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
|
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",
)