Общие правила

Правила

• alias
• config_setting
• filegroup
• genquery
• genrule
• starlark_doc_extract
• test_suite

псевдоним

alias(name, actual, compatible_with, deprecation, features, restricted_to, tags, target_compatible_with, testonly, visibility)

Правило alias создаёт другое имя, по которому можно обратиться к правилу.

Псевдонимирование работает только для «обычных» целей. В частности, package_group и test_suite нельзя псевдонимировать.

Псевдонимирование может быть полезно в больших репозиториях, где переименование цели потребовало бы внесения изменений во множество файлов. Также можно использовать правило псевдонима для хранения вызова функции select, если нужно повторно использовать эту логику для нескольких целей.

Правило псевдонима имеет собственное объявление видимости. Во всех других отношениях оно ведет себя так же, как правило, к которому оно относится (например, testonly в псевдониме игнорируется; используется testonly-ность правила-оригинала) с некоторыми незначительными исключениями:

• Тесты не выполняются, если их псевдоним указан в командной строке. Чтобы определить псевдоним, который выполняет связанный тест, используйте правило test_suite с одной целью в атрибуте tests.
• При определении групп сред псевдонимы для environment правил не поддерживаются. Они также не поддерживаются в опции командной строки --target_environment.

Примеры

filegroup(
    name = "data",
    srcs = ["data.txt"],
)

alias(
    name = "other",
    actual = ":data",
)

Аргументы

настройка_конфигурации

config_setting(name, constraint_values, define_values, deprecation, distribs, features, flag_values, licenses, tags, testonly, values, visibility)

Соответствует ожидаемому состоянию конфигурации (выраженному как флаги сборки или ограничения платформы) для целей запуска настраиваемых атрибутов. См. select для получения информации о том, как использовать это правило, и Настраиваемые атрибуты для общего обзора функции.

Примеры

Следующее соответствует любой сборке, в которой заданы --compilation_mode=opt или -c opt (явно в командной строке или неявно из файлов .bazelrc):

  config_setting(
      name = "simple",
      values = {"compilation_mode": "opt"}
  )
  

Следующее соответствует любой сборке, нацеленной на ARM и применяющей пользовательское определение FOO=bar (например, bazel build --cpu=arm --define FOO=bar ...):

  config_setting(
      name = "two_conditions",
      values = {
          "cpu": "arm",
          "define": "FOO=bar"
      }
  )
  

Следующее соответствует любой сборке, в которой задан пользовательский флаг --//custom_flags:foo=1 (явно в командной строке или неявно из файлов .bazelrc):

  config_setting(
      name = "my_custom_flag_is_set",
      flag_values = { "//custom_flags:foo": "1" },
  )
  

Следующее соответствует любой сборке, нацеленной на платформу с архитектурой x86_64 и версией glibc 2.25, при условии существования constraint_value с меткой //example:glibc_2_25. Обратите внимание, что платформа по-прежнему соответствует, если она определяет дополнительные значения ограничений помимо этих двух.

  config_setting(
      name = "64bit_glibc_2_25",
      constraint_values = [
          "@platforms//cpu:x86_64",
          "//example:glibc_2_25",
      ]
  )
  

Примечания

• См. select для того, что происходит, когда несколько config_setting соответствуют текущему состоянию конфигурации.
• Для флагов, которые поддерживают сокращённые формы (например, --compilation_mode против -c), определения values должны использовать полную форму. Они автоматически соответствуют вызовам, использующим любую форму.
• Если флаг принимает несколько значений (например, --copt=-Da --copt=-Db или список тип флага Starlark), values = { "flag": "a" } соответствует, если "a" присутствует где-либо в фактическом списке.

  values = { "myflag": "a,b" } работает аналогично: это соответствует --myflag=a --myflag=b, --myflag=a --myflag=b --myflag=c, --myflag=a,b, и --myflag=c,b,a. Точные семантики варьируются в зависимости от флагов. Например, --copt не поддерживает несколько значений в одном случае: --copt=a,b приводит к ["a,b"], а --copt=a --copt=b приводит к ["a", "b"] (поэтому values = { "copt": "a,b" } соответствует первому, но не второму). Но --ios_multi_cpus (для правил Apple) поддерживает: -ios_multi_cpus=a,b и ios_multi_cpus=a --ios_multi_cpus=b оба приводят к ["a", "b"]. Тщательно проверьте определения флагов и тестируйте свои условия, чтобы проверить точные ожидания.

