常見定義

本節定義多個常見詞彙和概念 許多函式或建構規則

目錄

• Bourne 殼層權杖化
• 標籤擴展
• 多數建構規則定義的一般屬性
• 所有建構規則通用的屬性
• 所有測試規則 (*_test) 通用的屬性
• 所有二進位規則通用的屬性 (*_binary)
• 可設定的屬性
• 隱含輸出目標

Bourne 殼層權杖化

某些規則的特定字串屬性會分成多個 Bourne 殼層的權杖化規則來修正字詞： 無引號的空格分隔每個字詞、以及單字和 雙引號字元和反斜線 符記化

需符合此符記化條件的屬性如下： 在本文件中的定義加以明確表示。

屬於「廠牌」的屬性變數擴展和 Bourne 殼層 符記化通常用於將任意選項 編譯器和其他工具這類屬性的例子包括 《cc_library.copts》和《java_library.javacopts》。 這些替代字元 單一字串變數，展開為特定設定的專屬清單 代表字詞

標籤擴展

只有極少數規則的部分字串屬性會加上標籤 擴充：如果這些字串包含 子字串，例如 //mypkg:target，而該標籤是 就會擴展為 檔案路徑名稱 目標 //mypkg:target。

屬性範例包括 genrule.cmd 和 cc_binary.linkopts。您在 以及個別問題，例如：相對標籤 已展開；標籤如何展開到多個檔案 請參閱規則屬性說明文件 具體細節

多數建構規則定義的一般屬性

本節說明許多建構規則定義的屬性。 但並非全部

屬性	說明
data	List of labels ; optional 這項規則在執行階段所需的檔案。可列出檔案或規則目標。通用 允許任何目標。 預設會輸出和執行 data 屬性中的目標檔案 應該會出現在*.runfiles 或對這個目標具有執行階段依附元件這可能包含數據傳輸 設定檔或二進位檔 系統會執行 srcs。詳情請參閱 資料依附元件 一節，進一步瞭解如何依附及使用資料檔案。 如果新規則會處理，則應定義 data 屬性 這些輸入內容可能會在執行階段使用其他輸入內容規則實作函式 也必須填入目標的 從輸出和執行檔案的任何 data 屬性中， 以及從提供下列任一依附元件的依附元件屬性中 執行檔案 原始碼或執行階段依附元件
deps	List of labels ; optional 此目標的依附元件。一般來說，只會列出規則目標。(咳嗽 某些規則允許檔案直接列在 deps 中， 都應避免使用)。 特定語言的規則通常只會列出具有 特定供應商提供的資訊 定義目標對其他依附項目 deps 是特定規則種類和規則專屬的規則 則會詳細說明對於處理原始碼的規則 deps 一般會指定程式碼中使用的程式碼依附元件 srcs。 大多數情況下，deps 依附元件會用來允許一個模組使用 另一個以相同程式設計語言編寫而成的符號 單獨編譯。許多語言依附元件的依附元件 情況：例如，java_library 目標可能會依附於 C++ 程式碼 在 cc_library 目標中，您只要列出 deps 屬性。請參閱 依附元件 瞭解詳情
licenses	List of strings; optional; nonconfigurable 這個特定目標要使用的授權類型字串清單。 這是 Bazel 不再使用的授權 API 的一部分。錯誤做法 即可。
srcs	List of labels ; optional 套用這項規則或納入這項規則的檔案。通常會直接列出檔案，但 可能會列出規則目標 (例如 filegroup 或 genrule) 包括其預設輸出內容 特定語言專用的規則通常需要列出的檔案要有特定的 副檔名。

所有建構規則通用的屬性

本節說明自動新增至所有建構作業的屬性 不過，編寫這類演算法並不容易 因為我們無法寫出所有可能的規則

