Build Rules Guide

Introduction

Sandboxed API (SAPI) can be used with Google's Bazel build system, or with the popular CMake meta build system. This page focuses on Bazel, but the same features are available for CMake. Bazel is the recommended build system and the easiest to integrate with.

In your BUILD.bazel file you will have a build rule to build your Host Code. For the Host Code to use the sandboxed version of a library, you need to prepare a build target that your Host Code will make use of.

SAPI Build Rules

  • sapi_library

sapi_library

sapi_library(name, deps, srcs, hdrs, embed, functions, lib, lib_name, input_files, namespace, header, add_default_deps, limit_scan_depth, visibility)

Output Targets

The sapi_library() build rule generates the following targets:

  • name-sapi: Sandboxed library, substitutes the normal cc_library as the Host Code target. Consists of zlib_sapi.bin and sandbox dependencies.
  • name.interface: Generated library interface.
  • name.embed: cc_embed_data() target used to embed the Sandboxee in the binary. See bazel/embed_data.bzl.
    • name.bin: Sandboxee binary, consists of a small communication stub and the library that is being sandboxed.

Arguments

Attributes
name

Name; required

A unique name for this target. This will identify the sandboxed C/C++ library, see the name-sapi output target.
deps

List of labels; optional

A list of other libraries to be linked into the sandboxed C/C++ library.
srcs

List of labels; optional

A list of C and C++ files that are processed to create the sandboxed C/C++ library. These are C/C++ source and header files, either non-generated (normal source code) or generated.

For more information, see the explanation of the attribute srcs in the cc_library documentation.
hdrs

List of labels; optional

A list of header files that are processed to create the sandboxed C/C++ library.

This is where the sandbox definition (sandbox.h) should go; leave empty if the embedded SAPI library is used, and the default sandbox policy is sufficient.
embed

Boolean; optional; default is True

If True, the sandboxed library should be embedded inside the host code. This allows the SAPI Sandbox to be initialized with the ::sapi::Sandbox::Sandbox(FileToc*) constructor.
functions

List of function names; optional

A list of functions from the C/C++ library for which a sandboxed version is generated and that can then be used in the Host Code.

An empty list will try to export and wrap all functions found in the library.
lib

String; required

The name of the C/C++ library target which is going to be the sandboxed library.

This expects that you have a cc_library build rule for the C/C++ library in the project.
lib_name

String; required

The name of the SAPI object which is used to proxy the library functions from the functions attribute. Any call to the function in the sandboxed library will happen via the SAPI Object.
input_files

List of labels; optional

A list of C and C++ files that are processed during the internal run of the sapi_interface rule. The generator scans these files for the C/C++ library's function declarations.

This is mostly not needed as the C/C++ library's exported headers are always scanned.
namespace

String; optional; default is sapigen

A C++ namespace identifier to place the SAPI object defined by lib_name into.

The default namespace is sapigen.
header

String; optional

The name of the header file to use instead of the generated header file.

If you want to auto-generate the code, do not use this attribute
add_default_deps

Boolean; optional; default is True

DEPRECATED
limit_scan_depth

Boolean; optional; default is False

For complex libraries, the file-count for Bazel might be reached and the build process will not succeed. This attribute is an escape hatch for these complex situations. Do not use unless necessary.
tags

See Bazel documentation for tags.
visibility

See Bazel documentation for visibility

Example Use

The zlib example is a good reference project demonstrating how the sapi_library build rule is used:

load(
    "//sandboxed_api/tools/generator:sapi_generator.bzl",
    "sapi_library",
)

sapi_library(
    name = "zlib-sapi",
    srcs = [],     # Extra code compiled with the SAPI library
    hdrs = [],     # Leave empty if embedded SAPI libraries are used, and the
                   # default sandbox policy is sufficient.
    embed = True,  # This is the default
    functions = [
        "deflateInit_",
        "deflate",
        "deflateEnd",
    ],
    lib = "@zlib//:zlibonly",
    lib_name = "Zlib",
    namespace = "sapi::zlib",
)