函式

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

目錄

• package
• package_group
• exports_files
• glob
• 選取
• subpackages

包裹

package(default_deprecation, default_package_metadata, default_testonly, default_visibility, features)

這個函式會宣告套件中每個規則都適用的中繼資料。在套件 (BUILD 檔案) 中最多使用一次。

宣告中繼資料要套用至整體規則中各項規則的對應工具 存放區，請使用 repo() 函式的 存放區根目錄的 REPO.bazel 檔案。 repo() 函式使用的引數與 package() 完全相同。

畫面頂端所有 load() 陳述式的後面都應呼叫 package() 函式 檔案。

引數

屬性	說明
default_applicable_licenses	default_package_metadata 的別名。
default_visibility	標籤清單；預設為 [] 這個套件中規則的預設瀏覽權限。 這個套件中的每個規則都有指定的瀏覽權限 屬性，除非 visibility 中另有指定 參照規則的屬性。如要進一步瞭解這項屬性的語法，請參閱可見度的說明文件。套件預設瀏覽權限不適用於 exports_files，該檔案預設為公開。
default_deprecation	String;預設值為 "" 為此套件中的所有規則設定預設 deprecation 訊息。
default_package_metadata	標籤清單；預設為 [] 設定要套用至套件中所有其他目標的預設中繼資料目標清單。 這些通常是與 OSS 套件和授權聲明相關的目標。 如需範例，請參閱 rules_license。
default_testonly	布林值；預設值為 False，但另有註明 設定預設值 testonly 屬性。 javatests 底下的套件，預設值為 True。
features	清單字串；預設為 [] 設定各種會影響這個 BUILD 檔案語意的旗標。 這項功能主要供建構系統工作人員使用，用來標記需要特殊處理的套件。除非 明確要求。

範例

以下宣告聲明指出，只有套件群組 //foo:target 的成員才能看到這個套件中的規則。規則中的個別顯示設定聲明 (如有) 會覆寫此規格。

package(default_visibility = ["//foo:target"])

package_group

package_group(name, packages, includes)

這個函式會定義一組套件，並將標籤與該組套件建立關聯。標籤可在以下位置中參照： visibility 屬性。

套件群組主要用於控管瀏覽權限。公開顯示 目標架構可以從來源樹狀結構中的每個套件參照。私密 可見目標只能在本身的套件 (而非子套件) 中參照。 在這些極端情況之間，目標可能會允許存取其自身套件，以及一或多個套件群組所描述的任何套件。如需瀏覽權限系統的詳細說明，請參閱 visibility 屬性。

如果特定套件符合 packages 屬性，或是已包含在 includes 屬性中提及的其他套件群組中，就會被視為該群組的一部分。

套件群組在技術上屬於目標，但不是由規則建立，而且 就沒有任何瀏覽權限保護

引數

屬性	說明
name	名稱 (必填) 這個目標的專屬名稱。
packages	字串清單；預設值為 [] 零或多個套件規格的清單。 每個套件規格字串可以採用下列任一形式： 套件的全名 (不含存放區)，開頭為 雙斜線例如，//foo/bar 會指定套件名稱，且該套件名稱與套件群組位於相同的存放區。 與上述相同，但結尾為 /...。例如， //foo/... 指定 //foo 和其所有 子套件。//... 會指定目前存放區中的所有套件。 public 或 private 字串， 請分別指定每個套件或沒有套件。(這份表單為 標記 --incompatible_package_group_has_public_syntax 即可 )。 此外，前兩種套件規格也可以在前面加上 - 前置詞，表示為否定。 套件群組包含至少符合其中一個正面規格，且不符合任何負面規格的任何套件。舉例來說，值 [//foo/..., -//foo/tests/...] 包含所有 //foo 的子套件，但不包含 //foo/tests 的子套件。(//foo 本身已包含，但 //foo/tests 本身並未包含)。 除了公開顯示的瀏覽權限之外，你也無法直接指定 目前存放區以外的套件 如果缺少這項屬性，就等同於將其設為空白清單，也等同於將其設為只包含 private 的清單。 注意：在 Bazel 6.0 之前，規格 //... 的舊版行為與 public 相同。啟用 --incompatible_fix_package_group_reporoot_syntax 時，這項行為會修正，這是 Bazel 6.0 之後的預設行為。 注意：在 Bazel 6.0 之前，如果這項屬性以 bazel query --output=proto (或 --output=xml) 的一部分序列化，開頭的斜線會省略。舉例來說，//pkg/foo/... 會輸出為 \"pkg/foo/...\"。啟用 --incompatible_package_group_includes_double_slash 時，這項行為會修正，這是 Bazel 6.0 之後的預設值。
includes	標籤清單；預設為 [] 包含的其他套件群組。 這個屬性中的標籤必須參照其他套件群組。 參照套件群組中的套件將納入此元件 套件群組。這項屬性是傳遞性的，如果套件群組 a 包含套件群組 b，而 b 包含套件群組 c，那麼 c 中的每個套件也會是 a 的成員。 與否定套件規格搭配使用時，請注意，每個群組的套件組合會先獨立計算，然後再將結果聯集。也就是說 不會影響 另一個群組。

