Правила рабочей области

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

Примечание: помимо собственных правил рабочей области, Bazel также включает различные правила рабочей области Starlark, в частности те, которые предназначены для работы с репозиториями Git или архивами, размещёнными в сети.

Правила

• bind
• local_repository
• new_local_repository

bind

bind(name, actual, compatible_with, deprecation, distribs, features, licenses, restricted_to, tags, target_compatible_with, testonly, visibility)

Предупреждение: использование bind() не рекомендуется. См. "Рассмотрим удаление bind" для подробного обсуждения проблем и альтернатив. В частности, рассмотрите использование repo_mapping атрибутов репозитория.

Предупреждение: select() нельзя использовать в bind(). См. Вопросы и ответы по настраиваемым атрибутам для получения подробностей.

Присваивает целевому объекту псевдоним в пакете //external.

Пакет //external не является "обычным" пакетом: в нём нет каталога external/, поэтому его можно рассматривать как "виртуальный пакет", содержащий все привязанные целевые объекты.

Примеры

Чтобы присвоить целевому объекту псевдоним, bind его в файле WORKSPACE. Например, предположим, что есть целевой объект java_library под названием //third_party/javacc-v2. Его можно использовать как псевдоним, добавив следующее в файл WORKSPACE:

bind(
    name = "javacc-latest",
    actual = "//third_party/javacc-v2",
)

Теперь целевые объекты могут зависеть от //external:javacc-latest вместо //third_party/javacc-v2. Если javacc-v3 будет выпущен, правило bind можно будет обновить, и все файлы BUILD, зависящие от //external:javacc-latest, теперь будут зависеть от javacc-v3 без необходимости их редактирования.

Bind также можно использовать для предоставления доступа к целевым объектам во внешних репозиториях в вашей рабочей области. Например, если в файле WORKSPACE импортирован удалённый репозиторий под названием @my-ssl и в нём есть целевой объект cc_library //src:openssl-lib, вы можете создать псевдоним для этого целевого объекта, используя bind:

bind(
    name = "openssl",
    actual = "@my-ssl//src:openssl-lib",
)

Затем в файле BUILD в вашей рабочей области связанный целевой объект можно использовать следующим образом:

cc_library(
    name = "sign-in",
    srcs = ["sign_in.cc"],
    hdrs = ["sign_in.h"],
    deps = ["//external:openssl"],
)

В sign_in.cc и sign_in.h, к заголовочным файлам, экспортированным //external:openssl, можно обращаться, используя их путь относительно корня репозитория. Например, если определение правила для @my-ssl//src:openssl-lib выглядит так:

cc_library(
    name = "openssl-lib",
    srcs = ["openssl.cc"],
    hdrs = ["openssl.h"],
)

Тогда включения sign_in.cc могут выглядеть так:

#include "sign_in.h"
#include "src/openssl.h"

Аргументы

Атрибуты
name	Name; required Уникальное имя для этого целевого объекта.
actual	Label; optional Целевой объект, который нужно использовать как псевдоним. Этот целевой объект должен существовать, но может быть любого типа правила (включая bind). Если этот атрибут опущен, правила, ссылающиеся на этот целевой объект в //external , просто не увидят эту зависимость. Обратите внимание, что это отличается от полного пропуска правила bind: это ошибка, если зависимость //external не имеет связанного с ней правила bind.

local_repository

local_repository(name, path, repo_mapping)

Позволяет привязывать целевые объекты из локального каталога. Это означает, что текущий репозиторий может использовать целевые объекты, определённые в этом другом каталоге. Подробнее см. раздел bind.

Примеры

Предположим, что текущий репозиторий — это клиент чата, расположенный в каталоге ~/chat-app. Он хочет использовать библиотеку SSL, определённую в другом репозитории: ~/ssl. В библиотеке SSL есть целевой объект //src:openssl-lib.

Пользователь может добавить зависимость от этого целевого объекта, добавив следующие строки в ~/chat-app/WORKSPACE:

local_repository(
    name = "my-ssl",
    path = "/home/user/ssl",
)

Целевые объекты будут указывать на @my-ssl//src:openssl-lib в качестве зависимости для подключения к этой библиотеке.

Аргументы

