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

مقدمة

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

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

قواعد إنشاء 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: الهدف المستخدَم لتضمين 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.
header	سلسلة، اختيارية اسم ملف العنوان الذي سيتم استخدامه بدلاً من ملف العنوان الذي تم إنشاؤه. إذا كنت تريد إنشاء الرمز تلقائيًا، لا تستخدِم هذه السمة.
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",
)