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>