標籤

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

標籤是目標的 ID。一般標籤的完整標準形式如下:

@@myrepo//my/app/main:app_binary

標籤的第一部分是存放區名稱 @@myrepo。Double-@ 語法表示這是工作區中不重複的「標準」存放區名稱。標籤如果含有標準的 repo 名稱,無論出現在何種情境中,都能明確識別目標。

標準存放區名稱通常是混用字串,看起來像 @@rules_java~7.1.0~toolchains~local_jdk。更常見的是標記具有明顯的存放區名稱,如下所示:

@myrepo//my/app/main:app_binary

唯一的差別在於存放區名稱的前置字串是一個 @,而非兩個。這裡指的是名稱為 myrepo 的存放區,這個名稱可能會因標籤出現的上下文而有所不同。

在一般情況下,如果標籤參照的是使用該標籤的相同存放區,則可以省略存放區名稱部分。因此在 @@myrepo 中 第一個標籤的寫法通常是

//my/app/main:app_binary

標籤的第二部分是未限定的套件名稱 my/app/main,也就是相對於存放區根目錄的套件路徑。存放區名稱和未加修飾符的套件名稱會組成完整的套件名稱 @@myrepo//my/app/main。如果標籤參照使用的套件,可能會省略套件名稱 (可選擇加上冒號)。因此,在 @@myrepo//my/app/main 中,這個標籤可以採用下列任一方式編寫:

app_binary
:app_binary

根據慣例,檔案會省略冒號,規則則會保留冒號,但這並非必要。

標籤中冒號後的部分 (app_binary) 是未限定的目標名稱。如果與套件路徑的最後一個元件相符,則可省略該元件和冒號。因此,這兩個標籤的作用相同:

//my/app/lib
//my/app/lib:lib

套件子目錄中的檔案目標名稱為檔案在套件根目錄 (包含 BUILD 檔案的目錄) 相對的路徑。因此,這個檔案位於存放區的 my/app/main/testdata 子目錄中:

//my/app/main:testdata/input.txt

//my/app@@some_repo//my/app 這類字串有兩種含義,取決於使用時的情況:當 Bazel 預期標籤時,分別代表 //my/app:app@@some_repo//my/app:app。但當 Bazel 預期某個套件 (例如 package_group 規格) 時,就會參照含有該標籤的套件。

BUILD 檔案中的常見錯誤是使用 //my/app 來參照套件,或參照套件中的「所有」目標,不會發生這種錯誤。請注意,它等同於 //my/app:app,因此會命名目前存放區 my/app 套件中的 app 目標。

不過,在 package_group.bzl 檔案的規格中,建議使用 //my/app 來參照套件,因為這可清楚表示套件名稱為絕對值,且位於工作區頂層目錄中。

相對標籤無法用於參照其他套件中的目標;在這種情況下,必須一律指定存放區 ID 和套件名稱。舉例來說,如果來源樹狀結構包含套件 my/app 和套件 my/app/testdata (這兩個目錄各自都有 BUILD 檔案),後者套件會包含名為 testdepot.zip 的檔案。以下是兩種在 //my/app:BUILD 中參照此檔案的方式 (一個錯誤,一個正確):

錯誤testdata 是不同的套件,因此您無法使用相對路徑

testdata/testdepot.zip

正確:參照 testdata 及其完整路徑

//my/app/testdata:testdepot.zip

@@// 開頭的標籤是主要存放區的參照項目,即使來自外部存放區,仍可正常運作。因此,從外部存放區參照 @@//a/b/c 時,它與 //a/b/c 不同。前者會參照主要存放區,後者則會在外部存放區中尋找 //a/b/c。在主要存放區中撰寫參照主要存放區中目標的規則時,這一點尤其重要,且會從外部存放區使用。

如要瞭解如何參照目標的不同方式,請參閱目標模式

標籤的語彙規格

標籤語法不建議使用對殼層具有特殊意義的中繼字元。這有助於避免不慎引用問題,並且可更輕鬆地建構操縱標籤的工具和指令碼 (例如 Bazel Query Language)。

