64 lines
1.9 KiB
ReStructuredText
64 lines
1.9 KiB
ReStructuredText
.. _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>
|