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

Giới thiệu

Bạn có thể dùng API 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 CMake có các tính năng tương tự. 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ó quy tắc tạo để tạo Mã máy chủ. Để Mã máy chủ sử dụng phiên bản hộp cát của thư viện, bạn cần chuẩn bị một đích bản dựng mà Mã máy chủ của bạn 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 tạo bản dựng sapi_library() tạo ra các mục tiêu sau:

  • name-sapi: Thư viện hộp cát, thay thế cc_library thông thường làm mục tiêu Mã máy chủ. Bao gồm zlib_sapi.bin và các phần phụ thuộc hộp cát.
  • name.interface: Giao diện thư viện đã 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 của Sandboxee, bao gồm một mã giả lập giao tiếp nhỏ và thư viện đang được tạo hộp cát.

Đối số

Thuộc tính
tên

Tên; bắt buộc

Tên dành riêng cho mục tiêu này. Thao tác này sẽ xác định thư viện C/C++ dạng hộp cát, hãy xem đích đầu ra name-sapi.
Phần phụ thuộc

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++ dạng hộp cát.
src

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++ có dạng hộp cát. Đây là các tệp tiêu đề và tệp nguồn C/C++, có thể là không được tạo (mã nguồn thông thường) hoặc đã tạo.

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

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++ có dạng hộp cát.

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

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

Nếu là True, thư viện hộp cát sẽ được nhúng vào trong mã máy chủ. Việc 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*).
hàm

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

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

Một danh sách trống sẽ cố gắng xuất và gói tất cả hàm có 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ẽ trở thành thư viện hộp cát.

Do đó, bạn cần có một quy tắc tạo 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 để proxy các hàm của thư viện từ thuộc tính hàm. Mọi lệnh gọi đến hàm trong thư viện hộp cát đều sẽ xảy 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 quy tắc sapi_interface nội bộ. Trình tạo sẽ quét các tệp này để khai báo hàm của thư viện C/C++.

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

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

Giá trị 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.
tiêu đề

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 đề đã 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; mặc định là True

KHÔNG DÙNG NỮA
limit_scan_depth

Boolean; không bắt buộc; 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 tới và quy trình xây dựng sẽ không thành công. Thuộc tính này là một phương án thoát cho các tình huống phức tạp này. Không sử dụng trừ phi cần thiết.
thẻ

Xem tài liệu về Bazel để tìm hiểu về thẻ.
mức hiển thị

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

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

Ví dụ về zlib là một dự án tham khảo hay minh hoạ cách sử dụng quy tắc tạo bản 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 policy is sufficient.
    embed = True,  # This is the default
    functions = [
        "deflateInit_",
        "deflate",
        "deflateEnd",
    ],
    lib = "@zlib//:zlibonly",
    lib_name = "Zlib",
    namespace = "sapi::zlib",
)