一般規則

回報問題 。 。 查看來源 。 。 。 。 。 夜間 。 。 。 7.3 。 。 7.2 。 7.1 。 。 7.0 。 。 6.5

規則

別名

查看規則來源 
alias(name, actual, compatible_with, deprecation, features, restricted_to, tags, target_compatible_with, testonly, visibility)

alias 規則會建立可以指稱規則的名稱。

別名僅適用於「regular」目標。尤其是 package_group 和 test_suite 無法使用別名。

在大型存放區中，重新命名目標需要變更名稱時，別名或許能派上用場 對大量檔案所做的變更您也可以使用別名規則 select 函式呼叫則可重複使用該邏輯 有多個目標。

別名規則有專屬的瀏覽權限宣告。在所有其他情況下 就像參照規則一樣 (例如，系統會忽略「在別名上」的測試；僅供測試使用) 所參照的規則)，但有些微狀況除外：

  • 如果指令列中提及別名，測試就不會執行。如何定義別名 執行參照的測試，請使用 test_suite 規則只有一項目標tests 屬性。
  • 定義環境群組時，environment 規則的別名不會 支援。--target_environment 指令列不支援這些項目 或任一選項

範例

filegroup(
    name = "data",
    srcs = ["data.txt"],
)

alias(
    name = "other",
    actual = ":data",
)

引數

屬性
name

名稱；必選

此目標的專屬名稱。
actual

標籤；必選

這個別名參照的目標。不需要規則，也可以是輸入內容 檔案。

config_setting

查看規則來源 
config_setting(name, constraint_values, define_values, deprecation, distribs, features, flag_values, licenses, tags, testonly, values, visibility)

與應用程式的預期設定狀態 (以建構標記或平台限製表示) 相符 觸發可設定屬性的目的。查看選取： 如何使用這項規則， 可設定的屬性：提供一般功能的總覽。

範例

下列程式碼會與設定 --compilation_mode=opt 或 -c opt (可在指令列中明確指定，或是從 .bazelrc 檔案明確指定)： 

  config_setting(
      name = "simple",
      values = {"compilation_mode": "opt"}
  )

下列指令會比對指定 ARM 的所有版本，並套用自訂定義 FOO=bar (例如 bazel build --cpu=arm --define FOO=bar ...)： 

  config_setting(
      name = "two_conditions",
      values = {
          "cpu": "arm",
          "define": "FOO=bar"
      }
  )

下列程式碼與所有設定該版本的建構作業相符 使用者定義的旗標 --//custom_flags:foo=1 (明確在指令列中或間接從 .bazelrc 檔案)： 

  config_setting(
      name = "my_custom_flag_is_set",
      flag_values = { "//custom_flags:foo": "1" },
  )

下列程式碼比對鎖定採用 x86_64 架構和 glibc 平台的任何版本 2.25 版 (假設存在具有標籤的 constraint_value) //example:glibc_2_25。請注意，如果平台定義了 限制值 

  config_setting(
      name = "64bit_glibc_2_25",
      constraint_values = [
          "@platforms//cpu:x86_64",
          "//example:glibc_2_25",
      ]
  )
敬上 在這些情況下，您可以在建構中變更設定，例如， 您必須為與依附元件不同的平台建構目標。也就是說 config_setting 與頂層指令列旗標不相符，仍可能相符 和一些建構目標

