מדריך כללי Build
קל לארגן דפים בעזרת אוספים
אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.
מבוא
אפשר להשתמש ב-Sandboxed API (SAPI) עם מערכת ה-build של Google Bazel או עם מערכת ה-meta build הפופולרית CMake.
הדף הזה מתמקד ב-Bazel, אבל אותן תכונות זמינות גם ב-CMake. Bazel היא מערכת הבנייה המומלצת, והיא הכי קלה לשילוב.
בקובץ BUILD.bazel יהיה כלל build ליצירת קוד המארח. כדי שקוד המארח ישתמש בגרסת ארגז החול של ספרייה, צריך להכין יעד בנייה שקוד המארח ישתמש בו.
כללי בנייה של 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, מורכב מ-stub קטן לתקשורת ומספרייה שנמצאת בארגז חול.
ארגומנטים
| מאפיינים |
|---|
| שם |
Name (שם); חובה
שם ייחודי ליעד הזה. כך תזוהה ספריית C/C++ ב-sandbox, כפי שמוצג ביעד הפלט name-sapi.
|
| deps |
רשימה של
תוויות; אופציונלי
רשימה של ספריות אחרות שיש לקשר לספריית C/C++ בארגז חול.
|
| srcs |
רשימה של
תוויות; אופציונלי
רשימה של קבצי C ו-C++ שעוברים עיבוד כדי ליצור את ספריית C/C++ בסביבת ארגז חול. אלה קובצי מקור וכותרות של C/C++, לא נוצרו (קוד מקור רגיל) או נוצרו.
מידע נוסף זמין בהסבר על מאפיין ה-srcs ב
מסמכי התיעוד של cc_library.
|
| hdrs |
רשימה של
תוויות; אופציונלי
רשימה של קובצי כותרות שעוברים עיבוד כדי ליצור את ספריית C/C++ בסביבת ארגז חול.
כאן צריך להזין את הגדרת ארגז החול (sandbox.h). אם משתמשים בספריית SAPI המוטמעת ומדיניות ברירת המחדל של ארגז החול מספיקה, צריך להשאיר את השדה ריק.
|
| להטמיע |
ערך בוליאני; אופציונלי; ברירת המחדל היא True
אם הערך הוא True, הספרייה שמוגבלת לארגז חול צריכה להיות מוטמעת בתוך קוד המארח. הפעולה הזו מאפשרת לאתחל את ארגז החול של SAPI באמצעות הבונה ::sapi::Sandbox::Sandbox(FileToc*).
|
| פונקציות |
רשימה של שמות פונקציות; אופציונלי
רשימה של פונקציות מהספרייה C/C++ שעבורן נוצרת גרסה בסביבת ארגז חול, שאפשר להשתמש בה בקוד המארח.
רשימה ריקה תנסה לייצא ולעטוף את כל הפונקציות שנמצאות בספרייה.
|
| lib |
מחרוזת; חובה
השם של יעד ספריית C/C++ שיהיה הספרייה בסביבת ארגז חול.
הפונקציה הזו מצפה שיהיה לכם כלל build של cc_library עבור ספריית C/C++ בפרויקט.
|
| lib_name |
מחרוזת; חובה
השם של אובייקט SAPI שמשמש כפרוקסי לפונקציות של הספרייה מהמאפיין functions. כל קריאה לפונקציה בספרייה של ארגז החול תתבצע דרך אובייקט 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:
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",
)
אלא אם צוין אחרת, התוכן של דף זה הוא ברישיון Creative Commons Attribution 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 )"]]