屬性	說明
compatible_with	List of labels ; optional; nonconfigurable 除了設定這個目標外，也可以建立這個目標的環境清單 支援預設環境 這是 Bazel 限制系統的一部分，可讓使用者宣告 彼此間的關係，彼此互不相通。例如可從外部部署 二進位檔不應仰賴含有公司秘密程式碼的程式庫。詳情請見 ConstraintSemantics。
deprecation	String; optional; nonconfigurable 與這個目標相關的說明警告訊息。 通常用於通知使用者目標已過時 或受到其他規則取代、為套件專用，或 但可能因為某些原因而被視為有害建議你附上 一些參考資料 (例如網頁、錯誤編號或遷移 CL 範例)，因此 也很容易知道必須進行哪些變更，才能避免這個訊息。 如果有一個新目標可做為替換品使用， 建議您只遷移舊目標的所有使用者。 這個屬性對建構方式沒有影響，但 可能會影響建構工具的診斷輸出。建構工具會發出 如果規則包含 deprecation 屬性，則為警告 相依於另一個套件中的目標 就此警告而言，內部套件依附元件不受此警告的規範， 舉例來說，為已淘汰的規則建立測試時， 那麼網站會收到警告 如果已淘汰的目標依附於其他已淘汰的目標，則系統不會發出警告 發出的訊息。 一旦使用者停止使用，即可移除目標。
distribs	List of strings; optional; nonconfigurable 這個特定目標要使用的發布方法字串清單。 這是 Bazel 不再使用的授權 API 的一部分。錯誤做法 即可。
exec_compatible_with	List of labels ; optional; nonconfigurable 一系列 constraint_values 必須存在於這個目標的執行平台中。這位於 再加上規則類型已設定的任何限制條件。使用限制 以限制可用執行平台的清單詳情請參閱 模型的說明 工具鍊解決方案。
exec_properties	Dictionary of strings; optional 字串字典，會新增至為這個目標選擇的平台的 exec_properties。請參閱平台規則的 exec_properties。 如果平台和目標層級資源中同時出現某個鍵，系統會從目標擷取該值。
features	List of feature strings; optional 功能是字串標記，可為目標啟用或停用。 功能的意義取決於規則本身。 這個 features 屬性會與 套件層級 features 屬性。舉例來說 套件層級已啟用功能 [「a」、「b」，且目標的 features 屬性包含 ["-a", "c"]，表示為 規則會是「b」和「c」鍵。 查看範例。
restricted_to	List of labels ; optional; nonconfigurable 這個目標可以建構的環境清單，而不是 支援預設環境 這屬於 Bazel 限制系統的一部分。詳情請見 compatible_with 。
tags	List of strings; optional; nonconfigurable 代碼可用於任何規則。測試和測試中的代碼 test_suite 規則適合用來將測試分類。 非測試目標上的代碼可用來控制是否採用沙箱機制， genrule 和 Starlark 以及由人類和/或外部工具剖析資料。 Bazel 發現以下項目時，會修改沙箱程式碼的行為 任何測試或 genrule 的 tags 屬性中的關鍵字 或 execution_requirements 任何 Starlark 的鍵 動作。 no-sandbox 個關鍵字帶來的操作或測試從未出現 採用沙箱機制但還是可以快取或從遠端執行：請使用 no-cache 或 no-remote，防止兩者發生。 no-cache 個關鍵字帶來的操作或測試從未出現 快取 (遠端或本機) no-remote-cache 個關鍵字帶來的操作或測試從未出現 遠端快取 (但可能會在本機快取；也可以從遠端執行)。 注意：為了方便使用這個標記，磁碟快取會視為本機快取， 系統會將 http 和 gRPC 快取視為遠端程序。 如果指定合併快取 (例如含有本機和遠端元件的快取)， 系統會將其視為遠端快取，並完全停用，除非 --incompatible_remote_results_ignore_disk 如果已設定，則會使用本機元件。 no-remote-exec 個關鍵字帶來的操作或測試從未出現 遠端執行 (但可能會從遠端快取)。 no-remote 關鍵字阻止遠端執行動作或測試，或 遠端快取。等同於同時使用 《no-remote-cache》和《no-remote-exec》。 no-remote-cache-upload 關鍵字會停止上傳部分遠端快取的上傳功能。 也不會停用遠端執行 local 關鍵字會排除動作或測試遠端快取。 遠端執行或在沙箱內執行 如果是 Genrules 和測試，請使用 local = True 標記規則 屬性的效果相同。 requires-network 關鍵字允許存取 存取沙箱中的網路只有在採用沙箱機制時，這個標記才會生效 block-network 個關鍵字封鎖外部存取權 存取沙箱中的網路本例中 才能使用 localhost。只有在沙箱功能為 requires-fakeroot 會以 uid 和 gid 0 (亦即根層級) 執行測試或動作 使用者)。這項功能僅適用於 Linux。這個標記的優先順序高於 --sandbox_fake_username 指令列選項。 測試上的標記通常用於為 偵錯和發布流程標記對於 C++ 和 Python 通常最為實用 測試，缺少任何執行階段註解功能。使用代碼和大小 元素提供根據程式碼集來組合測試套件的靈活性 入住政策。 Bazel 會修改測試執行行為，前提是該測試在 測試規則的 tags 屬性： exclusive 會強制測試在以下位置執行： 「專屬」模式，確保在相同位置沒有其他測試 這類測試將在所有版本完成後依序執行 活動和非專屬測試都已完成。遠端執行為 因為 Bazel 無法控制執行中的 也就是遠端機器中運作的虛擬機器 exclusive-if-local 會強制測試在以下位置執行： 「專屬」模式，如果是本機執行，則會平行執行測試 遠端執行。 manual關鍵字會排除目標，不擴大目標模式萬用字元的擴充範圍 (...、:*、:all 等) 和 test_suite 規則 在計算要建構/執行的頂層目標組合時，系統不會明確列出測試 編寫 build、test 和 coverage 指令沒有 在其他情況下會影響目標萬用字元或測試套件擴充，包括 query 指令。請注意，manual 不表示目標 不會由持續建構/測試系統自動建構/執行。舉例來說， 理想情況下，應將指定目標從bazel test ...中排除，因為指定目標需要具體 Bazel 標記，但仍會納入正確設定的預先提交或持續測試中 或任何可執行 Knative 的環境中 external 關鍵字將強制測試無條件的測試 已執行 (不論 --cache_test_results 為何) 值)。 ，瞭解如何調查及移除這項存取權。 詳情請見 代碼慣例 ，瞭解測試目標附加標記的慣例。
target_compatible_with	List of labels ; optional 一系列 constraint_value 秒 必須存在於目標平台中，系統才會將這個目標視為 「相容」。除了 規則類型如果目標平台不符合所有列出的限制， 系統就會視為不相容的目標。不相容的目標如下： 當目標模式展開時，系統會略過建構及測試作業 (例如 //...、:all)。如果在 指令列不相容的目標，導致 Bazel 輸出錯誤並造成 建構或測試失敗 間接依賴不相容的目標本身 視為不相容建構和測試時，也會略過這些 KPI。 如果空白清單 (預設) 代表目標相容 與所有平台互動 Workspace 規則以外的所有規則都支援這項設定 屬性。 對某些規則而言，這個屬性不會有任何作用。例如指定 target_compatible_with 代表 cc_toolchain 不實用。 詳情請參閱 平台 頁面，進一步瞭解不相容的目標略過。
testonly	Boolean; optional; default False except for test and test suite targets; nonconfigurable 如果設為 True，則只有測試專用的目標 (例如測試) 能仰賴這個目標。 等同於不允許 testonly 的規則 取決於 testonly 的所有規則。 測試 (*_test 項規則) 和測試套件 (test_suite 規則) 預設為 testonly。 這個屬性是用來表示目標不得 包含在發布正式版的二進位檔中。 因為測試只會在建構期間強制執行，而非執行時間，並傳播 穿過依附性樹狀結構，應該謹慎地應用。適用對象 例如虛設常式和虛構資料 您對於進行整合測試也相當實用 包含即將發布到正式版的相同二進位檔 因此不應標示為「test only」相反地 即使沒有條件也沒關係 覆寫正常行為，應確實標示為 testonly。
toolchains	List of labels ; optional; nonconfigurable 這個目標的「建立變數」的一組目標 。這些目標就是由系統提供 TemplateVariableInfo 或 Bazel 內建工具鍊類型的特殊目標。這些 包括： @bazel_tools//tools/cpp:current_cc_toolchain @bazel_tools//tools/jdk:current_java_runtime 請注意，這與 工具鍊解決方案 處理各平台設定的規則。您無法使用這個項目 屬性決定是哪些特定 cc_toolchain 或 java_toolchain 目標模型會使用
visibility	List of labels ; optional; default default_visibility from package if specified, or //visibility:private otherwise; nonconfigurable 目標的 visibility 屬性可控制該目標 可用於其他套件詳情請參閱 瀏覽權限

所有測試規則 (*_test) 通用的屬性

本節說明所有測試規則的常見屬性。

屬性	說明
args	List of strings; optional; subject to $(location) and "Make variable" substitution, and Bourne shell tokenization Bazel 會在發生什麼情況時，將指令列引數傳遞至目標 以 bazel test 執行。 這些引數會在任何 --test_arg 值之前傳遞 您在 bazel test 指令列中指定的資訊。
env	Dictionary of strings; optional; values are subject to $(location) and "Make variable" substitution 指定執行測試時要設定的其他環境變數 bazel test。 這項屬性僅適用於原生規則，例如 cc_test。 py_test和sh_test。不適用於 Starlark 定義的測試規則。針對自己的 Starlark 規則，您可以新增「env」 屬性並用於填入 TestEnvironment 提供者。
env_inherit	List of strings; optional 指定要繼承自 外部環境 (當 bazel test 執行測試時)。 這項屬性僅適用於原生規則，例如 cc_test、py_test。 和 sh_test。不適用於 Starlark 定義的測試規則。
size	String "enormous", "large" "medium" or "small", default is "medium"; optional; nonconfigurable 指定測試目標的「重度」：執行測試需要花費的時間/資源。 單元測試分為「小」，整合測試為「中」，端對端測試則為「大型」或 「巨大」Bazel 會使用這個大小決定預設逾時，您可以使用 timeout 屬性。逾時設定適用於 BUILD 目標中的所有測試，而非每個測試 個別測試。在本機執行測試時，size 會額外用於 排程目的：Bazel 會嘗試遵循 --local_{ram,cpu}_resources，而不是 同時執行大量繁重測試，將本機機器的負載過重。 測試大小對應至下列預設的逾時時間，並假設本機資源是高峰值 用法： 大小 RAM (MB) CPU (CPU 核心數) 預設逾時 small 20 1 短 (1 分鐘) 媒介 100 1 中度 (5 分鐘) large 300 1 長 (15 分鐘) 巨大 800 1 永恆 (60 分鐘) 環境變數 TEST_SIZE 會設為 這個值。
timeout	String "short", "moderate", "long", "eternal" (with the default derived from the test's size attribute); nonconfigurable 測試在傳回前的預期執行時間。 測試的大小屬性會影響資源估算， 逾時。如果沒有明確指定 逾時取決於測試大小。測試 逾時可使用 --test_timeout 旗標覆寫，例如的 在某些已知速度緩慢的情況下運作。測試逾時值 對應下列時間範圍： 逾時值 時間範圍 short 1 分鐘 中度 5 分鐘 long 15 分鐘 Eternal 60 分鐘 如果不是上述時間，可使用 --test_timeout bazel 旗標，例如手動執行 但已知會執行速度緩慢的情況--test_timeout 值 都能在幾秒內完成例如 --test_timeout=120 會設定測試 並將逾時設為兩分鐘 產生測試時，環境變數 TEST_TIMEOUT 會設為測試逾時 (以秒為單位)。
flaky	Boolean; optional; default False; nonconfigurable 將測試標示為「容易」。 如果已設定，最多會執行測試三次，只有在測試失敗時才標示為失敗 失敗。此屬性預設為 False，而測試為 執行一次請注意，一般不建議使用這項屬性。 但測試應該穩定通過其斷言。
shard_count	Non-negative integer less than or equal to 50; optional 指定平行資料分割數量 以便執行測試 這個值會覆寫任何用來判定 以及執行測試的平行資料分割。請注意，在部分測試中 可能需要用到這個參數，才能啟用資料分割功能 一開始就做出決定另請參閱 --test_sharding_strategy。 如果測試資料分割已啟用，系統會在產生測試時將環境變數 TEST_TOTAL_SHARDS 設為這個值。 資料分割需要測試執行器來支援測試資料分割通訊協定。 如果不是的話，則很可能會在每個資料分割中執行所有測試； 並非您想要的 詳情請見 測試資料分割 。
local	Boolean; default False; nonconfigurable 強制測試在本機執行，且不採用沙箱機制。 設為 True 等同於提供「local」代碼 (tags=["local"])。

所有二進位規則通用的屬性 (*_binary)

本節說明所有二進位規則通用的屬性。

屬性	說明
args	List of strings; optional; subject to $(location) and "Make variable" substitution, and Bourne shell tokenization; nonconfigurable Bazel 會在執行時傳遞至目標的指令列引數 透過 run 指令或測試。這些引數 呼叫 bazel run 中的指定 ID 之前或 bazel test 指令列。 注意：執行目標時不會傳遞引數 在 Bazel 之外 (例如，手動在 bazel-bin/)。
env	Dictionary of strings; optional; values are subject to $(location) and "Make variable" substitution 指定要在目標： 由 bazel run 執行。 這項屬性僅適用於原生規則，例如 cc_binary、py_binary。 和 sh_binary。不適用於 Starlark 定義的執行規則。 注意：執行目標時不會設定環境變數 在 Bazel 之外 (例如，手動在 bazel-bin/)。
output_licenses	List of strings; optional 這個二進位檔產生的輸出檔案授權。 這是 Bazel 不再使用的授權 API 的一部分。錯誤做法 即可。

可設定的屬性

大多數的屬性都處於「可設定」的狀態，也就是說，當這些屬性在 而目標則是以不同方式建構而成具體來說，可設定的屬性 可能會因傳送至 Bazel 指令列的標記而異 下游依附元件正在要求目標。這可用於 例如自訂多個平台或編譯模式的目標。

以下範例針對不同的目標宣告不同來源 架構執行時間：bazel build :multiplatform_lib --cpu x86 建構目標時，會使用 x86_impl.cc 建構目標 --cpu arm 會改為使用 arm_impl.cc。

cc_library(
    name = "multiplatform_lib",
    srcs = select({
        ":x86_mode": ["x86_impl.cc"],
        ":arm_mode": ["arm_impl.cc"]
    })
)
config_setting(
    name = "x86_mode",
    values = { "cpu": "x86" }
)
config_setting(
    name = "arm_mode",
    values = { "cpu": "arm" }
)

select() 函式 針對可設定屬性選擇不同的替代值 config_setting 或 constraint_value 符合目標的設定條件

Bazel 會在處理巨集的當下和之前，評估可設定的屬性 就技術層面而言， 載入和分析階段))。 系統評估「select()」前進行的任何處理，不知道 select() 選擇的分支版本。例如，巨集將 指定分支版本的行為，bazel query 則可 僅在目標的可設定依附元件方面做出保守的猜測。詳情請見 這篇常見問題文章 ，進一步瞭解如何搭配使用 select() 與規則和巨集。

