Przewodnik po regułach tworzenia

Wstęp

Interfejs Sandboxed API (SAPI) może być używany z systemem kompilacji Bazel firmy Google lub z popularnym systemem metakompilacji CMake. Ta strona dotyczy usługi Bazel, ale te same funkcje są dostępne w CMake. Zalecanym systemem kompilacji jest Bazel, z którym najłatwiej można zintegrować.

W pliku BUILD.bazel znajdziesz regułę kompilacji, która pozwala utworzyć kod hosta. Aby kod hosta wykorzystywał wersję biblioteki w trybie piaskownicy, musisz przygotować miejsce docelowe 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 trybie piaskownicy, zastępuje normalną bibliotekę cc_library jako miejsce docelowe kodu hosta. Składa się z zależności zlib_sapi.bin i piaskownicy.
• name.interface: wygenerowany interfejs biblioteki.
• name.embed: element docelowy cc_embed_data() używany do umieszczenia piaskownicy w pliku binarnym. Więcej informacji: bazel/embed_data.bzl.
• name.bin: plik binarny piaskownicy – składa się z niewielkiego wycinka komunikacyjnego i biblioteki dostępnej w piaskownicy.

Argumenty

Atrybuty
nazwa	Nazwa; wymagana Unikalna nazwa celu. Zidentyfikuje ona bibliotekę C/C++ w trybie piaskownicy. Zobacz docelowy adres wyjściowy name-sapi.
deps	Lista etykiet; opcjonalna Lista innych bibliotek, które mają zostać połączone z biblioteką C/C++ w trybie piaskownicy.
źródła	Lista etykiet; opcjonalna Lista plików C i C++, które są przetwarzane w celu utworzenia biblioteki C/C++ w trybie piaskownicy. Są to pliki źródłowe i nagłówki C/C++ w języku C/C++ – niegenerowane (normalny kod źródłowy) lub wygenerowane. Więcej informacji znajdziesz w objaśnieniu atrybutów srcs w dokumentacji biblioteki cc_library.
HDR	Lista etykiet; opcjonalna Lista plików nagłówka, które są przetwarzane w celu utworzenia biblioteki C/C++ w trybie piaskownicy. Tutaj powinna znaleźć się definicja piaskownicy (sandbox.h). Jeśli używana jest osadzona biblioteka SAPI i wystarczą domyślne zasady piaskownicy.
umieść	Wartość logiczna; opcjonalna; domyślna to True Jeśli zasada ma wartość Prawda, biblioteka piaskownicy powinna być umieszczona w kodzie hosta. Dzięki temu Piaskownica SAPI może być zainicjowana przy użyciu konstruktora ::sapi::Sandbox::Sandbox(FileToc*).
funkcje	Lista nazw funkcji; opcjonalnie Lista funkcji z biblioteki C/C++, dla których generowana jest wersja piaskownicy i które mogą być używane w kodzie hosta. Jeśli lista będzie pusta, zostanie podjęta próba wyeksportowania i zapakowania wszystkich funkcji znajdujących się w bibliotece.
lib	Ciąg znaków; wymagany Nazwa biblioteki docelowej biblioteki C/C++, która będzie biblioteką w trybie piaskownicy. Oczekuje się, że masz w projekcie regułę kompilacji cc_library dla biblioteki C/C++.
lib_name	Ciąg znaków; wymagany Nazwa obiektu SAPI używanego do serwera proxy funkcji bibliotecznych z atrybutu funkcji. Wszelkie wywołania funkcji w bibliotece piaskownicy będą realizowane za pomocą obiektu SAPI.
input_files	Lista etykiet; opcjonalna Lista plików C i C++, które są przetwarzane podczas wewnętrznego uruchomienia reguły sapi_interface. Generator skanuje te pliki pod kątem deklaracji funkcji biblioteki C/C++. Najczęściej nie jest to potrzebne, ponieważ wyeksportowane nagłówki z biblioteki C/C++ są zawsze skanowane.
przestrzeń nazw	Ciąg znaków; opcjonalny; domyślnie jest to sapigen Identyfikator przestrzeni nazw C++, w którym należy umieścić obiekt SAPI zdefiniowany przez lib_name. Domyślną przestrzenią nazw to sapigen.
nagłówek	Ciąg znaków; opcjonalnie Nazwa pliku nagłówka do użycia zamiast wygenerowanego pliku. Jeśli chcesz automatycznie generować kod, nie używaj tego atrybutu.
add_default_deps	Wartość logiczna; opcjonalna; domyślna to True WYCOFANE
limit_scan_depth	Wartość logiczna; opcjonalna; domyślna to False W przypadku złożonych bibliotek może zostać osiągnięta liczba plików dla bazy danych, a proces kompilacji się nie powiedzie. Ten atrybut służy do wyjścia awaryjnego na wypadek skomplikowanych sytuacji. Nie używaj tego narzędzia, jeśli nie jest to konieczne.
tagi	Informacje o tagach znajdziesz w dokumentacji Bazel.
widoczność	Informacje o widoczności znajdziesz w dokumentacji Bazel

Przykład użycia

Przykład zlib jest dobrym projektem referencyjnym pokazującym, jak używana jest reguła kompilacji 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",
)