• Если вам нужны условия, которые не моделируются встроенными флагами сборки, используйте флаги, определённые в Starlark. Вы также можете использовать --define, но это обеспечивает более слабую поддержку и не рекомендуется. См. здесь для получения более подробной информации.
• Избегайте дублирования идентичных определений config_setting в разных пакетах. Вместо этого используйте общий config_setting определённый в стандартном пакете.
• values, define_values, и constraint_values можно использовать в любой комбинации в том же config_setting правиле, но хотя бы одно должно быть установлено для любого данного config_setting.

Аргументы

            config_setting(
                name = "a_and_b",
                values = {
                    "define": "a=1",
                    "define": "b=2",
                })
          

            config_setting(
                name = "a_and_b",
                define_values = {
                    "a": "1",
                    "b": "2",
                })
          

группа_файлов

filegroup(name, srcs, data, compatible_with, deprecation, distribs, features, licenses, output_group, restricted_to, tags, target_compatible_with, testonly, visibility)

Используйте filegroup для сбора выходных данных набора целей под одним меткой.

filegroup не является заменой перечисления целей в командной строке или в атрибуте другой команды, потому что у целей есть много свойств, помимо их выходных данных, которые не собираются таким же образом. Однако, оно всё ещё полезно в довольно многих случаях, например, в атрибуте srcs genrule или атрибуте data правила *_binary.

Рекомендуется использовать filegroup, а не ссылаться напрямую на каталоги. Прямое обращение к каталогам не рекомендуется, потому что система сборки не имеет полного знания обо всех файлах в каталоге, поэтому она может не перестраиваться при изменении этих файлов. В сочетании с glob, filegroup может гарантировать, что все файлы явно известны системе сборки.

Примеры

Чтобы создать filegroup, состоящий из двух исходных файлов, выполните

filegroup(
    name = "mygroup",
    srcs = [
        "a_file.txt",
        "//a/library:target",
        "//a/binary:target",
    ],
)

Или используйте glob для полного сканирования каталога testdata:

filegroup(
    name = "exported_testdata",
    srcs = glob([
        "testdata/*.dat",
        "testdata/logs/**/*.log",
    ]),
)

Чтобы использовать эти определения, ссылайтесь на filegroup с меткой из любого правила:

cc_library(
    name = "my_library",
    srcs = ["foo.cc"],
    data = [
        "//my_package:exported_testdata",
        "//my_package:mygroup",
    ],
)

Аргументы

genquery

genquery(name, deps, data, compatible_with, compressed_output, deprecation, distribs, exec_compatible_with, exec_properties, expression, features, licenses, opts, restricted_to, scope, strict, tags, target_compatible_with, testonly, visibility)

genquery() выполняет запрос, заданный на языке запросов Bazel Bazel query language, и выводит результат в файл.

Чтобы сохранить согласованность сборки, запросу разрешается посещать только транзитивное замыкание целей, указанных в атрибуте scope. Запросы, нарушающие это правило, завершатся ошибкой во время выполнения, если strict не указан или true (если strict false, цели, выходящие за рамки области, просто пропустятся с предупреждением). Самый простой способ убедиться, что этого не происходит, это указать те же метки в области, что и в выражении запроса.

