xref: /aosp_15_r20/external/pigweed/third_party/emboss/docs.rst (revision 61c4878ac05f98d0ceed94b57d316916de578985) 
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
23.. tab-set::
24
25   .. tab-item:: GN
26
27      Next, set the GN variable ``dir_pw_third_party_emboss`` to the path of
28      your Emboss installation. If using the submodule path from above, add the
29      following to the ``default_args`` of your project's ``.gn`` file:
30
31      .. code-block::
32
33         dir_pw_third_party_emboss = "//third_party/emboss/src"
34
35      ..
36         inclusive-language: disable
37
38      Optionally, configure the Emboss defines documented at
39      `dir_pw_third_party_emboss/runtime/cpp/emboss_defines.h
40      <https://github.com/google/emboss/blob/master/runtime/cpp/emboss_defines.h>`_
41      by setting the ``pw_third_party_emboss_CONFIG`` variable to a source set
42      that includes a public config overriding the defines. By default, checks
43      will use PW_DASSERT.
44
45      ..
46         inclusive-language: enable
47
48   .. tab-item:: CMake
49
50      Next, set the CMake variable ``dir_pw_third_party_emboss`` to the path of
51      your Emboss installation. If using the submodule path from above, add the
52      following to your project's ``CMakeLists.txt`` file:
53
54      .. code-block::
55
56         set(dir_pw_third_party_emboss "$ENV{PW_ROOT}/third_party/emboss/src" CACHE PATH "" FORCE)
57
58
59------------
60Using Emboss
61------------
62.. tab-set::
63
64   .. tab-item:: GN
65
66      Let's say you've authored an Emboss source file at
67      ``//my-project/public/my-project/my-protocol.emb``.
68      To generate its bindings, you can add the following to
69      ``//my-project/BUILD.gn``:
70
71      .. code-block::
72
73         import("$dir_pw_third_party/emboss/build_defs.gni")
74
75         emboss_cc_library("emboss_protocol") {
76            source = "public/my-project/my-protocol.emb"
77         }
78
79      This generates a source set of the same name as the target, in this case
80      "emboss_protocol". To use the bindings, list this target as a dependency
81      in GN:
82
83      .. code-block::
84
85         pw_test("emboss_test") {
86            sources = [ "emboss_test.cc" ]
87            deps = [
88               ":emboss_protocol",
89            ]
90         }
91
92   .. tab-item:: CMake
93
94      Let's say you've authored an Emboss source file at
95      ``my-project/public/my-project/my-protocol.emb``.
96      To generate its bindings, you can add the following to
97      ``my-project/CMakeLists.txt``:
98
99      .. code-block::
100
101         include($ENV{PW_ROOT}/third_party/emboss/emboss.cmake)
102
103         emboss_cc_library(emboss_protocol
104           SOURCES
105             source = "public/my-project/my-protocol.emb"
106         )
107
108      This generates a library of the same name as the target, in this case
109      "emboss_protocol". To use the bindings, list this target as a dependency
110      in CMake:
111
112      .. code-block::
113
114         pw_add_test(emboss_test
115            SOURCES
116               emboss_test.cc
117            PRIVATE_DEPS
118               emboss_protocol
119         )
120
121Now just include the generated header by adding ``.h`` to the path of your
122Emboss source file:
123
124.. code-block:: c++
125
126   #include <my-project/my-protocol.emb.h>
127