.. _module-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 and client code for   |
|             |                | nanopb. Requires a nanopb installation.       |
+-------------+----------------+-----------------------------------------------+
| Raw RPC     | ``raw_rpc``    | Compiles raw binary pw_rpc service code.      |
+-------------+----------------+-----------------------------------------------+

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", "go" ]

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

Two targets are created, named ``test_protos.pwpb`` and ``test_protos.go``,
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
    ]

    # Proto libraries depend on other proto libraries directly.
    deps = [ ":my_protos" ]
  }

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

    # When depending on protos in a source_set, specify the generator suffix.
    deps = [ ":my_other_protos.pwpb" ]
  }