Emboss#
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:
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:
dir_pw_third_party_emboss = "//third_party/emboss/src"
Optionally, configure the Emboss defines documented at
dir_pw_third_party_emboss/runtime/cpp/emboss_defines.h
by setting the pw_third_party_emboss_CONFIG
variable to a source set that
includes a public config overriding the defines. By default, checks will
use PW_DASSERT.
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
:
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:
#include <some/path/to/protocol.emb.h>