מדריך כללי Build

מבוא

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

בקובץ BUILD.bazel יהיה כלל 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)

יעדי פלט

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

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

ארגומנטים

מאפיינים
שם	Name (שם); חובה שם ייחודי ליעד הזה. כך תזוהה ספריית C/C++‎ ב-sandbox, כפי שמוצג ביעד הפלט 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++ שיהיה הספרייה בסביבת ארגז חול. הפונקציה הזו מצפה שיהיה לכם כלל build של 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.
כותרת	מחרוזת; אופציונלי השם של קובץ הכותרת שבו רוצים להשתמש במקום קובץ הכותרת שנוצר. אם רוצים ליצור את הקוד באופן אוטומטי, לא משתמשים במאפיין הזה.
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",
)