Bazel создает программное обеспечение из исходного кода, организованного в дереве каталогов, называемом рабочей областью. Исходные файлы в рабочей области организованы во вложенную иерархию пакетов, где каждый пакет представляет собой каталог, содержащий набор связанных исходных файлов и один файл BUILD . Файл BUILD указывает, какие программные продукты могут быть созданы из исходного кода.
Рабочее пространство
Рабочее пространство — это дерево каталогов в вашей файловой системе, содержащее исходные файлы программного обеспечения, которое вы хотите создать. Каждое рабочее пространство имеет текстовый файл с именем WORKSPACE , который может быть пустым или содержать ссылки на внешние зависимости , необходимые для создания выходных данных.
Каталоги, содержащие файл с именем WORKSPACE , считаются корнем рабочей области. Таким образом, Bazel игнорирует любые деревья каталогов в рабочей области с корнем в подкаталоге, содержащем файл WORKSPACE , поскольку они образуют другую рабочую область.
Bazel также поддерживает файл WORKSPACE.bazel в качестве псевдонима файла WORKSPACE . Если оба файла существуют, используется WORKSPACE.bazel .
Репозитории
Код организован в репозиториях . Каталог, содержащий файл WORKSPACE , является корнем основного репозитория, также называемого @ . Другие (внешние) репозитории определяются в файле WORKSPACE с помощью правил рабочей области.
Правила рабочей области, связанные с Bazel, задокументированы в разделе « Правила рабочей области» в Build Encyclopedia и в документации по встроенным правилам репозитория Starlark .
Поскольку внешние репозитории сами по себе являются репозиториями, они также часто содержат файл WORKSPACE . Однако Bazel игнорирует эти дополнительные файлы WORKSPACE . В частности, репозитории, от которых зависит транзитивно, не добавляются автоматически.
Пакеты
Основной единицей организации кода в репозитории является пакет . Пакет представляет собой набор связанных файлов и спецификацию того, как их можно использовать для создания выходных артефактов.
Пакет определяется как каталог, содержащий файл с именем BUILD (или BUILD.bazel ). Пакет включает в себя все файлы в своем каталоге, а также все подкаталоги под ним, за исключением тех, которые сами содержат файл BUILD . Согласно этому определению, ни один файл или каталог не может быть частью двух разных пакетов.
Например, в следующем дереве каталогов есть два пакета: my/app и подпакет my/app/tests . Обратите внимание, что my/app/data — это не пакет, а каталог, принадлежащий пакету my/app .
src/my/app/BUILD
src/my/app/app.cc
src/my/app/data/input.txt
src/my/app/tests/BUILD
src/my/app/tests/test.cc
Цели
Пакет — это контейнер целей , которые определены в файле BUILD пакета. Большинство целей относятся к одному из двух основных типов: файлы и правила .
Файлы далее делятся на два типа. Исходные файлы обычно пишутся усилиями людей и возвращаются в репозиторий. Сгенерированные файлы , иногда называемые производными файлами или выходными файлами, не возвращаются, а создаются из исходных файлов.
Второй тип цели объявляется с помощью правила . Каждый экземпляр правила определяет отношение между набором входных и выходных файлов. Входными данными для правила могут быть исходные файлы, но они также могут быть выходными данными других правил.
В большинстве случаев не имеет значения, являются ли входные данные правила исходным файлом или сгенерированным файлом; важно только содержимое этого файла. Этот факт позволяет легко заменить сложный исходный файл сгенерированным файлом, созданным по правилу, например, когда бремя ручного обслуживания высокоструктурированного файла становится слишком утомительным, и кто-то пишет программу для его получения. Для потребителей этого файла не требуется никаких изменений. И наоборот, сгенерированный файл можно легко заменить исходным файлом только с локальными изменениями.
Входные данные для правила могут также включать другие правила . Точное значение таких взаимосвязей часто довольно сложно и зависит от языка или правил, но интуитивно оно простое: библиотечное правило C++ A может иметь другое библиотечное правило C++ B в качестве входных данных. Эффект этой зависимости заключается в том, что файлы заголовков B доступны для A во время компиляции, символы B доступны для A во время компоновки, а данные времени выполнения B доступны для A во время выполнения.
Инвариант всех правил заключается в том, что файлы, созданные правилом, всегда принадлежат тому же пакету, что и само правило; невозможно сгенерировать файлы в другой пакет. Однако входные данные правила нередко поступают из другого пакета.
Группы пакетов — это наборы пакетов, целью которых является ограничение доступности определенных правил. Группы пакетов определяются функцией package_group . У них есть три свойства: список пакетов, которые они содержат, их имя и другие группы пакетов, которые они включают. Единственными разрешенными способами ссылаться на них являются атрибут visibility правил или атрибут default_visibility функции package ; они не генерируют и не потребляют файлы. Для получения дополнительной информации обратитесь к документации package_group .