Emboss

Pigweed AI summary: Emboss is a tool that generates code for reading and writing binary data structures. The $dir_pw_third_party/emboss module provides an emboss_cc_library GN template that generates C++ bindings for the given Emboss source file. To include the Emboss source code, it is recommended to add it as a Git submodule and set the GN variable dir_pw_third_party_emboss to the path of the Emboss installation. The Emboss defines can be configured by setting the pw_third_party_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

Pigweed AI summary: This section provides instructions for configuring Emboss source code by adding it as a Git submodule and setting the GN variable <literal>dir_pw_third_party_emboss</literal> to the path of the installation. It also suggests configuring Emboss defines by setting the <literal>pw_third_party_emboss_CONFIG</literal> variable to override the default defines.

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

Pigweed AI summary: This article explains how to use Emboss to generate bindings for an Emboss source file. To do this, you need to add code to the BUILD.gn file and list the generated source set as a dependency in GN. The article provides an example of how to do this and includes a code block for reference. Once the bindings are generated, you can include the generated header in your Emboss source file to use them.

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>