附註

  • 請參閱選取，瞭解如果多個元素之間會引發多個事件， config_setting 個符合目前的設定狀態。
  • 適用於支援簡寫表單的旗標 (例如 --compilation_mode 與 -c) 和 values 定義必須使用完整格式。系統會自動列出 比對叫用內容
  • 如果標記採用多個值 (例如 --copt=-Da --copt=-Db 或清單類型) Starlark 旗標)，則 values = { "flag": "a" } 會比對 "a" 是否為 顯示在實際清單「任何位置」。

    values = { "myflag": "a,b" } 的運作方式相同：將相符 --myflag=a --myflag=b、--myflag=a --myflag=b --myflag=c、 --myflag=a,b 和 --myflag=c,b,a。確切語意 旗標舉例來說，--copt 並不支援 同一個區域中的多個值 執行個體：--copt=a,b 會產生 ["a,b"]，而 --copt=a --copt=b 產生 ["a", "b"] (因此 values = { "copt": "a,b" }) 會比對前者，但不會比對後者)。但 --ios_multi_cpus (適用於 Apple 規則) 執行：-ios_multi_cpus=a,b 和 ios_multi_cpus=a --ios_multi_cpus=b 都會產生 ["a", "b"]。檢查標記定義並測試 檢查條件是否符合您的預期

  • 如果您需要定義不是由內建建構旗標建模的條件，請使用 Starlark 定義的旗標。也可以使用 --define，但此項功能較弱 但我們不建議這麼做詳情請見 這裡瞭解詳情。
  • 避免在不同套件中重複相同的 config_setting 定義。 請改為參照標準套件中定義的一般 config_setting。
  • values、 define_values和 constraint_values 可以搭配同一個 config_setting 的任何組合使用，但至少要有一個 任何指定的 config_setting。

引數

屬性
name

名稱；必選

此目標的專屬名稱。
constraint_values

標籤清單；無法設定；預設為 []

目標平台必須指定的 constraint_values 下限 才能比對到此config_setting。(執行平台並非 以上皆是)。平台會忽略的其他限制值。詳情請見 可設定的建構屬性詳細資料。

如果兩個 config_setting 都在同一處 select，我們不會將這項屬性用於判斷 指出其中一個 config_setting 是否為另一個專業認證。在其他 每個 config_setting 比對平台的機率都不高。

define_values

字典：字串 ->String;不可設定；預設為 {}

與 values 相同，但 專門用於 --define 旗標

--define 是特殊的，因為其語法 (--define KEY=VAL) 從 Bazel 標記的角度來看，KEY=VAL 是「值」。

也就是說： 

            config_setting(
                name = "a_and_b",
                values = {
                    "define": "a=1",
                    "define": "b=2",
                })

因為同一個鍵 (define) 重複出現在 字典中。這個屬性可解決這個問題： 

            config_setting(
                name = "a_and_b",
                define_values = {
                    "a": "1",
                    "b": "2",
                })

正確比對 bazel build //foo --define a=1 --define b=2。

--define仍會顯示在以下位置： values 與一般旗標語法相同， 並可自由與這個屬性混合使用，只要字典鍵保持不同即可。

flag_values

字典：label ->String;無法設定；預設為 {}

與 values 相同，但 適用於 使用者定義的建構旗標。

這是不同的屬性，因為使用者定義的標記被當做標籤， 內建旗標做為任意字串參照

values

字典：字串 ->String;不可設定；預設為 {}

符合這項規則的一組設定值 (以建構標記表示)

這項規則會繼承已配置的目標設定 在 select 陳述式中參照這個引數情況 「比對」Bazel 叫用，前提是字典中的每個項目、 設定就會符合項目的預期值例如： values = {"compilation_mode": "opt"} 與叫用相符 「bazel build --compilation_mode=opt ...」和 bazel build -c opt ...。

為方便起見，設定值會指定為建構旗標 (不含 上述的 "--")。但請注意，兩者有所不同。這個 這是因為目標可在 建構應用程式例如，exec 設定的「cpu」與 --host_cpu，而不是 --cpu。因此兩個不同的執行個體 同一個 config_setting 可能會以不同方式比對同一個叫用 視使用規則的規則設定而定

如果指令列沒有明確設定標記，系統會使用其預設值。 如果索引鍵在字典中多次出現，則只會使用最後一個例項。 如果鍵參照的旗標，且可在指令列上多次設定 (例如 bazel build --copt=foo --copt=bar --copt=baz ...)，比對符合時 任一個設定一致。

檔案群組

查看規則來源 
filegroup(name, srcs, data, compatible_with, deprecation, distribs, features, licenses, output_group, restricted_to, tags, target_compatible_with, testonly, visibility)

使用 filegroup 為一組指定目標命名方便的名稱。 接著，您可以從其他規則參照這些規則。

