Hướng dẫn tạo quy tắc

Giới thiệu

Bạn có thể sử dụng API trong hộp cát (SAPI) với hệ thống xây dựng Bazel của Google hoặc với hệ thống xây dựng meta CMake phổ biến. Trang này tập trung vào Bazel, nhưng các tính năng tương tự cũng có sẵn cho CMake. Bazel là hệ thống xây dựng được đề xuất và dễ tích hợp nhất.

Trong tệp BUILD.bazel, bạn sẽ có một quy tắc xây dựng để xây dựng Mã máy chủ. Để Mã máy chủ sử dụng phiên bản trong hộp cát của một thư viện, bạn cần chuẩn bị mục tiêu xây dựng mà Mã máy chủ sẽ sử dụng.

Quy tắc xây dựng 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)

Mục tiêu đầu ra

Quy tắc xây dựng sapi_library() tạo ra các mục tiêu sau:

  • name-sapi: Thư viện trong hộp cát, thay thế cc_library thông thường làm mục tiêu của Mã máy chủ. Bao gồm zlib_sapi.bin và các phần phụ thuộc trong hộp cát.
  • name.interface: Giao diện thư viện được tạo.
  • name.embed: Mục tiêu cc_embed_data() dùng để nhúng Sandboxee vào tệp nhị phân. Xem bazel/embed_data.bzl.
    • name.bin: Tệp nhị phân Sandboxee, bao gồm một đoạn mã giao tiếp nhỏ và thư viện đang được đặt trong hộp cát.

Đối số

Thuộc tính
tên

Tên; bắt buộc

Tên duy nhất cho mục tiêu này. Tên này sẽ xác định thư viện C/C++ trong hộp cát, hãy xem mục tiêu đầu ra name-sapi.

deps

Danh sách nhãn; không bắt buộc

Danh sách các thư viện khác sẽ được liên kết vào thư viện C/C++ trong hộp cát.

srcs

Danh sách nhãn; không bắt buộc

Danh sách các tệp C và C++ được xử lý để tạo thư viện C/C++ trong hộp cát. Đây là các tệp nguồn và tệp tiêu đề C/C++, hoặc không được tạo (mã nguồn thông thường) hoặc được tạo.

Để biết thêm thông tin, hãy xem phần giải thích về thuộc tính srcs trong tài liệu cc_library.

hdrs

Danh sách nhãn; không bắt buộc

Danh sách các tệp tiêu đề được xử lý để tạo thư viện C/C++ trong hộp cát.

Đây là nơi định nghĩa hộp cát (sandbox.h) sẽ được đặt; để trống nếu bạn sử dụng thư viện SAPI được nhúng và cấu hình hộp cát mặc định (DefaultConfig, sử dụng DefaultPolicyBuilder, DefaultFlags, DefaultEnvironmentVariables, và DefaultLimits) là đủ.

embed

Boolean; không bắt buộc; giá trị mặc định là True

Nếu là True, thư viện trong hộp cát sẽ được nhúng vào bên trong mã máy chủ code. Điều này cho phép khởi chạy Hộp cát SAPI bằng hàm khởi tạo ::sapi::Sandbox::Sandbox(FileToc*).

functions

Danh sách tên hàm; không bắt buộc

Danh sách các hàm trong thư viện C/C++ mà phiên bản trong hộp cát được tạo và sau đó có thể được sử dụng trong Mã máy chủ.

Danh sách trống sẽ cố gắng xuất và gói tất cả các hàm được tìm thấy trong thư viện.

lib

Chuỗi; bắt buộc

Tên của mục tiêu thư viện C/C++ sẽ là thư viện trong hộp cát.

Điều này giả định rằng bạn có quy tắc xây dựng cc_library cho thư viện C/C++ trong dự án.

lib_name

Chuỗi; bắt buộc

Tên của đối tượng SAPI được dùng để uỷ quyền các hàm thư viện từ thuộc tính functions. Mọi lệnh gọi đến hàm trong thư viện trong hộp cát sẽ diễn ra thông qua Đối tượng SAPI.

input_files

Danh sách nhãn; không bắt buộc

Danh sách các tệp C và C++ được xử lý trong quá trình chạy nội bộ của quy tắc sapi_interface. Trình tạo sẽ quét các tệp này để tìm các khai báo hàm của thư viện C/C++.

Việc này thường không cần thiết vì các tiêu đề đã xuất của thư viện C/C++ luôn được quét.

không gian tên

Chuỗi; không bắt buộc; giá trị mặc định là sapigen

Mã nhận dạng không gian tên C++ để đặt đối tượng SAPI do lib_name xác định vào.

Không gian tên mặc định là sapigen.

header

Chuỗi; không bắt buộc

Tên của tệp tiêu đề sẽ dùng thay cho tệp tiêu đề được tạo.

Nếu bạn muốn tự động tạo mã, đừng sử dụng thuộc tính này

add_default_deps

Boolean; không bắt buộc; giá trị mặc định là True

ĐÃ NGỪNG HOẠT ĐỘNG

limit_scan_depth

Boolean; không bắt buộc; giá trị mặc định là False

Đối với các thư viện phức tạp, số lượng tệp cho Bazel có thể đạt đến giới hạn và quá trình xây dựng sẽ không thành công. Thuộc tính này là một lối thoát cho những trường hợp phức tạp này. Đừng sử dụng trừ phi cần thiết.

thẻ

Xem tài liệu về Bazel để biết các thẻ.

chế độ hiển thị

Xem tài liệu về Bazel để biết chế độ hiển thị

Ví dụ về cách sử dụng

Ví dụ về zlib là một dự án tham chiếu hay cho thấy cách sử dụng quy tắc xây dựng 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",
)