在說明文件中標示為 nonconfigurable 的屬性不得 使用這項功能由於 Bazel 無法設定屬性 內部必須先瞭解該值，才能決定如何解決 select()。

詳情請參閱 可設定的建構屬性取得詳細總覽。

隱含輸出目標

C++ 中的隱式輸出內容已淘汰，請避免使用 。我們目前還沒有淘汰的途徑 但最終會被淘汰。

在 BUILD 檔案中定義建構規則時，您會明確地 在套件中宣告新的已命名規則目標。許多建構規則 函式也會「間接」包含一或多個輸出檔案 其內容和意義是專屬於特定規則。 例如，當您明確宣告 java_binary(name='foo', ...) 規則，您也是 「隱含」宣告輸出檔案 指定 foo_deploy.jar 做為同一套件的成員。 (這個特定目標為獨立的 Java 封存檔， 以便進行部署作業)。

隱式輸出目標是全球一流成員 目標圖表如同其他目標，隨選是依需求而建構 當您設定在頂層建構指令中指定時，或 是其他建構目標的必要先決條件。可以 會在 BUILD 檔案中參照為依附元件，並可在 bazel query 等分析工具的輸出結果。

對於每種建構規則，規則的說明文件都包含 這個特殊章節，詳細說明任何隱含 輸出結果會包含該類規則的宣告。

兩個核心指標 兩個建構系統使用的命名空間： labels 可識別目標， 可以是規則或檔案，而檔案目標則可劃分成 來源 (或輸入) 檔案目標和衍生 (或輸出) 檔案 目標。您可以在 BUILD 檔案中提及以下內容 透過指令列建構，或使用 bazel query 進行檢查。 這是目標命名空間每個檔案目標都會對應至 改為磁碟中的一個實際檔案 (「檔案系統命名空間」)；每項規則 目標可能會對應到零，或是磁碟上的實際檔案。 磁碟中可能可能有檔案沒有相應的目標。的 例如：C++ 編譯期間產生的 .o 物件檔案 無法從 BUILD 檔案或指令列參照。 這樣一來，建構工具可能會隱藏某些實作詳細資料 它的運作方式如需詳細說明，請參閱 BUILD 概念參考資料。