常見定義

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

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

目錄

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

Bourne 殼層權杖化

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

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

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

標籤擴展

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

屬性範例包括 genrule.cmd 和 cc_binary.linkopts。在各個情況下，詳細資料可能會因下列問題而有顯著差異：是否要展開相對標籤；如何處理展開至多個檔案的標籤等等。請參閱規則屬性說明文件，瞭解詳細資訊。

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

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

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

所有建構規則通用的屬性

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

屬性	說明
compatible_with	標籤清單； 無法設定；預設為 [] 除了預設支援的環境外，此目標可建構的環境清單。 這是 Bazel 限制系統的一部分，可讓使用者宣告 彼此間的關係，彼此互不相通。舉例來說，外部可部署的二進位檔不應依附含有公司機密程式碼的程式庫。詳情請見 ConstraintSemantics。
deprecation	String;不可設定；預設為 None 與此目標相關的說明警告訊息。通常用於通知使用者目標已過時 或受到其他規則取代、為套件專用，或 但可能因為某些原因而被視為有害建議你附上 一些參考資料 (例如網頁、錯誤編號或遷移 CL 範例)，因此 也很容易知道必須進行哪些變更，才能避免這個訊息。 如果有一個新目標可做為替換品使用， 建議您只遷移舊目標的所有使用者。 這個屬性對建構方式沒有影響，但 可能會影響建構工具的診斷輸出。建構工具會發出 如果規則包含 deprecation 屬性，則為警告 相依於另一個套件中的目標 就此警告而言，內部套件依附元件不受此警告的規範， 舉例來說，為已淘汰的規則建立測試時， 那麼網站會收到警告 如果已淘汰的目標依附於另一個已淘汰的目標，系統不會發出警告訊息。 一旦使用者停止使用，即可移除目標。
distribs	字串清單；不可設定；預設為 [] 這個特定目標要使用的發布方法字串清單。 這是 Bazel 不再使用的授權 API 的一部分。錯誤做法 即可。
exec_compatible_with	標籤清單；不可設定；預設為 [] 此目標的執行平台中必須具備的 constraint_values 清單。這是在規則類型已設定的任何限制之外。使用限制 以限制可用執行平台的清單詳情請參閱 模型的說明 工具鍊解決方案。
exec_properties	字串字典；預設值為 {} 字串字典，會新增至為這個目標選擇的平台的 exec_properties。請參閱 platform 規則的 exec_properties。 如果平台和目標層級資源中同時出現某個鍵，系統會從目標擷取該值。
features	feature 字串清單；預設為 [] 功能是字串標記，可為目標啟用或停用。 功能的意義取決於規則本身。 這個 features 屬性會與 套件層級 features 屬性。舉例來說 套件層級已啟用功能 [「a」、「b」，且目標的 features 屬性包含 ["-a", "c"]，表示為 規則會是「b」和「c」鍵。 查看範例。
restricted_to	標籤清單； 無法設定；預設為 [] 這個目標可以建構的環境清單，而不是 支援預設環境 這是 Bazel 限制系統的一部分。詳情請參閱 compatible_with。
tags	字串清單；不可設定；預設為 [] 代碼可用於任何規則。測試和 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	標籤清單；預設為 [] 一系列 constraint_values 必須存在於目標平台中，系統才會將這個目標視為 「相容」。除了 規則類型如果目標平台不符合所有列出的限制， 系統就會視為不相容的目標。當目標模式展開 (例如 //...、:all) 時，系統會略過不相容的目標，以便建構及測試。如果在指令列中明確指定不相容的目標，Bazel 會列印錯誤訊息，並導致建構或測試失敗。 間接依賴不相容的目標本身 視為不相容建構和測試時，也會略過這些 KPI。 如果空白清單 (預設) 代表目標相容 與所有平台互動 除了「工作區規則」以外，所有規則都支援這項屬性。對某些規則而言，這個屬性不會有任何作用。例如指定 target_compatible_with 代表 cc_toolchain 不實用。 詳情請參閱 平台 頁面，進一步瞭解不相容的目標略過。
testonly	布林值；不可設定；預設為 False ，除了測試套件和測試套件 如果設為 True，則只有測試專用的目標 (例如測試) 能夠依賴這個目標。 等同於不允許 testonly 的規則 取決於 testonly 的所有規則。 測試 (*_test 項規則) 和測試套件 (test_suite 規則) 預設為 testonly。 這個屬性是用來表示目標不得 包含在發布正式版的二進位檔中。 因為測試只會在建構期間強制執行，而非執行時間，並傳播 穿過依附性樹狀結構，應該謹慎地應用。適用對象 例如虛設常式和虛構資料 您對於進行整合測試也相當實用 包含即將發布到正式版的相同二進位檔 因此不應標示為「test only」相反地 即使沒有條件也沒關係 覆寫正常行為，應確實標示為 testonly。
toolchains	標籤清單；無法設定；預設為 [] 這個目標的「建立變數」的一組目標 。這些目標是規則的例項，可提供 TemplateVariableInfo，或為 Bazel 內建的工具鍊類型提供特殊目標。包括： @bazel_tools//tools/cpp:current_cc_toolchain @bazel_tools//tools/jdk:current_java_runtime 請注意，這與 工具鍊解決方案 處理各平台設定的規則。您無法使用這個項目 屬性決定是哪些特定 cc_toolchain 或 java_toolchain 目標模型會使用
visibility	標籤清單；不可設定；如果已指定，則預設為package 中的 default_visibility，否則為 "//visibility:private" 目標的 visibility 屬性可控制該目標 可用於其他套件詳情請參閱 瀏覽權限

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

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

屬性	說明
args	字串清單；會依據 $(location) 和 "Make 變數" 替換，以及 Bourne shell 符記化；預設為 [] Bazel 會在發生什麼情況時，將指令列引數傳遞至目標 以 bazel test 執行。 這些引數會在任何 --test_arg 值之前傳遞 您在 bazel test 指令列中指定的資訊。
env	字串字典；值會根據 $(location) 和 「Make 變數」替換；預設值為 [] 指定執行測試時要設定的其他環境變數 bazel test。 這項屬性僅適用於原生規則，例如 cc_test。 py_test和sh_test。不適用於 Starlark 定義的測試規則。針對自己的 Starlark 規則，您可以新增「env」 屬性並用於填入 TestEnvironment 提供者。
env_inherit	字串清單；預設值為 [] 指定在 bazel test 執行測試時，要從外部環境繼承的其他環境變數。 這項屬性僅適用於原生規則，例如 cc_test、py_test。 和 sh_test。不適用於 Starlark 定義的測試規則。
size	字串 "enormous"、"large"、"medium" 或 "small"；不可設定；預設為 "medium" 指定測試目標的「重度」：執行測試需要花費的時間/資源。 單元測試分為「小」，整合測試為「中」，端對端測試則為「大型」或 「巨大」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	字串 "short"、"moderate"、"long" 或 "eternal"；不可設定；系統會衍生出預設值 測試的 size 屬性 測試在傳回前的預期執行時間。 測試的大小屬性會影響資源估算， 逾時。如果沒有明確指定 逾時取決於測試大小。測試 逾時可使用 --test_timeout 旗標覆寫，例如的 在某些已知速度緩慢的情況下運作。測試逾時值對應的時間範圍如下： 逾時值 時間範圍 short 1 分鐘 中度 5 分鐘 long 15 分鐘 Eternal 60 分鐘 如果不是上述時間，可使用 --test_timeout bazel 旗標，例如手動執行 但已知會執行速度緩慢的情況--test_timeout 值 都能在幾秒內完成舉例來說，--test_timeout=120 會將測試逾時時間設為兩分鐘。 產生測試時，環境變數 TEST_TIMEOUT 會設為測試逾時 (以秒為單位)。
flaky	布林值；不可設定； 預設為 False 將測試標示為「容易」。 如果已設定，最多會執行測試三次，只有在測試失敗時才標示為失敗 失敗。此屬性預設為 False，而測試為 執行一次請注意，一般不建議使用這項屬性。 但測試應該穩定通過其斷言。
shard_count	小於或等於 50 的非負整數；預設值為 -1 指定平行資料分割數量 以便執行測試 如果已設定，這個值會覆寫用於決定用來執行測試的平行資料分割數量的任何推論法。請注意，在部分測試中 可能需要用到這個參數，才能啟用資料分割功能 一開始就做出決定另請參閱 --test_sharding_strategy。 如果測試資料分割已啟用，系統會在產生測試時將環境變數 TEST_TOTAL_SHARDS 設為這個值。 資料分割需要測試執行器來支援測試資料分割通訊協定。 如果不是的話，則很可能會在每個資料分割中執行所有測試； 並非您想要的 詳情請見 測試資料分割 。
local	布林值；不可設定； 預設為 False 強制在本機執行測試，不採用沙箱機制。 將此值設為 True 相當於提供「local」做為標記 (tags=["local"])。

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

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

屬性	說明
args	字串清單；取決於 $(location)和 「設為變數」替代，以及 Bourne 殼層權杖化； 無法設定； 預設值為 [] Bazel 會在執行時傳遞至目標的指令列引數 透過 run 指令或測試。這些引數會在 bazel run 或 bazel test 指令列上指定的引數之前傳遞。 注意：執行目標時不會傳遞引數 在 Bazel 之外 (例如，手動在 bazel-bin/)。
env	字串字典；值會根據 $(location) 和 "Make 變數" 替換；預設值為 {} 指定要在目標： 由 bazel run 執行。 這項屬性僅適用於原生規則，例如 cc_binary、py_binary 和 sh_binary。不適用於 Starlark 定義的執行規則。 注意：執行目標時不會設定環境變數 在 Bazel 之外 (例如，手動在 bazel-bin/)。
output_licenses	字串清單；預設為 [] 這個二進位檔產生的輸出檔案授權。 這是 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 等分析工具的輸出內容中觀察到。

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

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