.. _module-pw_third_party_emboss:

======
Emboss
======
`Emboss <https://github.com/google/emboss>`_ is a tool for generating code to
safely read and write binary data structures.

The ``$dir_pw_third_party/emboss`` module provides an ``emboss_cc_library`` GN
template, defined in build_defs.gni, which generates C++ bindings for the given
Emboss source file. The Emboss source code needs to be provided by the user.

------------------
Configuring Emboss
------------------
The recommended way to include the Emboss source code is to add it as a
Git submodule:

.. code-block:: sh

   git submodule add https://github.com/google/emboss.git third_party/emboss/src

Next, set the GN variable ``dir_pw_third_party_emboss`` to the path of your Emboss
installation. If using the submodule path from above, add the following to the
``default_args`` of your project's ``.gn`` file:

.. code-block::

   dir_pw_third_party_emboss = "//third_party/emboss/src"

..
   inclusive-language: disable

Optionally, configure the Emboss defines documented at
`dir_pw_third_party_emboss/runtime/cpp/emboss_defines.h
<https://github.com/google/emboss/blob/master/runtime/cpp/emboss_defines.h>`_
by setting the ``pw_third_party_emboss_CONFIG`` variable to a config that
overrides the defines. By default, checks will use PW_DCHECK.

..
   inclusive-language: enable

------------
Using Emboss
------------
Let's say you've authored an Emboss source file at ``//some/path/to/my-protocol.emb``.
To generate its bindings, you can add the following to ``//some/path/to/BUILD.gn``:

.. code-block::

  import("$dir_pw_third_party/emboss/build_defs.gni")

  emboss_cc_library("protocol") {
    source = "my-protocol.emb"
  }

This generates a source set of the same name as the target, in this case "protocol".
To use the bindings, list this target as a dependency in GN and include the generated
header by adding ``.h`` to the path of your Emboss source file:

.. code-block::

  #include <some/path/to/protocol.emb.h>