คู่มือการสร้างกฎ

เกริ่นนำ

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 ปกติแทนเป้าหมายโค้ดโฮสต์ ประกอบด้วยทรัพยากร Dependency ของแซนด์บ็อกซ์ zlib_sapi.bin และ
• name.interface: อินเทอร์เฟซไลบรารีที่สร้างขึ้น
• name.embed: เป้าหมาย cc_embed_data() ที่ใช้เพื่อฝังแซนด์บ็อกซ์ในไบนารี โปรดดู bazel/embed_data.bzl
• name.bin: ไบนารีแซนด์บ็อกซ์ ประกอบด้วยต้นขั้วการสื่อสารขนาดเล็กและไลบรารีที่แซนด์บ็อกซ์อยู่

อาร์กิวเมนต์

Attributes
ชื่อ	Name ต้องระบุ ชื่อที่ไม่ซ้ำกันสำหรับเป้าหมายนี้ การดำเนินการนี้จะระบุไลบรารี C/C++ ที่ทำแซนด์บ็อกซ์ โปรดดูเป้าหมายเอาต์พุต name-sapi
Deps	รายการ ป้ายกำกับ ไม่บังคับ รายการไลบรารีอื่นๆ ที่จะลิงก์กับไลบรารี C/C++ ที่ทำแซนด์บ็อกซ์
src	รายการ ป้ายกำกับ ไม่บังคับ รายการไฟล์ C และ C++ ที่ได้รับการประมวลผลเพื่อสร้างไลบรารี C/C++ ที่ทำแซนด์บ็อกซ์ ไฟล์เหล่านี้เป็นไฟล์ต้นฉบับและส่วนหัว C/C++ ซึ่งอาจไม่ได้สร้างขึ้น (ซอร์สโค้ดปกติ) หรือสร้างขึ้น ดูคำอธิบายเพิ่มเติมของแอตทริบิวต์ src ใน เอกสาร cc_library
HDR	รายการ ป้ายกำกับ ไม่บังคับ รายการไฟล์ส่วนหัวที่มีการประมวลผลเพื่อสร้างไลบรารี C/C++ ที่ทำแซนด์บ็อกซ์ ช่องนี้ควรใส่คำจำกัดความแซนด์บ็อกซ์ (sandbox.h) ให้เว้นว่างไว้หากใช้ไลบรารี SAPI ที่ฝังและนโยบายแซนด์บ็อกซ์เริ่มต้นก็เพียงพอแล้ว
ฝัง	บูลีน ไม่บังคับ ค่าเริ่มต้นคือจริง หากเป็น "จริง" ควรฝังไลบรารีแซนด์บ็อกซ์ไว้ในโค้ดของโฮสต์ ซึ่งจะช่วยให้แซนด์บ็อกซ์ SAPI เริ่มต้นได้ด้วยตัวสร้าง ::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	บูลีน ไม่บังคับ ค่าเริ่มต้นคือจริง เลิกใช้งานแล้ว
limit_scan_depth	บูลีน ไม่บังคับ ค่าเริ่มต้นคือเท็จ สำหรับไลบรารีที่ซับซ้อน อาจมีการเข้าถึงจำนวนไฟล์ของ 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",
)