以下是允許的目標名稱詳細資料。

目標名稱:package-name:target-name

target-name 是套件中的目標名稱。規則名稱是 BUILD 檔案中規則宣告內 name 屬性的值;檔案名稱則是相對於包含 BUILD 檔案的目錄的路徑名稱。

目標名稱必須由 azAZ09 以及標點符號 !%-@^_"#$&'()*-+,;<=>?[]{|}~/. 組合繪製的字元組成。

檔案名稱必須是正常形式的相對路徑名稱,也就是說,檔案名稱開頭和結尾不得使用斜線 (例如 /foofoo/ 皆為禁止的名稱),也不得包含多個連續的斜線做為路徑分隔符號 (例如 foo//bar)。同樣地,上層參照 (..) 和目前目錄參照 (./) 也是禁止的名稱。

錯誤:請勿使用 `..` 參照其他套件中的檔案

正確:使用 `//package-name:filename`

雖然檔案目標名稱使用 / 是很常見的做法,但請避免在規則名稱中使用 /。尤其是使用簡寫形式的標籤時,可能會讓讀者感到困惑。標籤 //foo/bar/wiz 一律是 //foo/bar/wiz:wiz 的簡寫,即使沒有這樣的套件 foo/bar/wiz 也一樣;即使目標存在,也不會參照 //foo:bar/wiz

不過,在某些情況下使用斜線會比較方便,甚至有時是必要的。舉例來說,某些規則的名稱必須與主要來源檔案相符,而該檔案可能位於套件的子目錄中。

套件名稱://package-name:target-name

套件的名稱是指包含 BUILD 檔案的目錄名稱,相對於包含的存放區頂層目錄。例如:my/app

套件名稱必須完全由 A-Zaz09、'/'、'-'、'.'、'@' 和 '_' 集合中的字元組成,且開頭不得為斜線。

如果語言具有對其模組系統有意義的目錄結構 (例如 Java),請務必選擇在該語言中有效的識別項做為目錄名稱。

雖然 Bazel 支援工作區根套件 (例如 //:foo) 中的目標,但建議您將該套件留空,讓所有有意義的套件都有描述性名稱。

套件名稱不得包含子字串 //,也不能以斜線結尾。

規則

規則會指定輸入和輸出之間的關係,以及建構輸出的步驟。規則可以是許多不同類型 (有時稱為規則類別) 之一,可產生編譯的執行檔和程式庫、測試執行檔和其他支援的輸出內容,如建構百科全書所述。

BUILD 檔案會透過叫用規則宣告目標

在以下範例中,我們會看到使用 cc_binary 規則宣告目標 my_app

cc_binary(
    name = "my_app",
    srcs = ["my_app.cc"],
    deps = [
        "//absl/base",
        "//absl/strings",
    ],
)

每個規則叫用都有 name 屬性 (必須是有效的目標名稱),可在 BUILD 檔案的套件中宣告目標。

每項規則都有一組「屬性」;特定規則的適用屬性,且每個屬性的顯著性和語意都是該規則的函式。如需規則及對應屬性的清單,請參閱「建構百科全書」。每個屬性都有名稱和類型屬性可有的常見類型包括整數、標籤、標籤清單、字串、字串清單、輸出標籤、輸出標籤清單。並非每個規則都需要指定所有屬性。因此,屬性會形成字典,從鍵 (名稱) 到選用型別值。

許多規則中的 srcs 屬性類型為「標籤清單」;如果有值,則為標籤清單,每個標籤都是這個規則的輸入目標名稱。

在某些情況下,規則類型的名稱會有所不同,但更有趣的是規則產生的檔案名稱,這也是 genrules 的情況。詳情請參閱「一般規則:genrule」。

在其他情況下,名稱則具有重要意義:舉例來說,對於 *_binary*_test 規則,規則名稱會決定建構作業產生的可執行檔名稱。

這個與目標有關的非循環圖稱為「目標圖表」或「建構依附元件圖表」,也是 Bazel 查詢工具運作的網域。

目標 BUILD 檔案