คู่มือการสร้างกฎ
จัดทุกอย่างให้เป็นระเบียบอยู่เสมอด้วยคอลเล็กชัน
บันทึกและจัดหมวดหมู่เนื้อหาตามค่ากำหนดของคุณ
บทนำ
คุณสามารถใช้ Sandboxed API (SAPI) กับระบบบิลด์ Bazel ของ Google หรือกับระบบบิลด์เมตา 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 ปกติเป็นเป้าหมายของ Host Code ประกอบด้วย
zlib_sapi.bin และการขึ้นต่อกันของแซนด์บ็อกซ์
- name.interface: อินเทอร์เฟซของไลบรารีที่สร้างขึ้น
- name.embed:
cc_embed_data() เป้าหมายที่ใช้ฝัง
Sandboxee ในไบนารี ดู
bazel/embed_data.bzl
- name.bin: ไบนารี Sandboxee ประกอบด้วย Stub การสื่อสารขนาดเล็กและ
ไลบรารีที่กำลังแซนด์บ็อกซ์
อาร์กิวเมนต์
| Attributes |
|---|
| ชื่อ |
ชื่อ; ต้องระบุ
ชื่อที่ไม่ซ้ำกันสำหรับเป้าหมายนี้ ซึ่งจะระบุไลบรารี C/C++
ที่อยู่ในแซนด์บ็อกซ์ ดูเป้าหมายเอาต์พุต name-sapi
|
| deps |
รายการ
ป้ายกำกับ (ไม่บังคับ)
รายการไลบรารีอื่นๆ ที่จะลิงก์ไปยังไลบรารี C/C++
ในแซนด์บ็อกซ์
|
| srcs |
รายการ
ป้ายกำกับ (ไม่บังคับ)
รายการไฟล์ C และ C++ ที่ประมวลผลเพื่อสร้างไลบรารี C/C++ แบบแซนด์บ็อกซ์
ซึ่งเป็นไฟล์ต้นฉบับและไฟล์ส่วนหัวของ C/C++ ไม่ว่าจะเป็น
ไฟล์ที่ไม่ได้สร้าง (ซอร์สโค้ดปกติ) หรือไฟล์ที่สร้างขึ้น
ดูข้อมูลเพิ่มเติมได้ที่คำอธิบายแอตทริบิวต์ srcs ใน
เอกสารประกอบ cc_library
|
| hdrs |
รายการ
ป้ายกำกับ (ไม่บังคับ)
รายการไฟล์ส่วนหัวที่ประมวลผลเพื่อสร้างไลบรารี C/C++ ที่อยู่ในแซนด์บ็อกซ์
นี่คือตำแหน่งที่ควรวางคำจำกัดความแซนด์บ็อกซ์ (sandbox.h) เว้นว่างไว้
หากใช้ไลบรารี SAPI แบบฝัง และนโยบายแซนด์บ็อกซ์เริ่มต้น
เพียงพอ
|
| ฝัง |
บูลีน ไม่บังคับ ค่าเริ่มต้นคือ True
หากเป็นจริง ควรฝังไลบรารีที่อยู่ในแซนด์บ็อกซ์ไว้ภายในโค้ดโฮสต์ ซึ่งจะช่วยให้เริ่มต้นแซนด์บ็อกซ์ SAPI ด้วย
ตัวสร้าง ::sapi::Sandbox::Sandbox(FileToc*) ได้
|
| ฟังก์ชัน |
รายการชื่อฟังก์ชัน (ไม่บังคับ)
รายการฟังก์ชันจากไลบรารี C/C++ ที่มีการสร้างเวอร์ชันแซนด์บ็อกซ์
และสามารถใช้ในโค้ดโฮสต์ได้
รายการที่ว่างเปล่าจะพยายามส่งออกและรวมฟังก์ชันทั้งหมดที่พบใน
ไลบรารี
|
| lib |
สตริง; ต้องระบุ
ชื่อของเป้าหมายไลบรารี C/C++ ซึ่งจะเป็นไลบรารีแซนด์บ็อกซ์
ซึ่งคาดว่าคุณจะมีกฎการสร้าง cc_library สำหรับไลบรารี C/C++
ในโปรเจ็กต์
|
| lib_name |
สตริง; ต้องระบุ
ชื่อของออบเจ็กต์ SAPI ซึ่งใช้เพื่อพร็อกซีฟังก์ชันไลบรารี
จากแอตทริบิวต์ฟังก์ชัน การเรียกฟังก์ชันใน
ไลบรารีแซนด์บ็อกซ์จะเกิดขึ้นผ่านออบเจ็กต์ SAPI
|
| input_files |
รายการ
ป้ายกำกับ (ไม่บังคับ)
รายการไฟล์ C และ C++ ที่ประมวลผลระหว่างการเรียกใช้ภายใน
ของกฎ sapi_interface เครื่องมือสร้างจะสแกนไฟล์เหล่านี้เพื่อหา
การประกาศฟังก์ชันของไลบรารี C/C++
โดยส่วนใหญ่ไม่จำเป็นต้องทำเช่นนี้ เนื่องจากระบบจะสแกนส่วนหัวที่ส่งออกจากไลบรารี C/C++ เสมอ
|
| เนมสเปซ |
สตริง ไม่บังคับ ค่าเริ่มต้นคือ sapigen
ตัวระบุเนมสเปซ C++ เพื่อวางออบเจ็กต์ SAPI ที่กำหนดโดย
lib_name
เนมสเปซเริ่มต้นคือ sapigen
|
สตริง ไม่บังคับ
ชื่อของไฟล์ส่วนหัวที่จะใช้แทนไฟล์ส่วนหัวที่สร้างขึ้น
หากต้องการสร้างโค้ดโดยอัตโนมัติ อย่าใช้
แอตทริบิวต์นี้
|
| add_default_deps |
บูลีน ไม่บังคับ ค่าเริ่มต้นคือ True
เลิกใช้งานแล้ว
|
| limit_scan_depth |
บูลีน ไม่บังคับ ค่าเริ่มต้นคือ False
สำหรับไลบรารีที่ซับซ้อน จำนวนไฟล์สำหรับ Bazel อาจถึงขีดจำกัด
และกระบวนการบิลด์จะไม่สำเร็จ แอตทริบิวต์นี้เป็นทางออก
สำหรับสถานการณ์ที่ซับซ้อนเหล่านี้ อย่าใช้เว้นแต่
จำเป็น
|
| แท็ก |
ดูเอกสารประกอบของ Bazel สำหรับ
แท็ก
|
| การเปิดเผย |
ดูเอกสารประกอบของ 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 Developers Java เป็นเครื่องหมายการค้าจดทะเบียนของ Oracle และ/หรือบริษัทในเครือ
อัปเดตล่าสุด 2025-07-26 UTC
[[["เข้าใจง่าย","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 UTC"],[[["\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 )"]]
