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

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

Примечание: помимо собственных правил рабочей области, 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(). См. Раздел FAQ по настраиваемым атрибутам для получения подробной информации.

Присваивает целевому объекту псевдоним в пакете //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.new-repo-name может хорошо подойти для отличия его от фактических файлов 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.new-repo-name может хорошо подойти для отличия его от фактических файлов WORKSPACE репозитория.)
workspace_file_content	String; optional Содержимое файла WORKSPACE для этого репозитория. Можно указать либо workspace_file, либо workspace_file_content, но не оба одновременно.