範例

下列 package_group 宣告會指定 名為「tropical」的套件群組含有熱帶水果。

package_group(
    name = "tropical",
    packages = [
        "//fruits/mango",
        "//fruits/orange",
        "//fruits/papaya/...",
    ],
)

下列宣告內容指定虛構的套裝方案群組 應用程式：

package_group(
    name = "fooapp",
    includes = [
        ":controller",
        ":model",
        ":view",
    ],
)

package_group(
    name = "model",
    packages = ["//fooapp/database"],
)

package_group(
    name = "view",
    packages = [
        "//fooapp/swingui",
        "//fooapp/webui",
    ],
)

package_group(
    name = "controller",
    packages = ["//fooapp/algorithm"],
)

exports_files

exports_files([label, ...], visibility, licenses)

exports_files() 會指定屬於此套件且匯出至其他套件的檔案清單。

套件的 BUILD 檔案只能直接參照屬於其他套件的來源檔案，前提是這些來源檔案必須使用 exports_files() 陳述式明確匯出。進一步瞭解 檔案的瀏覽權限。

做為舊版行為，凡是被提及為規則輸入內容的檔案，系統都會匯出 保持啟用狀態，直到標記 --incompatible_no_implicit_file_export 但快速又簡單然而，出現這種情況時，不應仰賴並主動採取這個做法 其他用途

引數

引數是目前套件中的檔案名稱清單。您也可以指定可見度宣告；在這種情況下，檔案會對指定的目標顯示。如果未指定可見度，則所有套件都能看到這些檔案，即使在 package 函式中指定了套件的預設可見度也一樣。授權 也可以指定

範例

以下範例會匯出 golden.txt，這是 test_data 套件中的文字檔案，方便其他套件使用，例如在測試的 data 屬性中。

# from //test_data/BUILD

exports_files(["golden.txt"])

glob

glob(include, exclude=[], exclude_directories=1, allow_empty=True)

Glob 是輔助函式，可找出符合特定路徑模式的所有檔案，並傳回新的可變更且已排序的路徑清單。Glob 只會搜尋檔案 本身俱備專屬套件，而且只會尋找來源檔案 (不會產生 其他目標)。

如果來源檔案的套件相對路徑，結果會包含在結果中 路徑符合任一 include 模式，但沒有任何 exclude 個模式。

include 和 exclude 清單包含相對於目前套件的路徑模式。每個模式可能包含一或多個路徑區段。和 Unix 路徑一樣，這些區隔會按照 /。片段可包含 * 萬用字元：這會比對路徑片段中的任何子字串 (包括空白子字串)，但不包含目錄分隔符 /。這個萬用字元可以在單一路徑區段中使用多次。此外，** 萬用字元可以比對 零或多個完整路徑區隔，但必須宣告為獨立路徑 路徑片段

示例：

• foo/bar.txt 與這個套件中的 foo/bar.txt 檔案完全相符
• 如果檔案結尾為 .txt，foo/*.txt 會比對 foo/ 目錄中的每個檔案 (除非 foo/ 是子包)
• foo/a*.htm* 會比對 foo/ 目錄中開頭為 a 的每個檔案，接著會包含任意字串 (可為空白)，然後是 .htm，最後結尾為其他任意字串，例如 foo/axx.htm 和 foo/a.html 或 foo/axxx.html
• **/a.txt 會比對這個套件中每個子目錄中的每個 a.txt 檔案
• **/bar/**/*.txt比對每個.txt檔案 如果產生的路徑上至少有一個目錄為 呼叫 bar，例如 xxx/bar/yyy/zzz/a.txt 或 bar/a.txt (請注意，** 也與零相符 區隔) 或 bar/zzz/a.txt。
• ** 會比對此目錄內每個子目錄中的每個檔案 包裹
• foo**/a.txt 是無效模式，因為 ** 必須獨立於區段

