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

บทนำ

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

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

Attributes
name	ชื่อ; ต้องระบุ ชื่อที่ไม่ซ้ำกันสำหรับเป้าหมายนี้ ซึ่งจะระบุไลบรารี C/C++ แซนด์บ็อกซ์ ดูเป้าหมายเอาต์พุต name-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) เพียงพอ
embed	บูลีน; ไม่บังคับ; ค่าเริ่มต้นคือ True หากเป็น True ระบบควรฝังไลบรารีแซนด์บ็อกซ์ไว้ในโค้ดโฮสต์ ซึ่งจะช่วยให้เริ่มต้นแซนด์บ็อกซ์ SAPI ด้วย ::sapi::Sandbox::Sandbox(FileToc*) ตัวสร้างได้
functions	รายการชื่อฟังก์ชัน; ไม่บังคับ รายการฟังก์ชันจากไลบรารี C/C++ ที่สร้างเวอร์ชันแซนด์บ็อกซ์ และสามารถใช้ในโค้ดโฮสต์ได้ รายการที่ว่างเปล่าจะพยายามส่งออกและรวมฟังก์ชันทั้งหมดที่พบใน ไลบรารี
lib	สตริง; ต้องระบุ ชื่อเป้าหมายไลบรารี C/C++ ที่จะเป็น ไลบรารีแซนด์บ็อกซ์ ซึ่งคาดว่าคุณจะมีกฎบิลด์ cc_library สำหรับไลบรารี C/C++ ในโปรเจ็กต์
lib_name	สตริง; ต้องระบุ ชื่อออบเจ็กต์ SAPI ที่ใช้พร็อกซีฟังก์ชันไลบรารี จากแอตทริบิวต์ฟังก์ชัน การเรียกฟังก์ชันใน ไลบรารีแซนด์บ็อกซ์จะเกิดขึ้นผ่านออบเจ็กต์ SAPI
input_files	รายการป้ายกำกับ; ไม่บังคับ รายการไฟล์ C และ C++ ที่ประมวลผลระหว่างการเรียกใช้กฎ sapi_interface ภายใน เครื่องมือสร้างจะสแกนไฟล์เหล่านี้เพื่อหา การประกาศฟังก์ชันของไลบรารี C/C++ โดยส่วนใหญ่แล้วไม่จำเป็นเนื่องจากระบบจะสแกนส่วนหัวที่ส่งออกของไลบรารี C/C++ เสมอ
namespace	สตริง; ไม่บังคับ; ค่าเริ่มต้นคือ sapigen ตัวระบุเนมสเปซ C++ เพื่อวางออบเจ็กต์ SAPI ที่กำหนดโดย lib_name เนมสเปซเริ่มต้นคือ sapigen
header	สตริง; ไม่บังคับ ชื่อไฟล์ส่วนหัวที่จะใช้แทนไฟล์ส่วนหัวที่สร้างขึ้น หากต้องการสร้างโค้ดโดยอัตโนมัติ อย่าใช้ แอตทริบิวต์นี้
add_default_deps	บูลีน; ไม่บังคับ; ค่าเริ่มต้นคือ True เลิกใช้งานแล้ว
limit_scan_depth	บูลีน; ไม่บังคับ; ค่าเริ่มต้นคือ False สำหรับไลบรารีที่ซับซ้อน อาจมีการเข้าถึงจำนวนไฟล์สำหรับ Bazel และกระบวนการบิลด์จะไม่สำเร็จ แอตทริบิวต์นี้เป็นทางออก สำหรับสถานการณ์ที่ซับซ้อนเหล่านี้ อย่าใช้ เว้นแต่ จำเป็น
tags	ดูเอกสารประกอบของ Bazel สำหรับ แท็ก
visibility	ดูเอกสารประกอบของ 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",
)