pw_protobuf_compiler/docs.rst

.. default-domain:: py

.. highlight:: py

.. _chapter-pw-protobuf-compiler:

--------------------
pw_protobuf_compiler
--------------------

The Protobuf compiler module provides build system integration and wrapper
scripts for generating source code for Protobuf definitions.

Generator support
=================

Protobuf code generation is currently supported for the following generators:

+-------------+----------------+-----------------------------------------------+
| Generator   | Code           | Notes                                         |
+-------------+----------------+-----------------------------------------------+
| pw_protobuf | ``pwpb``       | Compiles using ``pw_protobuf``.               |
+-------------+----------------+-----------------------------------------------+
| Go          | ``go``         | Compiles using the standard Go protobuf       |
|             |                | plugin with gRPC service support.             |
+-------------+----------------+-----------------------------------------------+
| Nanopb      | ``nanopb``     | Compiles using Nanopb. The build argument     |
|             |                | ``dir_pw_third_party_nanopb`` must be set to  |
|             |                | point to a local nanopb installation.         |
+-------------+----------------+-----------------------------------------------+
| Nanopb RPC  | ``nanopb_rpc`` | Compiles pw_rpc service code for a nanopb     |
|             |                | server. Requires the nanopb generator to be   |
|             |                | configured as well.                           |
+-------------+----------------+-----------------------------------------------+

The build variable ``pw_protobuf_GENERATORS`` tells the module the generators
for which it should compile code. It is defined as a list of generator codes.

GN template
===========

The ``pw_proto_library`` GN template is provided by the module.

It tells the build system to compile a set of source proto files to a library in
each chosen generator. A different target is created for each generator, with
the generator's code appended as a suffix to the template's target name.

For example, given the definitions:

.. code::

  pw_protobuf_GENERATORS = [ "pwpb", "py" ]

  pw_proto_library("test_protos") {
    sources = [ "test.proto" ]
  }

Two targets are created, named ``test_protos_pwpb`` and ``test_protos_py``,
containing the generated code from their respective generators.

**Arguments**

* ``sources``: List of ``.proto`` files.
* ``deps``: Other ``pw_proto_library`` targets that this one depends on.

**Example**

.. code::

  import("$dir_pw_protobuf_compiler/proto.gni")

  pw_proto_library("my_protos") {
    sources = [
      "foo.proto",
      "bar.proto",
    ]
  }

  pw_proto_library("my_other_protos") {
    sources = [
      "baz.proto", # imports foo.proto
    ]
    deps = [
      ":my_protos",
    ]
  }

  source_set("my_cc_code") {
    sources = [
      "foo.cc",
      "bar.cc",
      "baz.cc",
    ]
    deps = [
      ":my_other_protos_cc",
    ]
  }