Руководство по правилам сборки

Введение

Sandboxed API (SAPI) можно использовать с системой сборки Bazel от Google или с популярной метасистемой сборки CMake . Эта страница посвящена Bazel, но те же функции доступны и для CMake. Bazel — рекомендуемая система сборки, с которой проще всего интегрироваться.

В файле BUILD.bazel будет указано правило сборки для вашего кода хоста. Чтобы код хоста использовал изолированную версию библиотеки, необходимо подготовить целевой объект сборки, который будет использовать ваш код хоста.

Правила сборки 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)

Выходные цели

Правило сборки sapi_library() генерирует следующие цели:

• name-sapi : изолированная библиотека, заменяет обычную cc_library в качестве целевого хост-кода. Состоит из zlib_sapi.bin и зависимостей изолированной библиотеки.
• имя .interface: Сгенерированный интерфейс библиотеки.
• Имя .embed: цель cc_embed_data() , используемая для встраивания Sandboxee в исполняемый файл. См. bazel/embed_data.bzl .
  • имя .bin: двоичный файл Sandboxee, состоящий из небольшой заглушки для связи и библиотеки, которая помещается в песочницу.

Аргументы

Атрибуты
имя	Имя ; обязательно Уникальное имя для этой цели. Оно будет идентифицировать изолированную библиотеку C/C++ (см. выходной параметр name-sapi).
deps	Список меток ; необязательно Список других библиотек, которые следует подключить к изолированной библиотеке C/C++.
источники	Список меток ; необязательно Список файлов C и C++, обрабатываемых для создания изолированной библиотеки C/C++. Это исходные и заголовочные файлы C/C++, как несгенерированные (обычный исходный код), так и сгенерированные. Более подробную информацию см. в описании атрибута srcs в документации cc_library .
hdrs	Список меток ; необязательно Список заголовочных файлов, которые обрабатываются для создания изолированной библиотеки C/C++. Здесь должно располагаться определение песочницы (sandbox.h); оставьте это поле пустым, если используется встроенная библиотека SAPI и достаточно политики песочницы по умолчанию.
встраивать	Логическое значение; необязательное; по умолчанию True Если True, изолированная библиотека должна быть встроена в код хоста. Это позволяет инициализировать песочницу SAPI с помощью конструктора ::sapi::Sandbox::Sandbox(FileToc*) .
функции	Список названий функций; необязательно Список функций из библиотеки C/C++, для которых создается изолированная версия, которую затем можно использовать в коде хоста. Пустой список попытается экспортировать и обернуть все функции, найденные в библиотеке.
библиотека	Строка; обязательно Имя целевой библиотеки C/C++, которая будет изолированной библиотекой. Предполагается, что у вас есть правило сборки cc_library для библиотеки C/C++ в проекте.
имя_библиотеки	Строка; обязательно Имя объекта SAPI, используемого для проксирования библиотечных функций из атрибута "functions". Любой вызов функции в изолированной библиотеке будет осуществляться через объект SAPI.
входные_файлы	Список меток ; необязательно Список файлов C и C++, обрабатываемых во время внутреннего выполнения правила sapi_interface. Генератор сканирует эти файлы на предмет объявлений функций библиотеки C/C++. В большинстве случаев это не требуется, поскольку экспортированные заголовочные файлы библиотеки C/C++ всегда сканируются.
пространство имен	Строка; необязательно; по умолчанию — sapigen Идентификатор пространства имен C++, в которое помещается объект SAPI, определенный параметром lib_name . Пространство имен по умолчанию — sapigen .
заголовок	Строка; необязательно Имя заголовочного файла, который следует использовать вместо сгенерированного заголовочного файла. Если вы хотите автоматически сгенерировать код, не используйте этот атрибут.
add_default_deps	Логическое значение; необязательное; по умолчанию True УСТАРЕЛО
limit_scan_length	Логическое значение; необязательное; по умолчанию — False В сложных библиотеках количество файлов может быть достигнуто, и сборка завершится неудачей. Этот атрибут — выход из таких сложных ситуаций. Не используйте его без необходимости.
теги	Информацию о тегах см. в документации Bazel.
видимость	Для наглядности см. документацию Bazel.

Пример использования

Пример zlib — хороший справочный проект, демонстрирующий, как используется правило сборки 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",
)