دليل قواعد الإنشاء
تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
مقدمة
يمكن استخدام واجهة برمجة التطبيقات Sandboxed API (SAPI) مع نظام الإنشاء Bazel من Google، أو مع نظام الإنشاء الوصفي الشائع CMake.
تركّز هذه الصفحة على Bazel، ولكن تتوفّر الميزات نفسها لـ CMake. Bazel
هو نظام الإنشاء الذي يُنصح به والأسهل في الدمج.
في ملف BUILD.bazel، سيكون لديك قاعدة إنشاء لإنشاء رمز المضيف. لكي يستخدم Host Code الإصدار المحمي من إحدى المكتبات، عليك إعداد هدف إنشاء سيستخدمه Host Code.
قواعد إنشاء 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: الهدف المستخدَم لتضمين
Sandboxee في الرمز الثنائي.
cc_embed_data() راجِع
bazel/embed_data.bzl.
- name.bin: ملف ثنائي لـ Sandboxee، ويتألف من جزء صغير من التعليمات البرمجية الخاصة بالاتصال والمكتبة التي يتم وضعها في وضع الحماية.
الوسيطات
| السمات |
|---|
| الاسم |
الاسم: مطلوب
اسم فريد لهذا الهدف سيحدّد هذا الإجراء مكتبة C/C++ المحصورة في بيئة الاختبار، ويُرجى الاطّلاع على هدف إخراج 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++ الذي سيصبح
المكتبة المحصورة.
ويفترض ذلك أنّه لديك قاعدة إنشاء 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 |
قيمة منطقية؛ اختيارية؛ القيمة التلقائية هي "خطأ"
بالنسبة إلى المكتبات المعقّدة، قد يتم الوصول إلى الحد الأقصى لعدد الملفات في 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 (حسب التوقيت العالمي المتفَّق عليه)
[[["يسهُل فهم المحتوى.","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 )"]]
