Hướng dẫn tạo quy tắc
Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang
Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.
Giới thiệu
Bạn có thể sử dụng Sandboxed API (SAPI) với hệ thống xây dựng Bazel của Google hoặc với hệ thống xây dựng meta CMake phổ biến.
Trang này tập trung vào Bazel, nhưng các tính năng tương tự cũng có trong CMake. Bazel là hệ thống bản dựng được đề xuất và dễ tích hợp nhất.
Trong tệp BUILD.bazel, bạn sẽ có một quy tắc xây dựng để tạo Mã máy chủ lưu trữ. Để Mã máy chủ sử dụng phiên bản hộp cát của một thư viện, bạn cần chuẩn bị một mục tiêu bản dựng mà Mã máy chủ sẽ sử dụng.
Quy tắc xây dựng 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)
Mục tiêu đầu ra
Quy tắc tạo bản dựng sapi_library() sẽ tạo ra các mục tiêu sau:
- name-sapi: Thư viện được cách ly, thay thế cc_library thông thường làm mục tiêu Mã máy chủ. Bao gồm
zlib_sapi.bin và các phần phụ thuộc của hộp cát.
- name.interface: Giao diện thư viện được tạo.
- name.embed:
cc_embed_data() đích đến dùng để nhúng Sandboxee vào tệp nhị phân. Xem bazel/embed_data.bzl.
- name.bin: Tệp nhị phân Sandboxee, bao gồm một đoạn giao tiếp nhỏ và thư viện đang được đưa vào hộp cát.
Đối số
| Thuộc tính |
|---|
| tên |
Tên; bắt buộc
Tên riêng cho mục tiêu này. Thao tác này sẽ xác định thư viện C/C++ được cách ly, hãy xem đích đầu ra name-sapi.
|
| deps |
Danh sách nhãn ; không bắt buộc
Danh sách các thư viện khác sẽ được liên kết vào thư viện C/C++ được cách ly.
|
| srcs |
Danh sách nhãn ; không bắt buộc
Danh sách các tệp C và C++ được xử lý để tạo thư viện C/C++ trong hộp cát. Đây là các tệp nguồn và tệp tiêu đề C/C++, không được tạo (mã nguồn thông thường) hoặc được tạo.
Để biết thêm thông tin, hãy xem phần giải thích về thuộc tính srcs trong
tài liệu cc_library.
|
| hdrs |
Danh sách
nhãn; không bắt buộc
Danh sách các tệp tiêu đề được xử lý để tạo thư viện C/C++ được cách ly.
Đây là nơi bạn nên đặt định nghĩa hộp cát (sandbox.h); hãy để trống nếu bạn dùng thư viện SAPI nhúng và chính sách hộp cát mặc định là đủ.
|
| nhúng |
Boolean; không bắt buộc; mặc định là True
Nếu là True, thư viện được cách ly phải được nhúng bên trong mã máy chủ. Điều này cho phép SAPI Sandbox được khởi chạy bằng hàm dựng ::sapi::Sandbox::Sandbox(FileToc*).
|
| chức năng |
Danh sách tên hàm; không bắt buộc
Danh sách các hàm trong thư viện C/C++ mà phiên bản hộp cát được tạo và sau đó có thể dùng trong Mã máy chủ.
Một danh sách trống sẽ cố gắng xuất và bao bọc tất cả các hàm có trong thư viện.
|
| lib |
Chuỗi; bắt buộc
Tên của đích thư viện C/C++ sẽ là thư viện được tạo hộp cát.
Điều này giả định rằng bạn có một quy tắc xây dựng cc_library cho thư viện C/C++ trong dự án.
|
| lib_name |
Chuỗi; bắt buộc
Tên của đối tượng SAPI được dùng để làm proxy cho các hàm thư viện từ thuộc tính functions. Mọi lệnh gọi đến hàm trong thư viện được cách ly sẽ diễn ra thông qua Đối tượng SAPI.
|
| input_files |
Danh sách
nhãn; không bắt buộc
Danh sách các tệp C và C++ được xử lý trong quá trình chạy nội bộ của quy tắc sapi_interface. Trình tạo sẽ quét các tệp này để tìm khai báo hàm của thư viện C/C++.
Bạn thường không cần làm việc này vì các tiêu đề được xuất của thư viện C/C++ luôn được quét.
|
| không gian tên |
Chuỗi; không bắt buộc; mặc định là sapigen
Giá trị nhận dạng không gian tên C++ để đặt đối tượng SAPI do lib_name xác định vào.
Không gian tên mặc định là sapigen.
|
Chuỗi; không bắt buộc
Tên của tệp tiêu đề sẽ dùng thay cho tệp tiêu đề được tạo.
Nếu bạn muốn tự động tạo mã, đừng sử dụng thuộc tính này
|
| add_default_deps |
Boolean; không bắt buộc; mặc định là True
KHÔNG CÒN DÙNG NỮA
|
| limit_scan_depth |
Boolean; không bắt buộc; giá trị mặc định là False
Đối với các thư viện phức tạp, số lượng tệp cho Bazel có thể đạt đến giới hạn và quy trình tạo sẽ không thành công. Thuộc tính này là một lối thoát cho những tình huống phức tạp này. Không sử dụng trừ phi cần thiết.
|
| thẻ |
Xem tài liệu về Bazel để biết
thẻ.
|
| mức hiển thị |
Xem tài liệu về Bazel để biết
khả năng hiển thị
|
Ví dụ về cách sử dụng
Ví dụ về zlib là một dự án tham chiếu hữu ích minh hoạ cách sử dụng quy tắc tạo 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",
)
Trừ phi có lưu ý khác, nội dung của trang này được cấp phép theo Giấy phép ghi nhận tác giả 4.0 của Creative Commons và các mẫu mã lập trình được cấp phép theo Giấy phép Apache 2.0. Để biết thông tin chi tiết, vui lòng tham khảo Chính sách trang web của Google Developers. Java là nhãn hiệu đã đăng ký của Oracle và/hoặc các đơn vị liên kết với Oracle.
Cập nhật lần gần đây nhất: 2025-07-26 UTC.
[[["Dễ hiểu","easyToUnderstand","thumb-up"],["Giúp tôi giải quyết được vấn đề","solvedMyProblem","thumb-up"],["Khác","otherUp","thumb-up"]],[["Thiếu thông tin tôi cần","missingTheInformationINeed","thumb-down"],["Quá phức tạp/quá nhiều bước","tooComplicatedTooManySteps","thumb-down"],["Đã lỗi thời","outOfDate","thumb-down"],["Vấn đề về bản dịch","translationIssue","thumb-down"],["Vấn đề về mẫu/mã","samplesCodeIssue","thumb-down"],["Khác","otherDown","thumb-down"]],["Cập nhật lần gần đây nhất: 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 )"]]
