Przewodnik po regułach tworzenia

Wprowadzenie

Interfejs API w piaskownicy (SAPI) można używać z systemem kompilacji Bazel firmy Google lub z popularnym systemem kompilacji CMake. Ta strona koncentruje się na Bazelu, ale te same funkcje są dostępne w CMake. Bazel to zalecany system kompilacji, który najłatwiej zintegrować.

W pliku BUILD.bazel będziesz mieć regułę kompilacji do kompilowania kodu hosta. Aby kod hosta mógł korzystać z wersji biblioteki w piaskownicy, musisz przygotować cel kompilacji, z którego będzie korzystać kod hosta.

Reguły kompilacji 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)

Cele wyjściowe

Reguła kompilacji sapi_library() generuje te cele:

• name-sapi: biblioteka w piaskownicy, zastępuje zwykłą bibliotekę cc_library jako cel kodu hosta. Składa się z zlib_sapi.bin i zależności piaskownicy.
• name.interface: wygenerowany interfejs biblioteki.
• name.embed: cel cc_embed_data() używany do umieszczania piaskownicy w pliku binarnym. Zobacz bazel/embed_data.bzl.
  • name.bin: plik binarny piaskownicy, składa się z małego elementu komunikacyjnego i biblioteki, która jest umieszczana w piaskownicy.

Argumenty

Atrybuty
nazwa	Nazwa; wymagana Unikalna nazwa tego celu. Będzie ona identyfikować bibliotekę C/C++ w piaskownicy. Zobacz cel wyjściowy name-sapi.
deps	Lista etykiet; opcjonalnie Lista innych bibliotek, które mają być połączone z biblioteką C/C++ w piaskownicy.
srcs	Lista etykiet; opcjonalnie Lista plików C i C++, które są przetwarzane w celu utworzenia biblioteki C/C++ w piaskownicy. Są to pliki źródłowe i nagłówkowe C/C++, które nie są generowane (zwykły kod źródłowy) lub są generowane. Więcej informacji znajdziesz w wyjaśnieniu atrybutu srcs w dokumentacji cc_library.
hdrs	Lista etykiet; opcjonalnie Lista plików nagłówkowych, które są przetwarzane w celu utworzenia biblioteki C/C++ w piaskownicy. Tutaj powinna się znajdować definicja piaskownicy (sandbox.h). Pozostaw to pole puste, jeśli używana jest biblioteka SAPI umieszczona w kodzie, a domyślna konfiguracja piaskownicy (DefaultConfig, która używa DefaultPolicyBuilder, DefaultFlags, DefaultEnvironmentVariables, i DefaultLimits) jest wystarczająca.
embed	Wartość logiczna; opcjonalnie; domyślnie True Jeśli wartość to True, biblioteka w piaskownicy powinna być umieszczona w kodzie hosta. Umożliwia to zainicjowanie piaskownicy SAPI za pomocą ::sapi::Sandbox::Sandbox(FileToc*) konstruktora.
functions	Lista nazw funkcji; opcjonalnie Lista funkcji z biblioteki C/C++, dla których generowana jest wersja w piaskownicy , która może być używana w kodzie hosta. Pusta lista spowoduje wyeksportowanie i opakowanie wszystkich funkcji znalezionych w bibliotece.
lib	Ciąg znaków; wymagany Nazwa celu biblioteki C/C++, która będzie biblioteką w piaskownicy. Wymaga to, aby w projekcie była reguła kompilacji cc_library dla biblioteki C/C++ w projekcie.
lib_name	Ciąg znaków; wymagany Nazwa obiektu SAPI, który jest używany do przekazywania funkcji biblioteki funkcji z atrybutu functions. Każde wywołanie funkcji w bibliotece w piaskownicy będzie odbywać się za pomocą obiektu SAPI.
input_files	Lista etykiet; opcjonalnie Lista plików C i C++, które są przetwarzane podczas wewnętrznego uruchamiania reguły sapi_interface. Generator skanuje te pliki pod kątem deklaracji funkcji biblioteki C/C++. Zwykle nie jest to konieczne, ponieważ zawsze skanowane są wyeksportowane nagłówki biblioteki C/C++.
namespace	Ciąg znaków; opcjonalnie; domyślnie sapigen Identyfikator przestrzeni nazw C++, w której ma się znajdować obiekt SAPI zdefiniowany przez lib_name. Domyślna przestrzeń nazw to sapigen.
header	Ciąg znaków; opcjonalnie Nazwa pliku nagłówkowego, który ma być używany zamiast wygenerowanego pliku nagłówkowego. Jeśli chcesz automatycznie wygenerować kod, nie używaj tego atrybutu.
add_default_deps	Wartość logiczna; opcjonalnie; domyślnie True WYCOFANE
limit_scan_depth	Wartość logiczna; opcjonalnie; domyślnie False W przypadku złożonych bibliotek może zostać osiągnięta liczba plików w Bazelu a proces kompilacji nie powiedzie się. Ten atrybut jest rozwiązaniem w takich złożonych sytuacjach. Nie używaj, chyba że jest to konieczne.
tags	Informacje o tagach znajdziesz w dokumentacji Bazela .
visibility	Informacje o widoczności znajdziesz w dokumentacji Bazela.

Przykład użycia

Dobrym projektem referencyjnym, który pokazuje, jak używać reguły kompilacji sapi_library, jest przykład zlib:

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