راهنمای قوانین ساخت

مقدمه

از 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++ جعبه ایمنی را شناسایی می‌کند، هدف برونداد نام-سرویس کاربردی را ببینید.
deps	فهرست برچسب‌ها؛ اختیاری فهرست کتابخانه‌های دیگری که باید به کتابخانه C/C++ جعبه ایمنی پیوند داده شوند.
منابع	فهرست برچسب‌ها؛ اختیاری فهرستی از فایل‌های C و C++‎ که برای ایجاد کتابخانه C/C++‎ در محیط امن پردازش می‌شوند. این‌ها فایل‌های منبع و سرصفحه C/C++ هستند، یا تولیدنشده (کد منبع معمولی) یا تولیدشده. برای اطلاعات بیشتر، توضیح مشخصه srcs را در سند cc_library ببینید.
hdrs	فهرست برچسب‌ها؛ اختیاری فهرستی از فایل‌های سرایند که برای ایجاد کتابخانه C/C++‎ در محیط امن پردازش شده‌اند. اینجا جایی است که تعریف جعبه امن (sandbox.h) باید برود؛ اگر از کتابخانه SAPI جاسازی‌شده استفاده می‌شود و پیکربندی پیش‌فرض جعبه امن (DefaultConfig که از DefaultPolicyBuilder، DefaultFlags، DefaultEnvironmentVariables، و DefaultLimits استفاده می‌کند) کافی است، آن را خالی بگذارید.
جاسازی	بولی؛ اختیاری؛ پیش‌فرض «درست» است اگر «درست» باشد، کتابخانه جعبه ایمنی باید در کد میزبان جاسازی شود. این کار به SAPI Sandbox اجازه می‌دهد با سازنده ::sapi::Sandbox::Sandbox(FileToc*) مقداردهی اولیه شود.
توابع	فهرست نام‌های تابع؛ اختیاری فهرستی از توابع کتابخانه C/C++ که نسخه جعبه ایمنی برای آن‌ها تولید شده است و سپس می‌توانند در «کد میزبان» استفاده شوند. فهرست خالی سعی می‌کند همه عملکردهای موجود در کتابخانه را صادر و بسته‌بندی کند.
lib	رشته؛ الزامی نام هدف کتابخانه C/C++ که قرار است کتابخانه محیط امن باشد. این امر مستلزم آن است که قانون ساخت cc_library برای کتابخانه C/C++‎ در پروژه داشته باشید.
lib_name	رشته؛ الزامی نام شیء SAPI که برای پراکسی کردن توابع کتابخانه از ویژگی توابع استفاده می‌شود. هرگونه فراخوانی تابع در کتابخانه محدودشده ازطریق «شیء 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 configuration (DefaultConfig) is sufficient.
    embed = True,  # This is the default
    functions = [
        "deflateInit_",
        "deflate",
        "deflateEnd",
    ],
    lib = "@zlib//:zlibonly",
    lib_name = "Zlib",
    namespace = "sapi::zlib",
)