建議您使用 filegroup，不要直接參照目錄。 後者非常不聲音，因為建構系統無法完整瞭解所有檔案 因此無法在這些檔案變更時重建。與 glob，filegroup 可以確保所有檔案都 讓建構系統知道的具體專案

範例

如要建立含有兩個來源檔案的 filegroup，請執行下列步驟： 

filegroup(
    name = "mygroup",
    srcs = [
        "a_file.txt",
        "some/subdirectory/another_file.txt",
    ],
)

或者，使用 glob 修復 testdata 目錄： 

filegroup(
    name = "exported_testdata",
    srcs = glob([
        "testdata/*.dat",
        "testdata/logs/**/*.log",
    ]),
)

如要使用這些定義，請參照任何規則中的標籤來參照 filegroup： 

cc_library(
    name = "my_library",
    srcs = ["foo.cc"],
    data = [
        "//my_package:exported_testdata",
        "//my_package:mygroup",
    ],
)

引數

屬性
name

名稱；必選

此目標的專屬名稱。
srcs

標籤清單；預設為 []

屬於檔案群組成員的目標清單。

常見的做法是將 glob 運算式的結果用於 srcs 屬性的值。

data

標籤清單；預設為 []

在執行階段，這項規則需要的檔案清單。

data 屬性中命名的目標會新增至 這項 filegroup 規則中的 runfiles 項。當 filegroup 的 data 屬性已參照 另一項規則的runfiles 會新增至「runfiles」 第一個輸入規則請參閱資料依附元件 和 data，進一步瞭解如何依附及使用資料檔案。

output_group

String;預設值為 ""

從來源收集構件的輸出群組。如果這個屬性 系統就會從指定依附元件的輸出群組中，匯出指定的構件 而不是預設的輸出群組

「輸出群組」是目標的輸出構件類別， 特定規則的實作

Genquery

查看規則來源 
genquery(name, deps, data, compatible_with, compressed_output, deprecation, distribs, exec_compatible_with, exec_properties, expression, features, licenses, opts, restricted_to, scope, strict, tags, target_compatible_with, testonly, visibility)

genquery() 會執行 Blaze 查詢語言並傾印結果 複製到檔案中

為保持一致建構作業，該查詢只能造訪 scope 中指定的目標遞移性封閉 屬性。如果發生下列情況，違反這項規則的查詢就無法執行 strict 未指定或為 true (如果 strict 為 false， 超出範圍的目標時，系統會略過並發出警告)。 要避免這種情況發生，最簡單的方法就是 和查詢運算式一樣

