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 config that overrides the defines. By default, checks will use PW_DCHECK.

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>