Руководство по созданию правил

Введение

Изолированный API (SAPI) можно использовать с системой сборки Bazel от Google или с популярной системой метасборки CMake. This page focuses on Bazel, but the same features are available for 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 и зависимостей песочницы.
• name.interface – интерфейс сгенерированной библиотеки.
• name.embed: цель cc_embed_data(), используемая для встраивания изолированной среды в двоичный файл. См. bazel/embed_data.bzl.
  • name.bin – исполняемый файл Sandboxee, состоящий из небольшого коммуникационного модуля и библиотеки, которая помещается в изолированную среду.

Аргументы

Атрибуты
name	Name; обязательное свойство. Уникальное название для этой цели. Это позволит идентифицировать изолированную библиотеку C/C++. См. целевой объект name-sapi.
deps	Список ярлыков (необязательно). Список других библиотек, которые будут связаны с изолированной библиотекой C/C++.
srcs	Список ярлыков (необязательно). Список файлов C и C++, которые обрабатываются для создания библиотеки C/C++ в изолированной среде. Это исходные и заголовочные файлы C/C++, которые могут быть как сгенерированными, так и нет (обычный исходный код). Дополнительную информацию можно найти в описании атрибута srcs в документации по cc_library.
hdrs	Список ярлыков (необязательно). Список заголовочных файлов, которые обрабатываются для создания изолированной библиотеки C/C++. Здесь должен быть указан файл sandbox.h. Если используется встроенная библиотека SAPI и достаточно конфигурации изолированной среды по умолчанию (DefaultConfig, в которой используются DefaultPolicyBuilder, DefaultFlags, DefaultEnvironmentVariables и DefaultLimits), оставьте поле пустым.
embed	Логическое значение; необязательное; по умолчанию – True. Если True, изолированная библиотека должна быть встроена в код хоста. Это позволяет инициализировать безопасную тестовую среду SAPI с помощью конструктора ::sapi::Sandbox::Sandbox(FileToc*).
функции	Список названий функций (необязательно). Список функций из библиотеки C/C++, для которых создается изолированная версия и которые затем можно использовать в коде хоста. Если список пуст, будут экспортированы и упакованы все функции, найденные в библиотеке.
lib	Строка; обязательно Название целевой библиотеки C/C++, которая будет библиотекой в изолированной среде. Для этого в проекте должно быть правило сборки cc_library для библиотеки C/C++.
lib_name	Строка; обязательный параметр. Название объекта SAPI, который используется для проксирования функций библиотеки из атрибута functions. Любой вызов функции в изолированной библиотеке будет выполняться через объект SAPI.
input_files	Список ярлыков (необязательно). Список файлов C и C++, которые обрабатываются во время внутреннего выполнения правила sapi_interface. Генератор сканирует эти файлы на наличие объявлений функций библиотеки C/C++. В большинстве случаев это не требуется, поскольку экспортированные заголовки библиотеки C/C++ всегда сканируются.
пространство имен	Строка; необязательный; по умолчанию – sapigen Идентификатор пространства имен C++, в которое будет помещен объект SAPI, определенный параметром lib_name. Пространство имен по умолчанию – sapigen.
заголовок	Строка; необязательный параметр. Название заголовочного файла, который будет использоваться вместо сгенерированного. Если вы хотите, чтобы код генерировался автоматически, не используйте этот атрибут.
add_default_deps	Логическое значение; необязательное; по умолчанию – True. УСТАРЕВШИЙ
limit_scan_depth	Логическое значение; необязательный параметр; по умолчанию – False. Для сложных библиотек может быть достигнуто ограничение на количество файлов для Bazel, и процесс сборки не будет выполнен. Этот атрибут позволяет обойти такие сложные ситуации. Не используйте без необходимости.
теги	Подробнее о тегах рассказывается в документации по 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 configuration (DefaultConfig) is sufficient.
    embed = True,  # This is the default
    functions = [
        "deflateInit_",
        "deflate",
        "deflateEnd",
    ],
    lib = "@zlib//:zlibonly",
    lib_name = "Zlib",
    namespace = "sapi::zlib",
)