常見定義

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

目錄

Bourne 殼層權杖化

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

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

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

標籤擴展

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

屬性範例包括 genrule.cmdcc_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

套用這項規則或納入這項規則的檔案。通常會直接列出檔案,但 可能會列出規則目標 (例如 filegroupgenrule) 包括其預設輸出內容

特定語言專用的規則通常需要列出的檔案要有特定的 副檔名。

所有建構規則通用的屬性

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

屬性 說明
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 規則適合用來將測試分類。 非測試目標上的代碼可用來控制是否採用沙箱機制, genruleStarlark 以及由人類和/或外部工具剖析資料。

Bazel 發現以下項目時,會修改沙箱程式碼的行為 任何測試或 genruletags 屬性中的關鍵字 或 execution_requirements 任何 Starlark 的鍵 動作。

  • no-sandbox 個關鍵字帶來的操作或測試從未出現 採用沙箱機制但還是可以快取或從遠端執行:請使用 no-cacheno-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 規則 在計算要建構/執行的頂層目標組合時,系統不會明確列出測試 編寫 buildtestcoverage 指令沒有 在其他情況下會影響目標萬用字元或測試套件擴充,包括 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_toolchainjava_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_testpy_testsh_test。不適用於 Starlark 定義的測試規則。針對自己的 Starlark 規則,您可以新增「env」 屬性並用於填入 TestEnvironment 提供者。

env_inherit

List of strings; optional

指定要繼承自 外部環境 (當 bazel test 執行測試時)。

這項屬性僅適用於原生規則,例如 cc_testpy_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_binarypy_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_settingconstraint_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 概念參考資料