构建规则指南
使用集合让一切井井有条
根据您的偏好保存内容并对其进行分类。
简介
沙盒 API (SAPI) 可与 Google 的 Bazel 构建系统或热门的 CMake 元构建系统搭配使用。本页重点介绍 Bazel，但 CMake 也提供相同的功能。Bazel 是推荐的构建系统，也是最容易集成的。
在 BUILD.bazel 文件中，您将拥有一个用于构建主机代码的 build 规则。为了让宿主代码使用库的沙盒版本，您需要准备一个宿主代码将要使用的 build 目标。
SAPI build 规则
sapi_library
sapi_library(name, deps, srcs, hdrs, embed, functions, lib, lib_name, input_files, namespace, header, add_default_deps, limit_scan_depth, visibility)
输出目标
sapi_library() build 规则会生成以下目标：
- name-sapi：沙盒库，替代了正常的 cc_library 作为宿主代码目标。由
zlib_sapi.bin 和沙盒依赖项组成。
- 名称.interface：生成的库接口。
- name.embed：用于在二进制文件中嵌入 Sandboxee 的
cc_embed_data() 目标。请参阅 bazel/embed_data.bzl。
- name.bin：Sandboxee 二进制文件，包含一个小型通信桩和正在沙盒化的库。
参数
| 属性 |
|---|
| name |
名称；必需
相应目标的唯一名称。这将标识沙盒化的 C/C++ 库，请参阅 name-sapi 输出目标。
|
| deps |
标签列表；可选
要链接到沙盒 C/C++ 库中的其他库的列表。
|
| srcs |
标签列表；可选
处理后可创建沙盒 C/C++ 库的 C 和 C++ 文件列表。这些是 C/C++ 源文件和头文件，可以是未生成的（常规源代码），也可以是生成的。
如需了解详情，请参阅
cc_library 文档中对属性 srcs 的说明。
|
| hdrs |
标签列表；可选
处理后用于创建沙盒 C/C++ 库的头文件列表。
这是放置沙盒定义 (sandbox.h) 的位置；如果使用嵌入式 SAPI 库，并且默认沙盒政策足够，则留空。
|
| 嵌入 |
布尔值；可选；默认值为 True
如果为 True，则沙盒库应嵌入到宿主代码中。这样一来，便可以使用 ::sapi::Sandbox::Sandbox(FileToc*) 构造函数初始化 SAPI 沙箱。
|
| 函数 |
函数名称列表；可选
C/C++ 库中已生成沙盒版本且可在宿主代码中使用的函数列表。
空列表将尝试导出并封装库中找到的所有函数。
|
| lib |
字符串；必需
将成为沙盒库的 C/C++ 库目标的名称。
这要求您在项目中为 C/C++ 库提供 cc_library build 规则。
|
| lib_name |
字符串；必需
用于代理来自 functions 属性的库函数的 SAPI 对象的名称。对沙盒库中函数的任何调用都将通过 SAPI 对象进行。
|
| input_files |
标签列表；可选
在 sapi_interface 规则的内部运行期间处理的 C 和 C++ 文件列表。生成器会扫描这些文件，以查找 C/C++ 库的函数声明。
这在大多数情况下是不需要的，因为 C/C++ 库的导出头文件始终会进行扫描。
|
| 命名空间 |
字符串；可选；默认值为 sapigen
一个 C++ 命名空间标识符，用于放置由 lib_name 定义的 SAPI 对象。
默认命名空间为 sapigen。
|
字符串；可选
要使用的头文件的名称，而不是生成的头文件。
如果您想自动生成代码，请勿使用此属性
|
| add_default_deps |
布尔值；可选；默认值为 True
已弃用
|
| limit_scan_depth |
布尔值；可选；默认值为 False
对于复杂的库，可能会达到 Bazel 的文件数上限，导致构建过程失败。此属性是应对这些复杂情况的应急方案。除非必要，否则请勿使用。
|
| 标记 |
请参阅 Bazel 文档，了解
标记。
|
| visibility |
请参阅 Bazel 文档，了解
可见性
|
用法示例
zlib 示例是一个很好的参考项目，展示了如何使用 sapi_library build 规则：
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",
)
如未另行说明，那么本页面中的内容已根据知识共享署名 4.0 许可获得了许可，并且代码示例已根据 Apache 2.0 许可获得了许可。有关详情，请参阅 Google 开发者网站政策。Java 是 Oracle 和/或其关联公司的注册商标。
最后更新时间 (UTC)：2025-07-26。
[[["易于理解","easyToUnderstand","thumb-up"],["解决了我的问题","solvedMyProblem","thumb-up"],["其他","otherUp","thumb-up"]],[["没有我需要的信息","missingTheInformationINeed","thumb-down"],["太复杂/步骤太多","tooComplicatedTooManySteps","thumb-down"],["内容需要更新","outOfDate","thumb-down"],["翻译问题","translationIssue","thumb-down"],["示例/代码问题","samplesCodeIssue","thumb-down"],["其他","otherDown","thumb-down"]],["最后更新时间 (UTC)：2025-07-26。"],[[["\u003cp\u003eSandboxed API (SAPI) integrates with Bazel and CMake, with Bazel being the recommended build system.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003esapi_library\u003c/code\u003e rule in Bazel is used to build sandboxed versions of libraries.\u003c/p\u003e\n"],["\u003cp\u003e\u003ccode\u003esapi_library\u003c/code\u003e generates targets like \u003ccode\u003ename-sapi\u003c/code\u003e for the sandboxed library and \u003ccode\u003ename.embed\u003c/code\u003e for embedding the Sandboxee.\u003c/p\u003e\n"],["\u003cp\u003eSeveral arguments in \u003ccode\u003esapi_library\u003c/code\u003e allow customization such as \u003ccode\u003efunctions\u003c/code\u003e to specify functions to sandbox and \u003ccode\u003elib\u003c/code\u003e to define the library target.\u003c/p\u003e\n"],["\u003cp\u003eAn example using zlib demonstrates the practical application of the \u003ccode\u003esapi_library\u003c/code\u003e rule.\u003c/p\u003e\n"]]],[],null,["Introduction\n\nSandboxed API (SAPI) can be used with Google's [Bazel](https://bazel.build/)\nbuild system, or with the popular [CMake](https://cmake.org/) meta build system.\nThis page focuses on Bazel, but the same features are available for CMake. Bazel\nis the recommended build system and the easiest to integrate with.\n\nIn your BUILD.bazel file you will have a build rule to build your Host Code. For\nthe Host Code to use the sandboxed version of a library, you need to prepare a\nbuild target that your Host Code will make use of.\n\nSAPI Build Rules\n\n- sapi_library\n\nsapi_library \n\n```\nsapi_library(name, deps, srcs, hdrs, embed, functions, lib, lib_name, input_files, namespace, header, add_default_deps, limit_scan_depth, visibility)\n```\n\nOutput Targets\n\nThe `sapi_library()` build rule generates the following targets:\n\n- *name-sapi* : Sandboxed library, substitutes the normal cc_library as the Host Code target. Consists of `zlib_sapi.bin` and sandbox dependencies.\n- *name*.interface: Generated library interface.\n- *name* .embed: `cc_embed_data()` target used to embed the Sandboxee in the binary. See [bazel/embed_data.bzl](https://github.com/google/sandboxed-api/blob/main/sandboxed_api/bazel/embed_data.bzl).\n - *name*.bin: Sandboxee binary, consists of a small communication stub and the library that is being sandboxed.\n\nArguments\n\n| Attributes ||\n|------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| name | [Name](https://docs.bazel.build/versions/main/build-ref.html#name); required A unique name for this target. This will identify the sandboxed C/C++ library, see the name-sapi output target. |\n| deps | List of [labels](https://docs.bazel.build/versions/main/build-ref.html#labels); optional A list of other libraries to be linked into the sandboxed C/C++ library. |\n| srcs | List of [labels](https://docs.bazel.build/versions/main/build-ref.html#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](https://docs.bazel.build/versions/main/be/c-cpp.html#cc_library.srcs). |\n| hdrs | List of [labels](https://docs.bazel.build/versions/main/build-ref.html#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. |\n| 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. |\n| 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. |\n| 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. |\n| 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. |\n| input_files | List of [labels](https://docs.bazel.build/versions/main/build-ref.html#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. |\n| 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*. |\n| 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 |\n| add_default_deps | Boolean; optional; default is True **DEPRECATED** |\n| 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. |\n| tags | See Bazel documentation for [tags](https://docs.bazel.build/versions/main/be/common-definitions.html#common.tags). |\n| visibility | See Bazel documentation for [visibility](https://docs.bazel.build/versions/main/be/common-definitions.html#common.visibility) |\n\nExample Use\n\nThe zlib example is a good reference project demonstrating how the sapi_library\nbuild rule is used: \n\n load(\n \"//sandboxed_api/tools/generator:sapi_generator.bzl\",\n \"sapi_library\",\n )\n\n sapi_library(\n name = \"zlib-sapi\",\n srcs = [], # Extra code compiled with the SAPI library\n hdrs = [], # Leave empty if embedded SAPI libraries are used, and the\n # default sandbox policy is sufficient.\n embed = True, # This is the default\n functions = [\n \"deflateInit_\",\n \"deflate\",\n \"deflateEnd\",\n ],\n lib = \"@zlib//:zlibonly\",\n lib_name = \"Zlib\",\n namespace = \"sapi::zlib\",\n )"]]