Атрибуты
name	Name; required Уникальное имя для этого целевого объекта.
path	String; required Путь к каталогу локального репозитория. Это должен быть путь к каталогу, содержащему файл WORKSPACE репозитория. Путь может быть абсолютным или относительным к файлу WORKSPACE основного репозитория.
repo_mapping	Dictionary: String -> String; optional Словарь из имени локального репозитория в глобальное имя репозитория. Это позволяет управлять разрешением зависимостей рабочей области для зависимостей этого репозитория. Например, запись "@foo": "@bar" указывает, что всякий раз, когда этот репозиторий зависит от "@foo" (например, от зависимости "@foo//some:target"), он должен разрешать эту зависимость в глобально объявленном "@bar" ("@bar//some:target").

new_local_repository

new_local_repository(name, build_file, build_file_content, path, repo_mapping, workspace_file, workspace_file_content)

Позволяет преобразовать локальный каталог в репозиторий Bazel. Это означает, что текущий репозиторий может определять и использовать целевые объекты из любой точки файловой системы.

Это правило создаёт репозиторий Bazel, создавая файл WORKSPACE и подкаталог, содержащий ссылки на файл BUILD и заданный путь. Файл сборки должен создавать целевые объекты относительно path. Для каталогов, уже содержащих файл WORKSPACE и файл BUILD, можно использовать правило local_repository.

Примеры

Предположим, что текущий репозиторий — это клиент чата, расположенный в каталоге ~/chat-app. Он хочет использовать библиотеку SSL, определённую в другом каталоге: ~/ssl.

Пользователь может добавить зависимость, создав файл BUILD для библиотеки SSL (~/chat-app/BUILD.my-ssl) содержащий:

java_library(
    name = "openssl",
    srcs = glob(['*.java'])
    visibility = ["//visibility:public"],
)

Затем они могут добавить следующие строки в ~/chat-app/WORKSPACE:

new_local_repository(
    name = "my-ssl",
    path = "/home/user/ssl",
    build_file = "BUILD.my-ssl",
)

Это создаст репозиторий @my-ssl, который создаёт символическую ссылку на /home/user/ssl. Целевые объекты могут зависеть от этой библиотеки, добавив @my-ssl//:openssl в зависимости целевого объекта.

Вы также можете использовать new_local_repository для включения отдельных файлов, а не только каталогов. Например, предположим, что у вас есть файл jar в /home/username/Downloads/piano.jar. Вы можете добавить только этот файл в сборку, добавив следующее в файл WORKSPACE:

new_local_repository(
    name = "piano",
    path = "/home/username/Downloads/piano.jar",
    build_file = "BUILD.piano",
)

И создав следующий файл BUILD.piano:

java_import(
    name = "play-music",
    jars = ["piano.jar"],
    visibility = ["//visibility:public"],
)

Затем целевые объекты могут зависеть от @piano//:play-music для использования piano.jar.

Аргументы

Атрибуты
name	Name; required Уникальное имя для этого целевого объекта.
build_file	String; optional Файл для использования в качестве файла BUILD для этого каталога. Должен быть указан либо build_file, либо build_file_content. Этот атрибут — это метка, относительная к основной рабочей области. Файл не обязательно должен называться BUILD, но может.
build_file_content	String; optional Содержимое файла BUILD для этого репозитория. Должен быть указан либо build_file, либо build_file_content.
path	String; required Путь в локальной файловой системе. Он может быть как абсолютным, так и относительным к файлу WORKSPACE основного репозитория.
repo_mapping	Dictionary: String -> String; optional Словарь из имени локального репозитория в глобальное имя репозитория. Это позволяет управлять разрешением зависимостей рабочей области для зависимостей этого репозитория. Например, запись "@foo": "@bar" указывает, что всякий раз, когда этот репозиторий зависит от "@foo" (например, от зависимости "@foo//some:target"), он должен разрешать эту зависимость в глобально объявленном "@bar" ("@bar//some:target").
workspace_file	String; optional Файл для использования в качестве файла WORKSPACE для этого репозитория. Можно указать либо workspace_file, либо workspace_file_content, но не оба. Этот атрибут — это метка, относительная к основной рабочей области. Файл не обязательно должен называться WORKSPACE, но может.
workspace_file_content	String; optional Содержимое файла WORKSPACE для этого репозитория. Можно указать либо workspace_file, либо workspace_file_content, но не оба.