此處允許的查詢和指令的唯一差異 這一行指的是包含萬用字元目標規格的查詢 (例如 //pkg:* 或 //pkg:all) 不在此限。 造成這種情況有兩個原因：首先，因為 genquery 可指定範圍，避免發生在 影響輸出結果其次，因為 BUILD 個檔案 不支援萬用字元依附元件 (例如 deps=["//a/..."] 。

模型的輸出內容會按照字母順序排序，以強制執行確定性輸出。 但 --output=graph|minrank|maxrank 或 somepath 是用於當做頂層函式

輸出檔案名稱是規則名稱。

範例

這個範例會在 指定的是檔案的目標 

genquery(
    name = "kiwi-deps",
    expression = "deps(//kiwi:kiwi_lib)",
    scope = ["//kiwi:kiwi_lib"],
)

引數

屬性
name

名稱；必選

此目標的專屬名稱。
compressed_output

布林值；預設值為 False

如果值為 True，則查詢輸出內容會以 GZIP 檔案格式寫入。你可以使用這項設定 ，避免 Bazel 記憶體用量突然攀升，如果查詢輸出量預期會很大。Bazel 已預先壓縮到超過 220 個位元組的查詢輸出內容 此設定的值，因此設為 True 可能無法減少保留 堆積。但可讓 Bazel 在寫入輸出檔案時略過「解壓縮」。 可能會耗用大量記憶體
expression

String;必選

要執行的查詢。與指令列和 BUILD 檔案中的其他位置相比， 這裡的標籤會根據工作區的根目錄進行解析。舉例來說， a/BUILD 檔案中的屬性 :b 會參照 目標//:b。
opts

字串清單；預設值為 []

傳遞至查詢引擎的選項。這些字串與指令列相對應 以及可以傳遞至 bazel query 的選項部分查詢選項不允許使用 此處：--keep_going、--query_file、--universe_scope --order_results和--order_output。此處未指定選項 也會有預設值，就像在 bazel query 指令列中一樣。
scope

標籤清單；必選

查詢的範圍。查詢不允許在遞移性之外的觸控目標 取代這些目標。
strict

布林值；預設值為 True

如果為 true，如果目標的查詢逃避範圍的遞移範圍， 建構應用程式如果為 false，Bazel 會顯示警告，並略過導致程序外部的任何查詢路徑 同時完成其餘查詢

Genrule

查看規則來源 
genrule(name, srcs, outs, cmd, cmd_bash, cmd_bat, cmd_ps, compatible_with, deprecation, distribs, exec_compatible_with, exec_properties, executable, features, licenses, local, message, output_licenses, output_to_bindir, restricted_to, tags, target_compatible_with, testonly, toolchains, tools, visibility)

genrule 會透過使用者定義的 Bash 指令產生一或多個檔案。

Genrules 是一般建構規則，可在工作沒有特定規則時使用。 舉例來說，您可以執行 Bash 單行程式碼。如果您需要編譯 C++ 檔案，請 至現有 cc_* 規則，因為所有繁重工作已完成 不必確保憑證管理是否適當 因為 Google Cloud 會為您管理安全性

請注意，genrule 需要殼層來解讀指令引數， 輕鬆參照 PATH 上的任意程式，但這使 指令無意義，可能無法重現 如果只需要執行單一工具，建議使用 run_binary 。

請勿使用 genrule 執行測試。測試和檢測作業有特殊分配方式 當中包含快取政策和環境變數測試通常需要執行 並在建構完成後並在目標架構上執行 Genrules 和 exec 架構 (可能不同)如果您需要一般用途 測試規則，請使用 sh_test。

跨平台程式碼編譯注意事項

請參閱使用手冊，進一步瞭解相關資訊 跨平台程式碼編譯

雖然 Genrules 在建構期間執行，其輸出內容通常是在建構後用於部署、部署 進行測試。以針對微控制器編譯 C 程式碼的範例：編譯器接受 C 並產生在微控制器上執行的程式碼。產生的是顯而易見的程式碼 無法在建構該檔案的 CPU 上執行，但 C 編譯器 (如果是從原始碼編譯而來) 這項功能

建構系統會使用 exec 設定，描述執行建構作業的機器 和目標設定，用於說明建構作業的輸出內容 。這項服務提供設定上述各項選項的選項 請將對應的檔案嵌入個別目錄以避免衝突

針對 Genrules，建構系統會確保正確建構依附元件： 系統會針對 target 設定建構 srcs (如有必要)。 系統會針對 exec 設定建構 tools，並將輸出內容視為 適用於 target 設定它也提供 「廠牌」變數。

Genrule 刻意並未定義 deps 屬性：其他內建規則使用 在規則之間傳遞的語言相關中繼資訊，以自動判斷 會處理相依規則，但 Genrules 無法採用這種自動化程度。Genrules 工作 只需要在檔案和執行檔案層級進行這項作業

特殊情況

Exec-exec 編譯：在某些情況下，建構系統需要執行 Genrule，讓 輸出內容也可以在建構期間執行舉例來說，如果 Genrule 會建構自訂編譯器 之後另一個 Genrule 會使用這個金鑰 exec 設定，因為這就是編譯器在其他 Genrule 中的位置在本例中 建構系統會自動執行正確的操作：建構 srcs 第 1 個 Genrule 中的 outs，而不是目標 此外還會從 0 自動調整資源配置 您完全不必調整資源調度設定詳情請參閱使用手冊 資訊

JDK 與C++ 工具：如要使用 JDK 或 C++ 編譯器套件 (建構系統) 中的工具 會提供一組變數。請參閱「廠牌」變數： 詳細資料。

Genrule 環境

genrule 指令是由設定失敗的 Bash 殼層執行 或使用 set -e -o pipefail 來處理管道失敗

建構工具會在經過清理的程序環境中執行 Bash 指令 只會定義 PATH、PWD、 TMPDIR 和另外一些服務。 為了確保建構作業可重現，大多數在使用者殼層中定義的變數 環境不會傳遞至 genrule 的指令不過，Bazel (但非 Blaze) 會傳遞使用者 PATH 環境變數的值。 任何變更 PATH 的值都會導致 Bazel 重新執行指令 下個建構作業的執行進度

除非連線至以下程序，否則 Genrule 指令不會存取網路 子項，但系統目前不會強制執行這項指令。

建構系統會自動刪除現有的任何輸出檔案，但建立任何必要的父項 執行 genrule 等並在作業失敗時移除所有輸出檔案。

一般建議

  • 要確保 Genrule 執行的工具具有確定性與隱密性，不應寫入 輸出內容的時間戳記，應對組合和對應採用穩定排序， 只寫入輸出的相對檔案路徑，無絕對路徑。未遵循這項規則，將會 導致非預期的建構行為 (Bazel 不會重新建構您認為會預期的 Genrule) 也會降低快取效能
  • 針對輸出內容、工具和來源，廣泛使用 $(location)。由於 針對不同設定區隔輸出檔案，genrules 不能依賴硬式編碼 和/或絕對路徑
  • 請編寫一個通用的 Starlark 巨集，以在 。如果 Genrule 是很複雜的，請考慮在指令碼或 星際大戰規則。這有助於改善可讀性和可測試性。
  • 確認結束程式碼可正確指出 Genrule 成功或失敗。
  • 請勿將資訊訊息寫入 stdout 或 stderr。雖然對偵錯很有幫助 變得雜訊；成功的 Genrule 應為靜止狀態另一方面，失敗的 Genrule 應該發出良好的錯誤訊息
  • $$ evaluates to a $, a literal dollar-sign, so in order to invoke a shell command containing dollar-signs such as ls $(dirname $x), one must escape it thus: ls $$(dirname $$x)。
  • 避免建立符號連結和目錄。Bazel 不會複製目錄/符號連結 但不包含 genrules 及其目錄的依附元件檢查作業。
  • 在其他規則中參照 genrule 時，可以使用 Genrule 標籤或 個別輸出檔案的標籤有時候其中一種方法易讀易懂，有時候就是 other：在使用規則的 srcs 中依名稱參照輸出可避免 無意中接收到 Genrule 的其他輸出內容 會產生許多輸出內容

範例

這個範例會產生 foo.h。沒有來源，因為指令並未 任何輸入內容「二進位」是由此指令執行，是與 genrule 相同的套件中的 perl 指令碼。 

genrule(
    name = "foo",
    srcs = [],
    outs = ["foo.h"],
    cmd = "./$(location create_foo.pl) > \"$@\"",
    tools = ["create_foo.pl"],
)

以下範例說明如何使用 filegroup ，以及另一個 genrule 的輸出內容。請注意，請改用 $(SRCS) 明確的 $(location) 指令也能使用本範例使用後者 目的只是在示範 

genrule(
    name = "concat_all_files",
    srcs = [
        "//some:files",  # a filegroup with multiple files in it ==> $(locations)
        "//other:gen",   # a genrule with a single output ==> $(location)
    ],
    outs = ["concatenated.txt"],
    cmd = "cat $(locations //some:files) $(location //other:gen) > $@",
)

引數

屬性
name

名稱；必選

此目標的專屬名稱。


你可以在 其他 BUILD 的 srcs 或 deps 部分 不過，編寫這類演算法並不容易 因為我們無法寫出所有可能的規則如果規則會產生來源檔案，您應該使用 srcs 屬性。
srcs

標籤清單；預設為 []

列出這項規則的輸入內容，例如要處理的來源檔案。

此屬性不適合列出 cmd 執行的工具。使用 的 tools 屬性。

建構系統會確保在執行 genrule 之前先建構這些必要條件 指令；這類模型使用與原始建構要求相同的設定。 指令可使用這些必要條件的檔案名稱 以空格分隔的清單，格式為 $(SRCS)；替代方法是 srcs 目標 //x:y 可以使用 $(location //x:y) 或 $< (前提是其是以下項目的唯一項目) srcs。

outs

檔案名稱清單；無法設定；必選

由這項規則產生的檔案清單。

輸出檔案不得跨越套件邊界。 系統會將輸出檔案名稱解讀為相對於套件。

如果已設定 executable 標記，則 outs 必須僅包含一個 標籤。

genrule 指令預期會在預先定義的位置建立每個輸出檔案。 可在 cmd 中使用 genrule 專屬「Make」指令 變數 ($@、$(OUTS)、$(@D) 或 $(RULEDIR))，或使用 $(location) 替代。

cmd

String;預設值為 ""

要執行的指令。 須遵守 $(location) 和「廠牌」設定變數替代。
  1. 套用第一個 $(location) 替換，取代所有出現的 $(location label) 和 $(locations label) (及類似內容) 使用相關變數 execpath、execpaths、 rootpath 和 rootpaths)。
  2. 下一個是「廠牌」變數。請注意， 預先定義的變數 $(JAVA)、$(JAVAC) 和 $(JAVABASE) 會在 exec 設定下方展開，因此 Java 叫用 在建構步驟中執行的 Pod 可以正確載入共用程式庫和其他 依附元件
  3. 最後，使用 Bash 殼層執行產生的指令。如果結束代碼為 非零錯誤，則系統會將該指令視為失敗。