如果 exclude_directories 引數已啟用 (設為 1)， type 目錄會省略結果內 (預設值為 1)。

如果 allow_empty 引數設為 False，如果結果是空白清單，glob 函式就會傳回錯誤。

這項功能有幾項重要限制和警告事項：

1. glob() 會在評估 BUILD 檔案期間執行， glob() 只會比對來源樹狀結構中的檔案，永遠不會比對 產生的檔案。如果您建構的目標需要原始檔案和產生的檔案，則必須在 glob 中附加明確的產生檔案清單。請參閱以下範例，其中包含 :mylib 和 :gen_java_srcs。

2. 如果規則名稱與相符的來源檔案相同，規則就會 「陰影」檔案。

   為了瞭解這一點，請注意 glob() 會傳回 路徑，因此請在其他規則中使用 glob()屬性 (例如 srcs = glob(["*.cc"])) 的效果與列出 進行比對舉例來說，如果 glob() 產生 ["Foo.java", "bar/Baz.java"]，但套件中也有名為「Foo.java」的規則 (雖然 Bazel 會發出警告，但這項操作是允許的)，則 glob() 的使用者會使用「Foo.java」規則 (其輸出內容)，而非「Foo.java」檔案。詳情請見 GitHub 問題 #10395 瞭解詳情。

3. Globs 可能會比對子目錄中的檔案。以及子目錄名稱 可能遭到萬用字元編碼。不過...

4. 標籤不得跨越套件邊界，而 glob 可以 和子套件中的檔案不相符。

   例如：套件中的 glob 運算式 **/*.cc 如果符合以下條件，x 不包含 x/y/z.cc x/y 是以套件形式存在 (可以是 x/y/BUILD，或套件路徑上的其他位置)。這個 表示 glob 運算式的結果實際上取決於 BUILD 檔案的存在，也就是說，相同的 glob 運算式 如果沒有呼叫套件，請包含 x/y/z.cc x/y，或是使用 --deleted_packages 旗標。

5. 上述限制適用於所有 glob 運算式，不論使用哪個萬用字元。
6. 檔案名稱以 . 開頭的隱藏檔案，會完全符合 ** 和 * 通配字元。如果您想比對隱藏檔案的複合模式，模式開頭必須是 .。舉例來說，* 和 .*.txt 會與 .foo.txt 相符，但 *.txt 則不會。隱藏目錄也會以同樣的方式比對。隱藏的資料夾可能包含不需要做為輸入內容的檔案，並且可能會增加不必要的 globbed 檔案數量和記憶體用量。排除目標 請將它們加進 [排除]list 引數。
7. 「**」萬用字元有一個邊角大小寫：模式 "**" 與套件的目錄路徑不符。也就是說，glob(["**"], exclude_directories = 0) 會嚴格地比對目前套件目錄下所有檔案和目錄的傳遞 (但當然不會進入子套件的目錄 - 請參閱前述的相關附註)。

一般來說，建議您嘗試提供適當的擴充功能 (例如 *.html) 而不是使用 bare '*' 來進行 glob 模式。更明確的名稱 都需自行記錄，確保不會意外比對到備份 檔案，或是 emacs/vi/... 自動儲存檔案。

編寫建構規則時，您可以列舉 glob 的元素。這個 能為每個輸入內容產生個別規則請參閱下方的擴充 glob 範例。

Glob 範例

根據這個目錄中的所有 Java 檔案，建立 Java 程式庫。 以及 :gen_java_srcs 規則產生的所有檔案

java_library(
    name = "mylib",
    srcs = glob(["*.java"]) + [":gen_java_srcs"],
    deps = "...",
)

genrule(
    name = "gen_java_srcs",
    outs = [
        "Foo.java",
        "Bar.java",
    ],
    ...
)

在目錄測試資料中加入所有 txt 檔案 ( experiment.txt 除外)。 請注意，testdata 子目錄中的檔案不會納入。如果您想納入這些檔案，請使用遞迴 glob (**)。

sh_test(
    name = "mytest",
    srcs = ["mytest.sh"],
    data = glob(
        ["testdata/*.txt"],
        exclude = ["testdata/experimental.txt"],
    ),
)

遞迴 Glob 範例

讓測試依附於 testdata 目錄中的所有 txt 檔案， 其子目錄 (及其子目錄等)。 系統會忽略含有 BUILD 檔案的子目錄。(查看限制 和上述注意事項)

sh_test(
    name = "mytest",
    srcs = ["mytest.sh"],
    data = glob(["testdata/**/*.txt"]),
)

