מדריך כללי Build

מבוא

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

בקובץ BUILD.bazel יהיה לכם כלל build ליצירת קוד המארח. כדי שקוד המארח ישתמש בגרסת ארגז החול של ספרייה, עליך להכין יעד 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 הרגיל כיעד קוד המארח. הוא מורכב מיחסי תלות של zlib_sapi.bin ושל Sandbox.
• name.interface: ממשק הספרייה שנוצר.
• name.embed: יעד cc_embed_data() שמשמש להטמעת Sandboxee בקובץ הבינארי. מידע נוסף זמין בכתובת bazel/embed_data.bzl.
• name.bin: בינארי של Sandboxee מורכב מ-stub תקשורת קטן ומהספרייה שנמצאת בהרצה בארגז חול.

ארגומנטים

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

שימוש לדוגמה

הדוגמה של zlib היא פרויקט עזר טוב שמדגים את השימוש בכלל ה-build של 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",
)