，瞭解如何調查及移除這項存取權。 這是 cmd_bash、cmd_ps 和 cmd_bat 的備用方案。 (如果所有元素都不適用)。

如果指令列的長度超出平台限制 (在 Linux/macOS 為 64K，在 Windows 上為 8K)， 那麼 Genrule 會將指令寫入指令碼，並執行該指令碼來解決問題這個 適用於所有 cmd 屬性 (cmd、cmd_bash、cmd_ps、 cmd_bat)。

cmd_bash

String;預設值為 ""

要執行的 Bash 指令。

這個屬性的優先順序高於 cmd。這項指令會展開 執行方式與 cmd 屬性相同。

cmd_bat

String;預設值為 ""

要在 Windows 上執行的 Batch 指令。

此屬性的優先順序高於 cmd 和 cmd_bash。 這個指令的執行方式與 cmd 屬性類似， 下列差異：

  • 這項屬性僅適用於 Windows。
  • 這個指令會以下列預設引數使用 cmd.exe /c 執行：
    • /S - 去除第一個和最後一個引號，然後依原樣執行所有其他項目。
    • /E:ON - 啟用擴充指令集。
    • /V:ON - 啟用延遲變數展開功能
    • /D - 忽略 AutoRun 登錄檔項目。
  • 在 $(location) 之後 「廠牌」替代變數，路徑就會是 擴展至 Windows 樣式路徑 (含反斜線)。
