دليل قواعد الإنشاء

مقدمة

يمكن استخدام واجهة برمجة التطبيقات Sandboxed API (SAPI) مع نظام الإنشاء Bazel من Google، أو مع نظام الإنشاء الوصفي CMake الرائج. تركز هذه الصفحة على Bazel، ولكن تتوفر الميزات نفسها لـ CMake. Bazel هو نظام الإنشاء الموصى به والأسهل في الدمج.

في ملف BUILD.bazel، سيكون لديك قاعدة إصدار لإنشاء كود المضيف الخاص بك. لكي يستخدم رمز المضيف إصدار المكتبة المحمي في وضع الحماية، يجب إعداد هدف إصدار سيستخدمه رمز المضيف.

قواعد إصدار SAPI

• sapi_library

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++ ذات وضع الحماية، ويمكنك الاطّلاع على هدف الإخراج name-sapi.
أقسام	قائمة التصنيفات، اختيارية قائمة بالمكتبات الأخرى المطلوب ربطها بمكتبة C/C++ ذات وضع الحماية.
srcs	قائمة التصنيفات، اختيارية قائمة بملفات C وC++ التي تتم معالجتها لإنشاء مكتبة C/C++ الموضوعة في وضع الحماية. وهذه الملفات هي ملفات المصدر والعناوين C/C++ ، إمّا غير مُنشأة (رمز مصدر عادي) أو تم إنشاؤها. لمزيد من المعلومات، اطّلِع على شرح السمة srcs في المستندات الخاصة بـ cc_library.
دقة عالية	قائمة التصنيفات، اختيارية قائمة بملفات العناوين التي تتم معالجتها لإنشاء مكتبة C/C++ الموضوعة في وضع الحماية هذا هو المكان الذي يجب أن يظهر فيه تعريف وضع الحماية (sandbox.h)، واتركه فارغًا في حال استخدام مكتبة SAPI المضمّنة، وكانت سياسة وضع الحماية التلقائية كافية.
تضمين	منطقي، اختياري، القيمة التلقائية هي True في حال ضبط هذه السياسة على "صحيح"، يجب تضمين المكتبة المحمية في وضع الحماية داخل رمز المضيف. ويسمح هذا الإجراء بإعداد SAPI Sandbox باستخدام الدالة الإنشائية ::sapi::Sandbox::Sandbox(FileToc*).
الدوال	قائمة أسماء الدوال؛ اختيارية قائمة بدوال من مكتبة C/C++ يتم إنشاء إصدار لها في وضع الحماية ويمكن استخدامها بعد ذلك في رمز المضيف (Host Code) ستحاول قائمة فارغة تصدير جميع الدوال المتوفّرة في المكتبة والتفافها.
lib	سلسلة؛ مطلوبة تمثّل هذه السمة اسم هدف مكتبة C/C++ الذي ستكون المكتبة مشمولة في وضع الحماية. ومن المتوقّع أن يكون لديك قاعدة إصدار cc_library لمكتبة C/C++ في المشروع.
lib_name	سلسلة؛ مطلوبة تمثّل هذه السمة اسم كائن SAPI الذي يتم استخدامه لخادم وكيل لدوال المكتبة من سمة الدوال. وسيتم تنفيذ أي استدعاء للدالة في المكتبة الموضوعة في وضع الحماية من خلال كائن SAPI.
input_files	قائمة التصنيفات، اختيارية قائمة بملفات C وC++ تتم معالجتها أثناء التشغيل الداخلي لقاعدة sapi_interface. يفحص المنشئ هذه الملفات بحثًا عن تعريفات الدوال في مكتبة C/C++. ولا يلزم إجراء ذلك في الغالب لأنّه يتم دائمًا فحص العناوين التي يتم تصديرها من مكتبة C/C++.
namespace	سلسلة؛ اختيارية؛ القيمة التلقائية هي sapigen معرّف مساحة اسم C++ لوضع عنصر SAPI المحدّد من خلال lib_name. مساحة الاسم التلقائية هي sapigen.
header	سلسلة؛ اختيارية اسم ملف العنوان المطلوب استخدامه بدلاً من ملف العنوان الذي تم إنشاؤه. إذا أردت إنشاء الرمز تلقائيًا، لا تستخدم هذه السمة.
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",
)