工作區規則

回報問題 查看原始碼 Nightly · 7.4 . 7.3 · 7.2 · 7.1 · 7.0 · 6.5

工作區規則用於提取外部依附元件,通常是位於主要存放區外的來源程式碼。

注意:除了原生工作區規則外,Bazel 也會嵌入各種 Starlark 工作區規則,特別是用於處理網站上代管的 git 存放區或封存檔。

規則

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 套件並非「一般」套件:沒有外部/ 目錄,因此可視為包含所有繫結目標的「虛擬套件」。

範例

如要為目標指定別名,請在 WORKSPACE 檔案中 bind 該目標。舉例來說,假設有一個名為 //third_party/javacc-v2java_library 目標。如要為此建立別名,請在 WORKSPACE 檔案中新增以下內容:

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

目標現在可以依附 //external:javacc-latest,而非 //third_party/javacc-v2。如果發布 javacc-v3,bind 規則即可更新,而所有依附 //external:javacc-latest 的 BUILD 檔案現在都會依附於 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.ccsign_in.h 中,您可以使用相對於存放區根目錄的路徑,參照 //external:openssl 公開的標頭檔案。舉例來說,如果 @my-ssl//src:openssl-lib 的規則定義如下:

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

sign_in.cc 的 includes 可能會如下所示:

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

引數

屬性
name

名稱;必填

此目標的專屬名稱。

actual

標籤;預設值為 None

要建立別名的目標。

這個目標必須存在,但可以是任何類型的規則 (包括繫結)。

如果省略這項屬性,在 //external 中參照這個目標的規則將不會看到這個依附元件邊緣。請注意,這與完全省略 bind 規則不同:如果 //external 依附元件沒有相關聯的 bind 規則,就會發生錯誤。

local_repository

查看規則來源
local_repository(name, path, repo_mapping)

允許繫結本機目錄的目標。也就是說,目前的存放區可以使用這個其他目錄中定義的目標。詳情請參閱繫結一節

範例

假設目前的存放區是聊天用戶端,根目錄為 ~/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

名稱;必填

此目標的專屬名稱。

path

字串;必填

本機存放區目錄的路徑。

這個路徑必須是包含存放區 WORKSPACE 檔案的目錄路徑。路徑可以是相對於主要存放區 WORKSPACE 檔案的絕對路徑或相對路徑。

repo_mapping

字典:字串 -> 字串;預設為 {}

從本機存放區名稱到全域存放區名稱的字典。這樣一來,您就能控管這個存放區依附元件的依附元件解析工作區。

舉例來說,項目 "@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 存放區。也就是說,目前的存放區可以定義並使用檔案系統中任何位置的目標。

這個規則會建立 WORKSPACE 檔案和子目錄,其中包含指向 BUILD 檔案和指定路徑的符號連結,藉此建立 Bazel 存放區。建構檔案應建立相對於 path 的目標。如果目錄已包含 WORKSPACE 檔案和 BUILD 檔案,則可使用 local_repository 規則。

範例

假設目前的存放區是聊天用戶端,根目錄為 ~/chat-app。它想要使用在不同目錄 ~/ssl 中定義的 SSL 程式庫。

使用者可以為 SSL 程式庫 (~/chat-app/BUILD.my-ssl) 建立 BUILD 檔案,藉此新增依附元件,其中包含:

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 納入單一檔案,而非目錄。舉例來說,假設您有位於 /home/username/Downloads/piano.jar 的 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

名稱;必填

這個目標的專屬名稱。

build_file

名稱;預設為 None

這個目錄要使用的 BUILD 檔案。

必須指定 build_file 或 build_file_content。

這個屬性是相對於主要工作區的標籤。檔案不必命名為 BUILD,但也有可能具備。(例如 BUILD.new-repo-name 可能很適合用來區分實際的 BUILD 檔案和存放區)。

build_file_content

字串;預設值為 ""

此存放區的 BUILD 檔案內容。

必須指定 build_file 或 build_file_content。

path

字串;必填

本機檔案系統的路徑。

這個路徑可以是相對於主存放區 WORKSPACE 檔案的絕對路徑或相對路徑。

repo_mapping

字典:字串 -> 字串;預設值為 {}

從本機存放區名稱到全域存放區名稱的字典。這樣一來,您就能控管這個存放區依附元件的依附元件解析工作區。

舉例來說,項目 "@foo": "@bar" 宣告,每次這個存放區依附 "@foo" (例如依附 "@foo//some:target") 時,實際上應在全域宣告的 "@bar" ("@bar//some:target") 中解析該依附元件。

workspace_file

名稱;預設為 None

要做為這個存放區 WORKSPACE 檔案的檔案。

您可以指定 workspace_file 或 workspace_file_content,但不能同時指定兩者。

這個屬性是相對於主要工作區的標籤。檔案不必命名為 WORKSPACE,但可以符合(例如 WORKSPACE.new-repo-name 可能很適合用來區分存放區的實際 WORKSPACE 檔案)。

workspace_file_content

字串;預設為 ""

這個存放區的 WORKSPACE 檔案內容。

可以指定 workspace_file 或 workspace_file_content 屬性,但不能兩者都指定。