cmd_ps

String;預設值為 ""

要在 Windows 上執行的 Powershell 指令。

此屬性的優先順序高於 cmd、cmd_bash 和 cmd_bat。這個指令的執行方式與 cmd 類似 屬性，不過須注意以下差異：

  • 這項屬性僅適用於 Windows。
  • 這個指令會以 powershell.exe /c 執行。

為了讓 Powershell 易於使用，並減少出錯的可能性，我們執行了以下程式碼 指令來設定環境，然後在 genrule 中執行 Powershell 指令。

  • Set-ExecutionPolicy -Scope CurrentUser RemoteSigned - 允許執行 未經簽署的指令碼。
  • $errorActionPreference='Stop'：如果有多個指令 以 ; 分隔，如果 Powershell CmdLet 失敗，動作會立即結束。 但這種做法「無法」用於外部指令。
  • $PSDefaultParameterValues['*:Encoding'] = 'utf8'：變更預設設定 從 utf-16 到 utf-8 進行編碼
executable

布林值；不可設定；預設為 False

宣告輸出內容為可執行檔。

將此標記設為 True 表示輸出是可執行的檔案，且可以使用 run 指令。在這種情況下，genrule 只能產生一項輸出內容。 如果設定這項屬性，run 會嘗試執行檔案，不論 內容

