函式

目錄

• package
• package_group
• exports_files
• glob
• 選取
• 子套件

包裹

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

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

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

請在檔案頂端的所有 load() 陳述式之後，也就是任何規則之前，呼叫 package() 函式。

引數

範例

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

package_group

package_group(name, packages, includes)

這個函式會定義一組套件 並將標籤與資料集建立關聯標籤可在 visibility 屬性中參照。

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

如果指定套件符合 packages 屬性，或已包含在另一個項目中 includes 屬性中提及的套件群組。

包裝組群在技術上是目標，但並非由規則建立，也不具備任何瀏覽權限保護機制。

引數

範例

以下 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 翻轉之前，系統會以預設可見度匯出規則中提及的輸入檔案。不過，您不應依賴這種行為，也應積極避免使用這種行為。

引數

引數是目前套件中的檔案名稱清單。A 罩杯 也可以指定瀏覽權限宣告在這個範例中 所有指定目標都能查看如果未指定瀏覽權限， 會向每個套件顯示 指定於 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 檔案 (除非 foo/ 是子套件)
• 如果檔案結尾為 .txt，foo/*.txt 會比對 foo/ 目錄中的每個檔案 (除非 foo/ 是子專案)
• foo/a*.htm* 會比對 foo/ 目錄中以 a 開頭的每個檔案，接著會比對任意字串 (可為空白)，然後比對 .htm，最後比對另一個任意字串 (除非 foo/ 是子包)，例如 foo/axx.htm 和 foo/a.html 或 foo/axxx.html
• foo/* 與 foo/ 目錄中的所有檔案相符， (除非 foo/ 為子套件)；與 foo 不符 將 exclude_directories 設為 0 分
• foo/** 會比對每個非子套件子目錄中的所有檔案 位於套件的第一個子目錄 foo/ 下如果 exclude_directories已設為 0，foo 目錄本身也符合模式；在本例中，** 是 視為與零路徑區隔相符
• **/a.txt 與這個套件的 a.txt 個檔案相符 目錄以及非子套件子目錄
• **/bar/**/*.txt比對每個.txt檔案 非子目錄的子目錄 (如果 產生的路徑稱為 bar，例如 xxx/bar/yyy/zzz/a.txt 或 bar/a.txt (請注意， 「**」也與零區隔相符) 或「bar/zzz/a.txt」
• ** 會比對這個套件的每個非子套件子目錄中的每個檔案
• foo**/a.txt 是無效的模式，因為 ** 必須獨立於區段
• foo/ 是無效的模式，因為 / 後定義的第二個區段是空字串

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

如果 allow_empty 引數設為 False， glob 函式會在結果可能是 空白清單。

以下是幾個重要的限制和注意事項：

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

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

   如要瞭解這項功能，請注意 glob() 會傳回路徑清單，因此在其他規則屬性 (例如 srcs = glob(["*.cc"])) 中使用 glob() 的效果，就等同於明確列出相符的路徑。舉例來說，如果 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 檔案是否存在。也就是說，如果沒有名為 x/y 的套件，或已使用 --deleted_packages 標記為已刪除，同樣的 glob 運算式會包含 x/y/z.cc。

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

一般來說，您應盡量提供適當的副檔名 (例如 *.html)，而非使用裸字元 '*' 做為 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",
    ],
    ...
)

在目錄 testdata 中加入所有 txt 檔案 ( experiment.txt 除外)。 請注意，不含測試資料子目錄中的檔案。如果 您希望納入這些檔案，請使用遞迴 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 檔案建立，但路徑包含名為 testing 的目錄除外。請盡量避免採用這個模式，因為這可能會減少建構 進而增加建構時間。

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"]
    })
)

這會讓 srcs 屬性 取代一般標籤即可設定的 sh_binary 清單指派，並加上對應 select 的呼叫 比對值每個條件都是一個標籤 參照 是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() 的輔助函式 會列出子套件，而非檔案和目錄。這個 API 也使用相同的 視為 glob() 的路徑模式，且能比對 目前載入的 BUILD 檔案的直接子系。如需包含和篩選資料的詳細說明及範例，請參閱 glob 排除模式。

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

  範例

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

  # The following BUILD files exist:
  # foo/BUILD
  # foo/bar/baz/BUILD
  # foo/bar/but/bad/BUILD
  # foo/sub/BUILD
  # foo/sub/deeper/BUILD
  #
  # In foo/BUILD a call to
  subs1 = subpackages(include = ["**"])
  
  # results in subs1 == ["sub", "bar/baz", "bar/but/bad"]
  #
  # 'sub/deeper' is not included because it is a subpackage of 'foo/sub' not of
  # 'foo'
  
  subs2 = subpackages(include = ["bar/*"])
  # results in subs2 = ["bar/baz"]
  #
  # Since 'bar' is not a subpackage itself, this looks for any subpackages under
  # all first level subdirectories of 'bar'.
  
  subs3 = subpackages(include = ["bar/**"])
  # results in subs3 = ["bar/baz", "bar/but/bad"]
  #
  # Since bar is not a subpackage itself, this looks for any subpackages which are
  # (1) under all subdirectories of 'bar' which can be at any level, (2) not a
  # subpackage of another subpackages.
  
  subs4 = subpackages(include = ["sub"])
  subs5 = subpackages(include = ["sub/*"])
  subs6 = subpackages(include = ["sub/**"])
  # results in subs4 and subs6 being ["sub"]
  # results in subs5 = [].
  #
  # In subs4, expression "sub" checks whether 'foo/sub' is a package (i.e. is a
  # subpackage of 'foo').
  # In subs5, "sub/*" looks for subpackages under directory 'foo/sub'. Since
  # 'foo/sub' is already a subpackage itself, the subdirectories will not be
  # traversed anymore.
  # In subs6, 'foo/sub' is a subpackage itself and matches pattern "sub/**", so it
  # is returned. But the subdirectories of 'foo/sub' will not be traversed
  # anymore.
  

  一般而言，最好不要直接呼叫這個函式 使用者將「子套件」的模組 skylib。