根據這個目錄中的所有 Java 檔案，建立程式庫 子目錄。 盡可能避免使用這種模式，因為這可能會降低建構增量，進而增加建構時間。

java_library(
    name = "mylib",
    srcs = glob(
        ["**/*.java"],
        exclude = ["**/testing/**"],
    ),
)

展開的 Glob 範例

在目前目錄中為 *_test.cc 建立個別的 genrule，用於計算檔案中的行數。

# Conveniently, the build language supports list comprehensions.
[genrule(
    name = "count_lines_" + f[:-3],  # strip ".cc"
    srcs = [f],
    outs = ["%s-linecount.txt" % f[:-3]],
    cmd = "wc -l $< >$@",
 ) for f in glob(["*_test.cc"])]

如果上述 BUILD 檔案位於 //foo 套件中，且套件包含三個相符的檔案 (a_test.cc、b_test.cc 和 c_test.cc)，則執行 bazel query '//foo:all' 會列出產生的所有規則：

$ bazel query '//foo:all' | sort
//foo:count_lines_a_test
//foo:count_lines_b_test
//foo:count_lines_c_test

選取

select(
    {conditionA: valuesA, conditionB: valuesB, ...},
    no_match_error = "custom message"
)

select() 是輔助函式，可讓規則屬性可設定。它可以取代 幾乎 任何屬性指派，因此其值取決於指令列 Bazel 標記。 舉例來說，您可以使用這項功能定義平台專屬的依附元件，或 根據「developer」 與「發行」相較模式。

基本使用方法如下：

sh_binary(
    name = "mytarget",
    srcs = select({
        ":conditionA": ["mytarget_a.sh"],
        ":conditionB": ["mytarget_b.sh"],
        "//conditions:default": ["mytarget_default.sh"]
    })
)

這樣一來，您就能透過將 sh_binary 的一般標籤清單指派項目替換為 select 呼叫，讓 srcs 屬性可進行設定，進而將設定條件對應至相符的值。每個條件都是參照 config_setting 或 constraint_value 的標籤，如果目標的設定符合預期的值集，則會「相符」。mytarget#srcs 的值會成為 標籤清單與目前的叫用相符

注意：

• 每次呼叫都會選取一個條件。
• 如果有多個條件相符，且其中一個條件是其他條件的專門領域，系統會優先採用專門領域。如果條件 B 與條件 A 的標記和限制值完全相同，且包含一些額外的標記或限制值，則系統會將條件 B 視為條件 A 的專門化。這也 代表在建立訂單時， 如下方範例 2 所示
• 如果有多個條件相符，但其中一個不是其他條件的專門化，除非所有條件都解析為相同的值，否則 Bazel 會失敗並顯示錯誤訊息。
• 如果沒有其他條件符合，系統會將特殊的虛擬標籤 //conditions:default 視為相符。如果這項條件成立 其他規則必須符合這些條件才不會發生錯誤。
• select 可嵌入內部較大的 屬性。因此 srcs = ["common.sh"] + select({ ":conditionA": ["myrule_a.sh"], ...}) 和 srcs = select({ ":conditionA": ["a.sh"]}) + select({ ":conditionB": ["b.sh"]}) 都是有效的運算式。
• select 適用於大多數屬性，但並非全部屬性。不相容 在相關說明文件中標示 nonconfigurable。

  子套件

  subpackages(include, exclude=[], allow_empty=True)

  subpackages() 是類似 glob() 的輔助函式 會列出子套件，而非檔案和目錄。它使用與 glob() 相同的路徑模式，可比對目前載入的 BUILD 檔案的直接子項的任何子專案。如需包含和排除模式的詳細說明和範例，請參閱 glob。

  傳回的子套件清單會按照排序順序，包含 目前載入套件中符合指定模式的路徑 include而非 exclude 中的使用者。

  範例

  以下範例會列出套件 foo/BUILD 的所有直接子包

  # The following BUILD files exist:
  # foo/BUILD
  # foo/bar/baz/BUILD
  # foo/sub/BUILD
  # foo/sub/deeper/BUILD
  #
  # In foo/BUILD a call to
  subs = subpackages(include = ["**"])
  
  # results in subs == ["sub", "bar/baz"]
  #
  # 'sub/deeper' is not included because it is a subpackage of 'foo/sub' not of
  # 'foo'
  

  一般來說，建議使用者使用 skylib 的「subpackages」模組，而非直接呼叫這個函式。