建構規則指南
透過集合功能整理內容
你可以依據偏好儲存及分類內容。
簡介
沙箱化 API (SAPI) 可搭配 Google 的 Bazel 建構系統，或搭配熱門的 CMake 中繼建構系統使用。本頁面著重於 Bazel，但 CMake 也提供相同功能。建議使用 Bazel 建構系統，因為最容易整合。
在 BUILD.bazel 檔案中，您會有建構主機程式碼的建構規則。如要讓主機程式碼使用程式庫的沙箱版本，您需要準備主機程式碼會使用的建構目標。
SAPI 建構規則
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() 建構規則會產生下列目標：
- name-sapi：沙箱程式庫，可取代一般 cc_library 做為主機程式碼目標。由
zlib_sapi.bin 和沙箱依附元件組成。
- name.interface：產生的程式庫介面。
- name.embed：
cc_embed_data() 用於在二進位檔中嵌入 Sandboxee 的目標。請參閱 bazel/embed_data.bzl。
- name.bin：Sandboxee 二進位檔，由小型通訊存根和受沙箱保護的程式庫組成。
引數
| 屬性 |
|---|
| 名稱 |
名稱 (必填)
這個目標的專屬名稱。這會識別沙箱化的 C/C++ 程式庫，請參閱名稱 SAPI 輸出目標。
|
| deps |
標籤清單；選用
要連結至沙箱 C/C++ 程式庫的其他程式庫清單。
|
| srcs |
標籤清單 (選用)
系統會處理 C 和 C++ 檔案清單，建立沙箱化的 C/C++ 程式庫。這些是 C/C++ 來源和標頭檔案，可以是未產生 (一般原始碼) 或已產生。
詳情請參閱
cc_library 說明文件中 srcs 屬性的說明。
|
| hdrs |
標籤清單 (選用)
系統會處理標頭檔案清單，以建立沙箱 C/C++ 程式庫。
沙箱定義 (sandbox.h) 應位於此處；如果使用內嵌的 SAPI 程式庫，且預設沙箱政策足夠，請留空。
|
| 嵌入 |
布林值；選用；預設值為 True
如果為 True，沙箱化程式庫應內嵌於主機程式碼中。這樣一來，SAPI Sandbox 就能使用 ::sapi::Sandbox::Sandbox(FileToc*) 建構函式初始化。
|
| 函式 |
函式名稱清單 (選用)
C/C++ 程式庫中的函式清單，其中會產生沙箱版本，然後可在主機程式碼中使用。
空白清單會嘗試匯出並包裝程式庫中找到的所有函式。
|
| lib |
字串；必填
C/C++ 程式庫目標的名稱，該目標將成為沙箱程式庫。
這項操作的前提是，您已在專案中為 C/C++ 程式庫建立 cc_library 建構規則。
|
| lib_name |
字串；必填
SAPI 物件的名稱，用於從函式屬性代理程式庫函式。對沙箱程式庫中函式的任何呼叫，都會透過 SAPI 物件進行。
|
| input_files |
標籤清單 (選用)
在 sapi_interface 規則的內部執行期間處理的 C 和 C++ 檔案清單。產生器會掃描這些檔案，找出 C/C++ 程式庫的函式宣告。
C/C++ 程式庫匯出的標頭一律會掃描，因此通常不需要這麼做。
|
| 命名空間 |
字串；選用；預設為 sapigen
C++ 命名空間 ID，用於放置 lib_name 定義的 SAPI 物件。
預設命名空間為 sapigen。
|
字串；選用
要使用的標頭檔案名稱，而非產生的標頭檔案。
如要自動產生程式碼，請勿使用這項屬性
|
| add_default_deps |
布林值；選用；預設值為 True
DEPRECATED
|
| limit_scan_depth |
布林值；選用；預設值為 False
如果是複雜的程式庫，可能會達到 Bazel 的檔案數上限，導致建構程序失敗。這項屬性是這些複雜情況的應變措施。除非必要，否則請勿使用。
|
| 標記 |
請參閱 Bazel 說明文件中的
標記。
|
| 顯示設定 |
請參閱 Bazel 說明文件，瞭解
可見性
|
使用範例
zlib 範例是很好的參考專案，可說明如何使用 sapi_library 建構規則：
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",
)
除非另有註明，否則本頁面中的內容是採用創用 CC 姓名標示 4.0 授權，程式碼範例則為阿帕契 2.0 授權。詳情請參閱《Google Developers 網站政策》。Java 是 Oracle 和/或其關聯企業的註冊商標。
上次更新時間：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"]],["上次更新時間：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 )"]]