不支援為產生的執行檔宣告資料依附元件。
local

布林值；預設值為 False

如果設為 True，這個選項會強制這個 genrule 使用「local」指令執行 策略，也就是無需遠端執行、無需採用沙箱機制，也不需要永久的工作站。

這等同於提供「local」做為標記 (tags=["local"])。

message

String;預設值為 ""

進度訊息。

在執行這個建構步驟時，系統會顯示的進度訊息。根據預設， 訊息為「產生 output」有時您也會提供 也就是更具體的請使用這個屬性，不要使用 echo 或其他沖印相片 cmd 指令中的陳述式，因為此方法可讓建構工具控制 以及指示是否列印這類進度訊息

output_licenses

授權類型；預設值為 ["none"]

查看「common attributes 」
output_to_bindir

布林值；不可設定；預設為 False

如果設為 True，這個選項會讓輸出檔案寫入 bin 而非 genfiles 目錄。

tools

標籤清單；預設為 []

這項規則的工具依附元件清單。請參閱 依附元件。

建構系統會確保在執行 genrule 指令之前先建構這些必要條件。 是使用 exec 設定，因為這些工具會在建構作業中執行。節點上的 個別 tools 目標 //x:y 可透過以下方法取得 $(location //x:y)。

凡是由 cmd 執行的 *_binary 或工具，都必須顯示在此 清單，而非 srcs 中，以確保在正確的設定中進行建構。

starlark_doc_extract

查看規則來源 
starlark_doc_extract(name, deps, src, data, compatible_with, deprecation, distribs, exec_compatible_with, exec_properties, features, licenses, render_main_repo_name, restricted_to, symbol_names, tags, target_compatible_with, testonly, visibility)

starlark_doc_extract() 會擷取規則、函式 (包括 巨集)、規格和提供者，在特定 .bzl 或 .scl 檔案。這項規則的輸出內容是 ModuleInfo 二進位 proto，符合定義的 英吋 stardoc_output.proto 在 Bazel 來源樹狀結構中。

隱含輸出目標

  • name.binaryproto (預設輸出)：A ModuleInfo 二進位檔 proto。
  • name.textproto (僅在明確要求時建構)：文字 name.binaryproto 的 proto 版本。

警告：這項規則的輸出格式不保證是固定的。主要用於以下用途： Stardoc 內部使用。

引數

屬性
name

名稱；必選

此目標的專屬名稱。
deps

標籤清單；預設為 []

納入以 load() 為基礎的 Starlark 檔案的目標清單 src。這些目標應在正常使用之下 bzl_library敬上 但 starlark_doc_extract 規則不會強制執行此政策 在 DefaultInfo 中提供 Starlark 檔案的任何目標。

請注意，包裝的 Starlark 檔案必須是來源樹狀結構中的檔案。Bazel 無法 load() 產生的檔案。

src

標籤；必選

要擷取文件的 Starlark 檔案。

請注意，這必須是原始碼樹狀結構中的檔案。Bazel 無法 load() 產生的檔案。

render_main_repo_name

布林值；預設值為 False

如為 true，則使用存放區元件在產生的說明文件中算繪主要存放區的標籤 (換句話說，//foo:bar.bzl 會以下列形式發出： @main_repo_name//foo:bar.bzl)。

主要存放區要使用的名稱是從 module(name = ...) 取得 位於主要存放區的 MODULE.bazel 檔案 (如果已啟用 Bzlmod)，或是 主要存放區 WORKSPACE 檔案中的 workspace(name = ...)。

產生以下項目的說明文件時，應將這項屬性設為 False 僅能在相同存放區中使用 Starlark 檔案，以及 產生 Starlark 檔案說明文件時，請True 從其他存放區使用 BigQuery

symbol_names

字串清單；預設值為 []

選用清單，列出匯出函式、規則、提供者或切面 (或 巢狀結構的結構體)，以便擷取說明文件。這裡有個合格 name 是模組使用者可使用實體的名稱。 包括實體採巢狀結構做為命名空間的任何結構體。

只有在符合下列條件時，starlark_doc_extract 才會發出實體的說明文件

  1. 每個實體合格名稱的組成部分都是公開的 (也就是 合格名稱中每個元件的字元是字母而非 "_")； 和
    1. symbol_names 清單都沒有內容 (這是預設值) 案件)，或
    2. 實體的合格名稱，或是實體中結構體的合格名稱 巢狀結構位於 symbol_names 清單中。

