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

บทนำ

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

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

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

ตัวอย่างการใช้งาน

ตัวอย่าง zlib เป็นโปรเจ็กต์อ้างอิงที่ดีที่แสดงให้เห็นวิธีใช้กฎ sapi_library build

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",
)