Panduan Aturan Build

Pengantar

Sandboxed API (SAPI) dapat digunakan dengan sistem build Bazel Google, atau dengan sistem build meta CMake yang populer. Halaman ini berfokus pada Bazel, tetapi fitur yang sama tersedia untuk CMake. Bazel adalah sistem build yang direkomendasikan dan paling mudah diintegrasikan.

Di file BUILD.bazel, Anda akan memiliki aturan build untuk membangun Kode Host. Agar Kode Host menggunakan versi library yang di-sandbox, Anda perlu menyiapkan target build yang akan digunakan oleh Kode Host Anda.

Aturan Build 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)

Target Output

Aturan build sapi_library() menghasilkan target berikut:

  • name-sapi: Library yang di-sandbox, menggantikan cc_library normal sebagai target Kode Host. Terdiri dari zlib_sapi.bin dan dependensi sandbox.
  • name.interface: Antarmuka library yang dihasilkan.
  • name.embed: Target cc_embed_data() yang digunakan untuk menyematkan Sandboxee dalam biner. Lihat bazel/embed_data.bzl.
    • name.bin: Biner Sandboxee, terdiri dari stub komunikasi kecil dan library yang sedang di-sandbox.

Argumen

Atribut
nama

Name; wajib

Nama unik untuk target ini. Tindakan ini akan mengidentifikasi library C/C++ sandbox, lihat target output name-sapi.
deps

Daftar label; opsional

Daftar library lain yang akan ditautkan ke library C/C++ sandbox.
srcs

Daftar label; opsional

Daftar file C dan C++ yang diproses untuk membuat library C/C++ yang di-sandbox. Ini adalah file sumber dan header C/C++, baik yang tidak dibuat (kode sumber normal) maupun yang dibuat.

Untuk mengetahui informasi selengkapnya, lihat penjelasan atribut srcs dalam dokumentasi cc_library.
hdrs

Daftar label ; opsional

Daftar file header yang diproses untuk membuat library C/C++ yang di-sandbox.

Di sinilah definisi sandbox (sandbox.h) harus ditempatkan; biarkan kosong jika library SAPI tersemat digunakan, dan kebijakan sandbox default sudah cukup.
menyematkan

Boolean; opsional; defaultnya adalah True

Jika Benar (True), library sandbox harus disematkan di dalam kode host. Hal ini memungkinkan SAPI Sandbox diinisialisasi dengan konstruktor ::sapi::Sandbox::Sandbox(FileToc*).
functions

Daftar nama fungsi; opsional

Daftar fungsi dari library C/C++ yang versi sandbox-nya dibuat dan kemudian dapat digunakan dalam Kode Host.

Daftar kosong akan mencoba mengekspor dan membungkus semua fungsi yang ditemukan di pustaka.
lib

String; wajib

Nama target library C/C++ yang akan menjadi library sandbox.

Hal ini mengharapkan Anda memiliki aturan build cc_library untuk library C/C++ dalam project.
lib_name

String; wajib

Nama objek SAPI yang digunakan untuk memproksi fungsi library dari atribut fungsi. Setiap panggilan ke fungsi di library yang di-sandbox akan terjadi melalui Objek SAPI.
input_files

Daftar label ; opsional

Daftar file C dan C++ yang diproses selama jalannya aturan sapi_interface secara internal. Generator memindai file ini untuk deklarasi fungsi library C/C++.

Hal ini sebagian besar tidak diperlukan karena header yang diekspor library C/C++ selalu dipindai.
namespace

String; opsional; defaultnya adalah sapigen

ID namespace C++ untuk menempatkan objek SAPI yang ditentukan oleh lib_name.

Namespace default adalah sapigen.
header

String; opsional

Nama file header yang akan digunakan, bukan file header yang dihasilkan.

Jika Anda ingin membuat kode secara otomatis, jangan gunakan atribut ini
add_default_deps

Boolean; opsional; defaultnya adalah True

TIDAK DIGUNAKAN LAGI
limit_scan_depth

Boolean; opsional; defaultnya adalah False

Untuk library yang kompleks, jumlah file untuk Bazel mungkin tercapai dan proses build tidak akan berhasil. Atribut ini adalah jalan keluar untuk situasi kompleks ini. Jangan gunakan kecuali diperlukan.
tags

Lihat dokumentasi Bazel untuk tag.
visibilitas

Lihat dokumentasi Bazel untuk visibilitas

Contoh Penggunaan

Contoh zlib adalah project referensi yang baik yang menunjukkan cara penggunaan aturan build 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",
)