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

مقدمة

يمكن استخدام واجهة برمجة التطبيقات المحصورة (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.
deps	قائمة بالتصنيفات ، اختيارية قائمة بالمكتبات الأخرى التي سيتم ربطها بمكتبة C/C++ المحصورة
srcs	قائمة بالتصنيفات ، اختيارية قائمة بملفات C وC++ التي تتم معالجتها لإنشاء مكتبة C/C++ المحصورة هذه هي ملفات مصدر C/C++ وملفات العنوان، إما غير منشأة (الرمز المصدر العادي) أو منشأة. لمزيد من المعلومات، راجِع شرح السمة srcs في مستندات cc_library.
hdrs	قائمة بالتصنيفات ، اختيارية قائمة بملفات العنوان التي تتم معالجتها لإنشاء مكتبة C/C++ المحصورة هذا هو المكان الذي يجب وضع تعريف وضع الحماية فيه (sandbox.h)، اتركه فارغًا إذا تم استخدام مكتبة SAPI المضمّنة وكانت إعدادات وضع الحماية التلقائية (DefaultConfig، التي تستخدم DefaultPolicyBuilder وDefaultFlags و DefaultEnvironmentVariables وDefaultLimits) كافية.
embed	قيمة منطقية، اختيارية، القيمة التلقائية هي True إذا كانت القيمة True، يجب تضمين المكتبة المحصورة داخل رمز المضيف. يسمح ذلك بتهيئة وضع حماية SAPI باستخدام الدالة الإنشائية ::sapi::Sandbox::Sandbox(FileToc*)
functions	قائمة بأسماء الدوال، اختيارية قائمة بالدوال من مكتبة C/C++ التي يتم إنشاء إصدار محصور لها ويمكن استخدامها بعد ذلك في رمز المضيف ستحاول القائمة الفارغة تصدير جميع الدوال التي تم العثور عليها في الـ مكتبة وتغليفها.
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 configuration (DefaultConfig) is sufficient.
    embed = True,  # This is the default
    functions = [
        "deflateInit_",
        "deflate",
        "deflateEnd",
    ],
    lib = "@zlib//:zlibonly",
    lib_name = "Zlib",
    namespace = "sapi::zlib",
)