test_suite

查看規則來源 
test_suite(name, compatible_with, deprecation, distribs, features, licenses, restricted_to, tags, target_compatible_with, testonly, tests, visibility)

test_suite 用於定義一組「實用」的測試人類可以使用。這個 可讓您為專案定義一組測試，例如「您必須在入住前執行的測試」、「我們的 的壓力測試」或「所有小型測試」blaze test 指令會遵循這個順序 機構：對於像 blaze test //some/test:suite 這類叫用，Blaze 會先 列舉 //some/test:suite 目標間接納入的所有測試目標 (我們 將其命名為「test_suite 輔助」，Blaze 會建構並測試這些目標。

範例

測試套件，用於執行目前套件中的所有小型測試。

test_suite(
    name = "small_tests",
    tags = ["small"],
)

執行一組特定測試的測試套件：

test_suite(
    name = "smoke_tests",
    tests = [
        "system_unittest",
        "public_api_unittest",
    ],
)

測試套件，用於執行目前套件中所有不會發生問題的測試。

test_suite(
    name = "non_flaky_test",
    tags = ["-flaky"],
)

引數

屬性
name

名稱；必選

此目標的專屬名稱。
tags

字串清單；不可設定；預設為 []

文字標記清單 (例如「small」)或「資料庫」或「-flaky」。標記可以是任何有效字串。

開頭為「-」的標記字元都會視為排除標記。 前面的「-」字元不屬於代碼的一部分，因此套件代碼 的「-小」符合測試的「小」大小所有其他代碼都會納入考量 正確標記。

(選用) 如要讓正面標記更加明確，也可在開頭加上 「+」字元，系統不會將其視為代碼文字的一部分進行評估。這項服務 只是讓正面和負面區別更容易閱讀

只測試符合「所有」正數標記，且「無」負面標記的測試規則 將納入測試套件。請注意，這不代表錯誤檢查 並略過已篩除測試的依附元件。略過的依附元件 測試仍必須合法 (例如不受瀏覽權限限制封鎖)。

manual 標記關鍵字的處理方式與上述 「test_suite 擴展」blaze test 指令對叫用執行 涉及萬用字元 目標模式。 發現有 test_suite 個目標標記為「手動」不會被篩除 已展開)。此行為與 blaze build 和 blaze test 通常會處理萬用字元的目標模式。請注意，此 明顯與 blaze query 'tests(E)' 的行為不同，因為套件 一律會依照 tests 查詢函式展開 manual 標記。

請注意，系統會將測試的 size 視為篩選用的標記。

如果您需要 test_suite，且其中包含具有互斥標記的測試 (例如所有小型和中型測試)，您必須建立三項 test_suite 規則：一項適用於所有小型測試、一項用於所有媒介測試，以及包含 前兩部

tests

標籤清單；無法設定；預設為 []

測試套件清單和任何語言的測試目標。

此處接受任何 *_test (無論語言為何)。否 不過，即使有執行測試，也會接受 *_binary 目標。 只有在測試中直接列出的測試時，系統才會按照指定的 tags 進行篩選 此屬性。如果這個屬性包含 test_suite，則其中的測試 這些事件不會以此test_suite篩除 (系統認為這些事件 已經過篩選)。

如果 tests 屬性未指定或空白，規則將預設為 包含目前 BUILD 檔案內所有未加上標記的測試規則 manual。這些規則仍受 tag 篩選影響。