1.. _module-pw_third_party_emboss: 2 3====== 4Emboss 5====== 6`Emboss <https://github.com/google/emboss>`_ is a tool for generating code to 7safely read and write binary data structures. 8 9The ``$dir_pw_third_party/emboss`` module provides an ``emboss_cc_library`` GN 10template, defined in build_defs.gni, which generates C++ bindings for the given 11Emboss source file. The Emboss source code needs to be provided by the user. 12 13------------------ 14Configuring Emboss 15------------------ 16The recommended way to include the Emboss source code is to add it as a 17Git submodule: 18 19.. code-block:: sh 20 21 git submodule add https://github.com/google/emboss.git third_party/emboss/src 22 23Next, set the GN variable ``dir_pw_third_party_emboss`` to the path of your Emboss 24installation. If using the submodule path from above, add the following to the 25``default_args`` of your project's ``.gn`` file: 26 27.. code-block:: 28 29 dir_pw_third_party_emboss = "//third_party/emboss/src" 30 31.. 32 inclusive-language: disable 33 34Optionally, configure the Emboss defines documented at 35`dir_pw_third_party_emboss/runtime/cpp/emboss_defines.h 36<https://github.com/google/emboss/blob/master/runtime/cpp/emboss_defines.h>`_ 37by setting the ``pw_third_party_emboss_CONFIG`` variable to a config that 38overrides the defines. By default, checks will use PW_DCHECK. 39 40.. 41 inclusive-language: enable 42 43------------ 44Using Emboss 45------------ 46Let's say you've authored an Emboss source file at ``//some/path/to/my-protocol.emb``. 47To generate its bindings, you can add the following to ``//some/path/to/BUILD.gn``: 48 49.. code-block:: 50 51 import("$dir_pw_third_party/emboss/build_defs.gni") 52 53 emboss_cc_library("protocol") { 54 source = "my-protocol.emb" 55 } 56 57This generates a source set of the same name as the target, in this case "protocol". 58To use the bindings, list this target as a dependency in GN and include the generated 59header by adding ``.h`` to the path of your Emboss source file: 60 61.. code-block:: 62 63 #include <some/path/to/protocol.emb.h> 64