third_party/pigweed/repo/pw_protobuf_compiler/docs.rst

   1 .. _module-pw_protobuf_compiler:
   2
   3 --------------------
   4 pw_protobuf_compiler
   5 --------------------
   6 The Protobuf compiler module provides build system integration and wrapper
   7 scripts for generating source code for Protobuf definitions.
   8
   9 Generator support
  10 =================
  11 Protobuf code generation is currently supported for the following generators:
  12
  13 +-------------+----------------+-----------------------------------------------+
  14 | Generator   | Code           | Notes                                         |
  15 +-------------+----------------+-----------------------------------------------+
  16 | pw_protobuf | ``pwpb``       | Compiles using ``pw_protobuf``.               |
  17 +-------------+----------------+-----------------------------------------------+
  18 | Nanopb      | ``nanopb``     | Compiles using Nanopb. The build argument     |
  19 |             |                | ``dir_pw_third_party_nanopb`` must be set to  |
  20 |             |                | point to a local nanopb installation.         |
  21 +-------------+----------------+-----------------------------------------------+
  22 | Nanopb RPC  | ``nanopb_rpc`` | Compiles pw_rpc service and client code for   |
  23 |             |                | nanopb. Requires a nanopb installation.       |
  24 +-------------+----------------+-----------------------------------------------+
  25 | Raw RPC     | ``raw_rpc``    | Compiles raw binary pw_rpc service code.      |
  26 +-------------+----------------+-----------------------------------------------+
  27 | Go          | ``go``         | Compiles using the standard Go protobuf       |
  28 |             |                | plugin with gRPC service support.             |
  29 +-------------+----------------+-----------------------------------------------+
  30 | Python      | ``python``     | Compiles using the standard Python protobuf   |
  31 |             |                | plugin, creating a ``pw_python_package``.     |
  32 +-------------+----------------+-----------------------------------------------+
  33
  34 GN template
  35 ===========
  36 The ``pw_proto_library`` GN template is provided by the module.
  37
  38 It defines a collection of protobuf files that should be compiled together. The
  39 template creates a sub-target for each supported generator, named
  40 ``<target_name>.<generator>``. These sub-targets generate their respective
  41 protobuf code, and expose it to the build system appropriately (e.g. a
  42 ``pw_source_set`` for C/C++).
  43
  44 For example, given the following target:
  45
  46 .. code-block::
  47
  48   pw_proto_library("test_protos") {
  49     sources = [ "my_test_protos/test.proto" ]
  50   }
  51
  52 ``test_protos.pwpb`` compiles code for pw_protobuf, and ``test_protos.nanopb``
  53 compiles using Nanopb (if it's installed).
  54
  55 Protobuf code is only generated when a generator sub-target is listed as a
  56 dependency of another GN target.
  57
  58 **Arguments**
  59
  60 * ``sources``: List of ``.proto`` files.
  61 * ``deps``: Other ``pw_proto_library`` targets that this one depends on.
  62
  63 **Example**
  64
  65 .. code::
  66
  67   import("$dir_pw_protobuf_compiler/proto.gni")
  68
  69   pw_proto_library("my_protos") {
  70     sources = [
  71       "my_protos/foo.proto",
  72       "my_protos/bar.proto",
  73     ]
  74   }
  75
  76   pw_proto_library("my_other_protos") {
  77     sources = [ "my_other_protos/baz.proto" ]  # imports foo.proto
  78
  79     # Proto libraries depend on other proto libraries directly.
  80     deps = [ ":my_protos" ]
  81   }
  82
  83   source_set("my_cc_code") {
  84     sources = [
  85       "foo.cc",
  86       "bar.cc",
  87       "baz.cc",
  88     ]
  89
  90     # When depending on protos in a source_set, specify the generator suffix.
  91     deps = [ ":my_other_protos.pwpb" ]
  92   }
  93
  94 Proto file structure
  95 --------------------
  96 Protobuf source files must be nested under another directory when they are
  97 listed in sources. This ensures that they can be packaged properly in Python.
  98 The first directory is used as the Python package name.
  99
 100 The requirements for proto file structure in the source tree will be relaxed in
 101 future updates.
 102
 103 Working with externally defined protos
 104 --------------------------------------
 105 ``pw_proto_library`` targets may be used to build ``.proto`` sources from
 106 existing projects. In these cases, it may be necessary to supply the
 107 ``include_path`` argument, which specifies the protobuf include path to use for
 108 ``protoc``. If only a single external protobuf is being compiled, the
 109 requirement that the protobuf be nested under a directory is waived. This
 110 exception should only be used when absolutely necessary -- for example, to
 111 support proto files that includes ``import "nanopb.proto"`` in them.