Wyatt Hepler | f9fb90f | 2020-09-30 18:59:33 -0700 | [diff] [blame] | 1 | .. _module-pw_protobuf_compiler: |
Alexei Frolov | 4a257c1 | 2020-03-02 14:09:42 -0800 | [diff] [blame] | 2 | |
Alexei Frolov | 942adf0 | 2019-12-11 17:07:28 -0800 | [diff] [blame] | 3 | -------------------- |
| 4 | pw_protobuf_compiler |
| 5 | -------------------- |
Alexei Frolov | 942adf0 | 2019-12-11 17:07:28 -0800 | [diff] [blame] | 6 | The Protobuf compiler module provides build system integration and wrapper |
| 7 | scripts for generating source code for Protobuf definitions. |
| 8 | |
Alexei Frolov | f39cd8b | 2020-04-13 17:59:20 -0700 | [diff] [blame] | 9 | Generator support |
| 10 | ================= |
Alexei Frolov | f39cd8b | 2020-04-13 17:59:20 -0700 | [diff] [blame] | 11 | Protobuf code generation is currently supported for the following generators: |
Alexei Frolov | 942adf0 | 2019-12-11 17:07:28 -0800 | [diff] [blame] | 12 | |
Alexei Frolov | 79b7cb0 | 2020-07-06 13:51:43 -0700 | [diff] [blame] | 13 | +-------------+----------------+-----------------------------------------------+ |
| 14 | | Generator | Code | Notes | |
| 15 | +-------------+----------------+-----------------------------------------------+ |
| 16 | | pw_protobuf | ``pwpb`` | Compiles using ``pw_protobuf``. | |
| 17 | +-------------+----------------+-----------------------------------------------+ |
Alexei Frolov | 79b7cb0 | 2020-07-06 13:51:43 -0700 | [diff] [blame] | 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 | +-------------+----------------+-----------------------------------------------+ |
Alexei Frolov | c912ea7 | 2020-10-26 08:43:27 -0700 | [diff] [blame] | 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. | |
Alexei Frolov | 79b7cb0 | 2020-07-06 13:51:43 -0700 | [diff] [blame] | 26 | +-------------+----------------+-----------------------------------------------+ |
Alexei Frolov | a4c0aee | 2020-12-01 13:48:48 -0800 | [diff] [blame] | 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 | +-------------+----------------+-----------------------------------------------+ |
Alexei Frolov | 942adf0 | 2019-12-11 17:07:28 -0800 | [diff] [blame] | 33 | |
Alexei Frolov | 942adf0 | 2019-12-11 17:07:28 -0800 | [diff] [blame] | 34 | GN template |
| 35 | =========== |
Alexei Frolov | 942adf0 | 2019-12-11 17:07:28 -0800 | [diff] [blame] | 36 | The ``pw_proto_library`` GN template is provided by the module. |
| 37 | |
Alexei Frolov | b499d3f | 2020-10-28 13:00:08 -0700 | [diff] [blame] | 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++). |
Alexei Frolov | 942adf0 | 2019-12-11 17:07:28 -0800 | [diff] [blame] | 43 | |
Alexei Frolov | b499d3f | 2020-10-28 13:00:08 -0700 | [diff] [blame] | 44 | For example, given the following target: |
Alexei Frolov | 942adf0 | 2019-12-11 17:07:28 -0800 | [diff] [blame] | 45 | |
Alexei Frolov | b499d3f | 2020-10-28 13:00:08 -0700 | [diff] [blame] | 46 | .. code-block:: |
Alexei Frolov | 942adf0 | 2019-12-11 17:07:28 -0800 | [diff] [blame] | 47 | |
| 48 | pw_proto_library("test_protos") { |
Wyatt Hepler | d517afc | 2021-02-03 19:40:08 -0800 | [diff] [blame^] | 49 | sources = [ "my_test_protos/test.proto" ] |
Alexei Frolov | 942adf0 | 2019-12-11 17:07:28 -0800 | [diff] [blame] | 50 | } |
| 51 | |
Alexei Frolov | b499d3f | 2020-10-28 13:00:08 -0700 | [diff] [blame] | 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. |
Alexei Frolov | 942adf0 | 2019-12-11 17:07:28 -0800 | [diff] [blame] | 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 = [ |
Wyatt Hepler | d517afc | 2021-02-03 19:40:08 -0800 | [diff] [blame^] | 71 | "my_protos/foo.proto", |
| 72 | "my_protos/bar.proto", |
Alexei Frolov | 942adf0 | 2019-12-11 17:07:28 -0800 | [diff] [blame] | 73 | ] |
| 74 | } |
| 75 | |
| 76 | pw_proto_library("my_other_protos") { |
Wyatt Hepler | d517afc | 2021-02-03 19:40:08 -0800 | [diff] [blame^] | 77 | sources = [ "my_other_protos/baz.proto" ] # imports foo.proto |
Alexei Frolov | 8e30d46 | 2020-10-22 13:54:36 -0700 | [diff] [blame] | 78 | |
| 79 | # Proto libraries depend on other proto libraries directly. |
| 80 | deps = [ ":my_protos" ] |
Alexei Frolov | 942adf0 | 2019-12-11 17:07:28 -0800 | [diff] [blame] | 81 | } |
| 82 | |
| 83 | source_set("my_cc_code") { |
| 84 | sources = [ |
| 85 | "foo.cc", |
| 86 | "bar.cc", |
| 87 | "baz.cc", |
| 88 | ] |
Alexei Frolov | 8e30d46 | 2020-10-22 13:54:36 -0700 | [diff] [blame] | 89 | |
| 90 | # When depending on protos in a source_set, specify the generator suffix. |
| 91 | deps = [ ":my_other_protos.pwpb" ] |
Alexei Frolov | 942adf0 | 2019-12-11 17:07:28 -0800 | [diff] [blame] | 92 | } |
Wyatt Hepler | d517afc | 2021-02-03 19:40:08 -0800 | [diff] [blame^] | 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. |