מדריך כללי Build

מבוא

אפשר להשתמש ב-Sandboxed API ‏ (SAPI) עם מערכת ה-build ‏Bazel של Google, או עם מערכת ה-meta build הפופולרית CMake. הדף הזה מתמקד ב-Bazel, אבל אותן תכונות זמינות גם ב-CMake. ‫Bazel היא מערכת ה-build המומלצת והכי קלה לשילוב.

בקובץ BUILD.bazel יהיה כלל build ליצירת קוד המארח. כדי שקוד המארח ישתמש בגרסת ארגז החול של הספרייה, צריך להכין יעד build שקוד המארח ישתמש בו.

כללי בנייה של 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)

יעדי פלט

כלל ה-build‏ sapi_library() יוצר את היעדים הבאים:

• ‫name-sapi: ספריית ארגז חול, מחליפה את cc_library הרגילה כיעד של Host Code. מורכב מ-zlib_sapi.bin ומיחסי תלות של ארגז חול.
• ‫name.interface: ממשק הספרייה שנוצר.
• ‫name.embed: cc_embed_data() היעד שמשמש להטמעת Sandboxee בקובץ הבינארי. ‫bazel/embed_data.bzl
  • ‫name.bin: קובץ בינארי של Sandboxee, שמורכב מ-stub קטן לתקשורת ומהספרייה שמופעלת בארגז החול.

ארגומנטים

מאפיינים
שם	שם; חובה שם ייחודי ליעד הזה. כך תזוהה ספריית C/C++‎ בארגז חול. אפשר לראות את יעד הפלט של שם ה-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) תספיק.
הטמעה	בוליאני; אופציונלי; ברירת המחדל היא True אם הערך הוא True, הספרייה בארגז החול צריכה להיות מוטמעת בתוך קוד המארח. כך אפשר לאתחל את ארגז החול של SAPI באמצעות בנאי ::sapi::Sandbox::Sandbox(FileToc*).
פונקציות	רשימה של שמות פונקציות; אופציונלי רשימה של פונקציות מספריית C/C++‎ שנוצרת להן גרסה בארגז חול (sandbox) ואפשר להשתמש בהן בקוד המארח. רשימה ריקה תנסה לייצא ולעטוף את כל הפונקציות שנמצאות בספרייה.
lib	מחרוזת; חובה השם של יעד הספרייה C/C++‎ שיהיה הספרייה בסביבת ארגז חול. הפונקציה הזו מניחה שיש לכם כלל build של cc_library לספריית C/C++‎ בפרויקט.
lib_name	מחרוזת; חובה השם של אובייקט ה-SAPI שמשמש כשרת proxy לפונקציות הספרייה מהמאפיין 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	בוליאני; אופציונלי; ברירת המחדל היא 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",
)