PICOPBC(1)

NAME
picopbc - protocol buffers compiler

SYNOPSIS
picopbc [-c cfile] [-d dumpfile] [-G hguard] [-H hfilename] [-h hfile] [-s cmtstyle] proto

DESCRIPTION
picopbc reads a protocol buffers ‘.proto’ description from the file proto, or from standard input if proto is ‘-’, and compiles it.

The following options are available:

-c cfile
    Write C source code with run-time data describing protobuf messages in proto to cfile, or to standard output if cfile is ‘-’. This code is typically written to a file named foo.pb.c and compiled as an object in an application or library linked against libpicopb.

    The resulting C source code must include a header file for the corresponding message and enumeration structure definitions:

        #include...

    The header file name is inferred from the -h hfile option if it is not ‘-’, or may be set explicitly by the -H hfilename option. At least one of -h hfile or -H hfilename must be supplied.

-d dumpfile
    Dump the abstract syntax tree of proto to dumpfile, or to standard output if dumpfile is ‘-’. The format of the dump is not reliable. This option is intended for debugging only.

-G hguard
    Specify the name of the include guard for the C source code generated by the -h hfile option. See the -h hfile option for details.

-H hfilename
    Specify the name of the header file for the C source code generated by the -c cfile option to include. See the -c cfile option for details.

-h hfile
    Write C source code with struct and enum definitions for protobuf messages in proto to hfile, or to standard output if hfile is ‘-’. This code is typically written to a file named foo.pb.h and included with #include in.c files in an application or library.

    To protect against multiple inclusions, the resulting C source code is surrounded by an include guard:

        #ifndef FROBNITZ_PB_H
        #define FROBNITZ_PB_H

        ...

        #endif  /* FROBNITZ_PB_H */

    The name FROBNITZ_PB_H is by default derived from hfile, provided it is not ‘-’, but may be explicitly set or overridden with the -G hguard option.

    In either case, all uppercase US-ASCII letters are preserved, all lowercase US-ASCII letters are replaced by their uppercase equivalents, and all other characters are replaced by underscores.

    For example, if the user passes ‘-G zombie/brain-messenger.pb.h’, then the actual include guard will be ZOMBIE_BRAIN_MESSENGER_PB_H.

    Please note that names beginning with an underscore and uppercase US-ASCII letter are reserved to the C implementation, so do not use these as include guards.

-s cmtstyle
    Set the comment style for the syntax of proto. The following comment styles are available:

    c++ Line comments are written starting with two slashes, ‘//’, and non-nesting block comments are written between ‘/*’ and ‘*/’, as in C and C++.

    sh  Line comments are written starting with ‘#’, and block comments are not supported.

EXIT STATUS

EXAMPLES
Generate.c and.h files from a protobuf description:

    % picopbc -c wirefmt.pb.c -h wirefmt.pb.h wirefmt.proto
    % head -9 wirefmt.pb.h wirefmt.pb.h
    ==> wirefmt.pb.h <==
    /*
     * Stand back!
     * This file was automagically generated!
     */
    #ifndef WIREFMT_PB_H
    #define WIREFMT_PB_H
    #include <pb.h>
    ==> wirefmt.pb.c <==
    /*
     * Stand back!
     * This file was automagically generated!
     */
    #include <pb.h>
    #include "wirefmt.pb.h"
    %

Automatic suffix rules in a makefile to compile protobufs:

    PICOPBC = picopbc

    .SUFFIXES: .proto .pb.c .pb.h
    .proto.pb.c:
            $(PICOPBC) -H $*.pb.h -c $@.tmp $<  mv -f $@.tmp $@
    .proto.pb.h:
            $(PICOPBC) -G $*.pb.h -h $@.tmp $<  mv -f $@.tmp $@

Since picopbc always generates the same output for the same input, it is safe to run twice, once to generate the.c file and once to generate the.h file. This is helpful because make(1) is easily confused by rules that generate two files at once, as is historically the case for program-generating programs such as yacc(1).

SEE ALSO
libpicopb(3)

STANDARDS
The protobuf language and wire format is described informally at Google, Protocol Buffers: Developer Guide, https://developers.google.com/protocol-buffers/.

AUTHORS
Taylor R Campbell <campbell+picopb@mumble.net>

BUGS
There is no way to make the generated C code use ‘#include <...>’ to include a system header file instead of a local header file.

Various protobuf features are not (yet) supported:
•   oneofs (‘unions’)
•   message extensions
•   imports
•   packages
•   options
•   groups