Единственное различие между запросами, разрешенными здесь и в командной строке, заключается в том, что запросы, содержащие спецификации целей с подстановкой (например, //pkg:* или //pkg:all), здесь не разрешены. Причины этого двояки: во-первых, потому что genquery должен указать область, чтобы предотвратить влияние целей за пределами транзитивного замыкания запроса на его вывод; и, во-вторых, потому что файлы BUILD не поддерживают подстановку зависимостей (например, deps=["//a/..."] запрещено).

Вывод genquery упорядочен лексикографически для обеспечения детерминированного вывода, за исключением --output=graph|minrank|maxrank или когда somepath используется в качестве функции верхнего уровня.

Имя выходного файла - это имя правила.

Примеры

В этом примере в файл записывается список меток в транзитивном замыкании указанной цели.

genquery(
    name = "kiwi-deps",
    expression = "deps(//kiwi:kiwi_lib)",
    scope = ["//kiwi:kiwi_lib"],
)

Аргументы

genrule

genrule(name, srcs, outs, cmd, cmd_bash, cmd_bat, cmd_ps, compatible_with, deprecation, distribs, exec_compatible_with, exec_properties, executable, features, licenses, local, message, output_licenses, output_to_bindir, restricted_to, tags, target_compatible_with, testonly, toolchains, tools, visibility)

genrule генерирует один или несколько файлов с помощью пользовательской команды Bash.

Genrule - это обобщённые правила сборки, которые можно использовать, если нет специального правила для задачи. Например, можно выполнить одну строчку Bash. Однако, если вам нужно скомпилировать файлы C++, придерживайтесь существующих правил cc_*, поскольку все тяжёлые вычисления уже выполнены за вас.

Обратите внимание, что genrule требует оболочки для интерпретации аргумента команды. Также легко ссылаться на произвольные программы, доступные в переменной среды PATH, однако это делает команду негерметичной и может сделать результат невоспроизводимым. Если вам нужно запустить только один инструмент, рассмотрите использование run_binary вместо этого.

Как и любое другое действие, действие, созданное genrule, не должно предполагать ничего о своей рабочей директории; Bazel гарантирует только, что объявленные входные данные будут доступны по пути, который $(location) возвращает для их метки. Например, если действие выполняется в песочнице или удалённо, реализация песочницы или удалённого выполнения определит рабочую директорию. Если выполняются напрямую (с использованием стратегии standalone), рабочая директория будет корневой директорией выполнения, т.е. результатом bazel info execution_root.

Не используйте genrule для запуска тестов. Существуют особые положения для тестов и результатов тестов, включая политики кэширования и переменные окружения. Тесты, как правило, выполняются после завершения сборки и на целевой архитектуре, тогда как genrule выполняются во время сборки и на архитектуре выполнения (они могут быть разными). Если вам нужно общее правило тестирования, используйте sh_test.

Учёт особенностей кросс-компиляции

См. руководство пользователя для получения дополнительной информации о кросс-компиляции.

Хотя genrule выполняются во время сборки, их выходные данные часто используются после сборки, для развертывания или тестирования. Рассмотрим пример компиляции кода C для микроконтроллера: компилятор принимает исходные файлы C и генерирует код, который работает на микроконтроллере. Сгенерированный код, очевидно, не может работать на процессоре, который использовался для его компиляции, но сам компилятор C (если он скомпилирован из исходных кодов) должен.

Система сборки использует конфигурацию exec для описания машины(ы), на которой выполняется сборка, и конфигурацию target для описания машины(ы), на которой предполагается выполнять выходные данные сборки. Она предоставляет параметры для настройки каждой из них и отделяет соответствующие файлы в отдельные каталоги для предотвращения конфликтов.

Для genrule система сборки гарантирует, что зависимости построены должным образом: srcs строятся (при необходимости) для конфигурации target, tools строятся для конфигурации exec, и выходные данные считаются для конфигурации target. Она также предоставляет переменные "Make", которые команды genrule могут передать соответствующим инструментам.

Целенаправленно, что genrule не определяет атрибут deps: другие встроенные правила используют зависящие от языка метаданные, передаваемые между правилами, чтобы автоматически определить, как обращаться с зависимыми правилами, но такая автоматизация невозможна для genrules. Genrules работают исключительно на уровне файлов и runfiles.

Особые случаи

Компиляция exec-exec: в некоторых случаях система сборки должна запускать genrules таким образом, чтобы выходные данные также могли быть выполнены во время сборки. Например, если genrule создает некоторый пользовательский компилятор, который затем используется другим genrule, первый должен производить свой вывод для конфигурации exec, потому что именно там компилятор будет запущен в другом genrule. В этом случае система сборки автоматически выполняет правильные действия: она собирает srcs и outs первого genrule для конфигурации exec вместо конфигурации target. Смотрите руководство пользователя для получения более подробной информации.

JDK и C++ инструменты: для использования инструмента из JDK или набора инструментов C++, система сборки предоставляет набор переменных для использования. См. "Переменные Make" для получения подробностей.

Окружение Genrule

Команда genrule выполняется оболочкой Bash, настроенной на завершение с ошибкой, когда команда или конвейер завершается с ошибкой, используя set -e -o pipefail.

Инструмент сборки выполняет команду Bash в очищенной среде процесса, которая определяет только основные переменные, такие как PATH, PWD, TMPDIR, и несколько других. Для обеспечения воспроизводимости сборок большинство переменных, определенных в среде оболочки пользователя, не передаются команде genrule. Однако Bazel (но не Blaze) передает значение переменной среды пользователя PATH. Любое изменение значения PATH заставит Bazel повторно выполнить команду при следующей сборке.

Команда genrule не должна получать доступ к сети, за исключением подключения процессов, которые являются дочерними по отношению к самой команде, хотя это в настоящее время не применяется.

Система сборки автоматически удаляет все существующие выходные файлы, но создает все необходимые родительские каталоги перед запуском genrule. Она также удаляет все выходные файлы в случае сбоя.

Общие рекомендации

• Убедитесь, что инструменты, запущенные genrule, являются детерминированными и герметичными. Они не должны записывать отметки времени в свой вывод, а должны использовать стабильную упорядоченность для множеств и карт, а также записывать только относительные пути к файлам вывода, не абсолютные пути. Несоблюдение этого правила приведет к неожиданному поведению сборки (Bazel не пересобирает genrule, который, как вы думали, будет пересобираться) и ухудшит производительность кэша.
• Активно используйте $(location) для выходов, инструментов и источников. Из-за разделения выходных файлов для разных конфигураций genrules не могут полагаться на жестко закодированные и/или абсолютные пути.
• Напишите общий макрос Starlark в случае, если одни и те же или очень похожие genrules используются в нескольких местах. Если genrule сложен, рассмотрите возможность реализации его в скрипте или как правило Starlark. Это улучшает читабельность и проверяемость.
• Убедитесь, что код выхода правильно указывает на успех или неудачу genrule.
• Не записывайте информационные сообщения в stdout или stderr. Хотя они полезны для отладки, они легко могут стать шумом; успешный genrule должен быть беззвучным. С другой стороны, genrule, завершившийся с ошибкой, должен выдавать хорошие сообщения об ошибках.
• $$ вычисляется как $, литеральная знак доллара, поэтому для вызова команд оболочки, содержащих знаки доллара, например ls $(dirname $x), необходимо экранировать их, как в ls $$(dirname $$x).
• Избегайте создания символических ссылок и каталогов. Bazel не копирует структуру каталогов/символических ссылок, созданную genrules, и проверка зависимостей Bazel на каталоги некорректна.
• При ссылке на genrule в других правилах вы можете использовать либо метку genrule, либо метки отдельных выходных файлов. Иногда один подход более читабелен, иногда другой: ссылка на выходы по имени в srcs правила-потребителя позволит избежать случайного выбора других выходов genrule, но может быть утомительной, если genrule производит много выходов.

Примеры

В этом примере генерируется foo.h. Источники отсутствуют, потому что команда не принимает никаких входных данных. "Бинарник", запускаемый командой, — это скрипт Perl в том же пакете, что и genrule.

genrule(
    name = "foo",
    srcs = [],
    outs = ["foo.h"],
    cmd = "./$(location create_foo.pl) > \"$@\"",
    tools = ["create_foo.pl"],
)

Следующий пример показывает, как использовать filegroup и выходные данные другого genrule. Обратите внимание, что использование $(SRCS) вместо явных $(location) директив также сработает; в данном примере используется последнее, для демонстрации.

genrule(
    name = "concat_all_files",
    srcs = [
        "//some:files",  # a filegroup with multiple files in it ==> $(locations)
        "//other:gen",   # a genrule with a single output ==> $(location)
    ],
    outs = ["concatenated.txt"],
    cmd = "cat $(locations //some:files) $(location //other:gen) > $@",
)

Аргументы

starlark_doc_extract

starlark_doc_extract(name, deps, src, data, compatible_with, deprecation, distribs, exec_compatible_with, exec_properties, features, licenses, render_main_repo_name, restricted_to, symbol_names, tags, target_compatible_with, testonly, visibility)

starlark_doc_extract() извлекает документацию для правил, функций (включая макросы), аспектов и поставщиков, определённых или повторно экспортированных в заданный .bzl или .scl файл. Результатом этого правила является двоичный протокол ModuleInfo , как определено в stardoc_output.proto в дереве исходного кода Bazel.

Неявные целевые объекты вывода

• name.binaryproto (вывод по умолчанию): двоичный протокол ModuleInfo.
• name.textproto (строятся только при явном запросе): текстовая прото версия name.binaryproto.

Предупреждение: формат вывода этого правила не гарантируется стабильным. Он предназначен в основном для внутреннего использования Stardoc.

Аргументы

Набор_тестов

test_suite(name, compatible_with, deprecation, distribs, features, licenses, restricted_to, tags, target_compatible_with, testonly, tests, visibility)

Набор_тестов определяет набор тестов, которые считаются «полезными» для людей. Это позволяет проектам определять наборы тестов, такие как «тесты, которые необходимо выполнить перед коммитом», «тесты на производительность проекта» или «все небольшие тесты». Команда bazel test учитывает такую организацию: для вызова, такого как bazel test //some/test:suite, Bazel сначала перечисляет все тестовые цели, транзитивно включённые в цель //some/test:suite (это называется «расширением набора_тестов»), затем Bazel строит и тестирует эти цели.

Примеры

Набор_тестов для запуска всех небольших тестов в текущем пакете.

test_suite(
    name = "small_tests",
    tags = ["small"],
)

Набор_тестов, запускающий определённый набор тестов:

test_suite(
    name = "smoke_tests",
    tests = [
        "system_unittest",
        "public_api_unittest",
    ],
)

Набор_тестов для запуска всех тестов в текущем пакете, которые не являются нестабильными.

test_suite(
    name = "non_flaky_test",
    tags = ["-flaky"],
)

Аргументы