本頁面提供使用 Bazel Query Language 的參考手冊
當您使用 bazel query
分析建構依附元件時。此外,
會說明 bazel query
支援的輸出格式。
如要瞭解實際用途,請參閱 Bazel 查詢使用方法。
其他查詢參考資料
除了 query
,它會在載入後階段目標圖表上執行。
Bazel 包含動作圖查詢和可設定的查詢。
動作圖表查詢
動作圖表查詢 (aquery
) 會根據設定後的分析作業
「目標圖表」會顯示動作、成果和
包括模型和網路之間的關係如果你對下列主題感興趣,aquery
非常實用
屬性。
舉例來說,實際指令會執行,以及指令的輸入內容、輸出內容和助詞。
詳情請參閱查詢參考資料。
可設定的查詢
傳統 Bazel 查詢會在載入後階段目標圖表上執行
因此沒有設定及其相關概念的概念。值得注意的是
無法正確解析選取陳述式
而是傳回所有可能的選取解析度不過,
可設定的查詢環境「cquery
」可正確處理設定,但
並未提供原始查詢的所有功能。
詳情請參閱 cquery 參考資料。
範例
使用者如何使用 bazel query
?以下是常見的範例:
為什麼 //foo
樹狀結構依附於 //bar/baz
?
顯示路徑:
somepath(foo/..., //bar/baz:all)
C++ 程式庫執行所有 foo
測試依附於哪些項目
不是「foo_bin
」目標?
kind("cc_library", deps(kind(".*test rule", foo/...)) except deps(//foo:foo_bin))
符記:詞法語法
查詢語言的運算式由以下項目組成: 符記:
關鍵字,例如
let
。關鍵字是 並逐一說明。整組 的關鍵字為:字詞,例如「
foo/...
」或「.*test rule
」或「//bar/baz:all
」。如果 字元序列為「引號」(開頭和結尾為單引號 ' 或 開頭和結尾為雙引號 "),代表這是字詞。如果字元序列 系統可能會將其剖析為字詞。未加引號的字詞為序列 從字母字元 A 到 Za-z、數字 0 到 9 和特殊字元*/@.-_:$~[]
(星號、正斜線、@、句號、 連字號, 底線, 冒號, 錢幣符號, 波浪號, 左正方形括號, 右正方形 。不過,未加引號的字詞不能以連字號-
或星號*
開頭 即使相對目標名稱 幫助大眾找到相關資訊未加引號的字詞也不得包含加號
+
或等號 符號=
,即使目標名稱中允許包含這些字元也一樣。時間 編寫產生查詢運算式的程式碼,應加上目標名稱。編寫建構 Bazel 查詢的指令碼時,「是」必須進行佇列 運算式。
//foo:bar+wiz # WRONG: scanned as //foo:bar + wiz. //foo:bar=wiz # WRONG: scanned as //foo:bar = wiz. "//foo:bar+wiz" # OK. "//foo:bar=wiz" # OK.
請注意,本句話外是其他引述方式 您的殼層,例如:
bazel query ' "//foo:bar=wiz" ' # single-quotes for shell, double-quotes for Bazel.
關鍵字和運算子 (在引號中) 會視為一般字詞。例如,
some
是 而是「某」是一個字詞foo
和「foo」都有效字詞不過,在目標名稱中使用單引號或雙引號時,請務必小心。時間 引用一或多個目標名稱,請只使用一種類型的引號 (包括 單引號或全雙引號)。
以下是 Java 查詢字串的範例:
'a"'a' # WRONG: Error message: unclosed quotation. "a'"a" # WRONG: Error message: unclosed quotation. '"a" + 'a'' # WRONG: Error message: unexpected token 'a' after query expression '"a" + ' "'a' + "a"" # WRONG: Error message: unexpected token 'a' after query expression ''a' + ' "a'a" # OK. 'a"a' # OK. '"a" + "a"' # OK "'a' + 'a'" # OK
我們選擇了這種語法,因此在大多數情況下,都不需要加上引號。 (異常)
".*test rule"
範例需要加上引號:開頭為句號, 包含空格。提及"cc_library"
是非必要的,但無害。標點符號,例如括號
()
、句號.
和半形逗號,
。字詞 包含標點符號 (上述例外項目除外)。
引用字詞外的空白字元會遭到忽略。
Bazel 查詢語言概念
Bazel 查詢語言是一種運算式,每次 運算式會評估為部分排序的目標、 或同樣是目標的圖表 (DAG)。只有 資料類型。
組合和圖表參照相同資料類型,但重點不同 相關面向,例如:
- 設定:目標的部分順序對結果不重要。
- 圖表:指定目標的部分順序相當重要。
依附元件圖表中的週期
建構依附元件圖表應循環出現。
查詢語言所使用的演算法 但針對循環次數十分強大詳細介紹 系統不會指定週期,因此不應仰賴週期。
隱含依附性
除了建構在 BUILD
檔案中明確定義的依附元件之外,
Bazel 會將額外的「隱含」依附元件新增至規則。例如:
每個 Java 規則都隱含於 JavaBuilder隱含依附性
是使用開頭為 $
,且它們開頭為
且無法在 BUILD
檔案中覆寫。
每個預設的 bazel query
會將隱含依附元件列入考量
當我們計算查詢結果時這個行為可以經由
--[no]implicit_deps
選項。請注意,由於查詢
設定時不會考慮潛在工具鍊。
聲音
Bazel 查詢語言運算式會針對建構作業執行
依附關係圖,這個圖表由所有元件以隱含方式定義
規則宣告BUILD
。請務必瞭解
這張圖是抽象的
執行建構所有步驟的完整說明。於
需要設定才能執行建構;
請參閱設定
一節。
以 Bazel 查詢語言評估運算式的結果 為 true, 也就是保守的高估值,而不是精確的結果。如果發生以下情況: 使用查詢工具來計算所需的所有來源檔案 可能會回報超過您實際需要的資料 因為例如,查詢工具 系統仍然必須支援訊息翻譯 這樣就能在建構中使用該功能
保存圖表順序
作業會保留任何排序順序
繼承自其子運算式的限制您可以把
也就是「部分命令的守則」。假設
範例:如果發出查詢來判斷
對特定目標的依附元件進行排序
按照依附關係圖而定如果將篩選器設為
只包含 file
種類的目標
各個 Pod 之間的遞移關係保留
產生的子集中的目標
這些組合實際上與原始圖表有直接關聯
(建構依附元件圖表中沒有檔案檔案邊緣)。
不過,雖然所有運算子都會「保留」順序,但 例如集合作業 自行加入任何順序限制。 請參考以下運算式:
deps(x) union y
最終結果集的順序會保證保留所有
也就是子運算式的排序限制
x
的遞移依附元件如何正確以
互相影響。不過,查詢保證
y
中的目標順序,也不是
deps(x)
中的目標相對於
y
(下列區域的這些目標除外)
發生在 deps(x)
中的 y
)。
導入排序限制的運算子包括:
allpaths
、deps
、rdeps
、somepath
和目標模式萬用字元
package:*
、dir/...
等
星空查詢
「Sky Query」是一種查詢模式,可針對指定「宇宙」運作。
僅適用於 SkyQuery 的特殊函式
「星空查詢」模式具有額外的查詢函式 allrdeps
和
rbuildfiles
。這類函式會針對
範圍 (所以這對一般查詢來說無意義)。
指定宇宙範圍
傳遞下列兩個旗標,即可啟用 Sky Query 模式:
(--universe_scope
或 --infer_universe_scope
) 和
--order_output=no
。
--universe_scope=<target_pattern1>,...,<target_patternN>
會告知查詢:
預先載入目標模式指定目標模式的遞移性閉包,
影響程度可能為加減然後評估這個「範圍」中的所有查詢。我們要用
allrdeps
和
rbuildfiles
運算子只會傳回這個範圍的結果。
--infer_universe_scope
會告知 Bazel 推論 --universe_scope
的值
查詢運算式傳回的值這項推測值是
但這可能不是您想要的結果例如:
bazel query --infer_universe_scope --order_output=no "allrdeps(//my:target)"
這個查詢運算式中的不重複目標模式清單是 ["//my:target"]
,因此
Bazel 會將這一點視為叫用:
bazel query --universe_scope=//my:target --order_output=no "allrdeps(//my:target)"
但使用 --universe_scope
查詢的結果僅為 //my:target
。
//my:target
的反向依附元件都並非宇宙
建造!另一方面,請考量以下幾點:
bazel query --infer_universe_scope --order_output=no "tests(//a/... + b/...) intersect allrdeps(siblings(rbuildfiles(my/starlark/file.bzl)))"
此為有意義的查詢叫用作業,會嘗試計算
tests
會擴大一些目錄中的目標
間接依附於定義使用特定 .bzl
檔案的目標。在這裡
--infer_universe_scope
是便利的方式,尤其是在
否則,您必須使用 --universe_scope
自行剖析查詢運算式。
因此,對於使用宇宙範圍運算子的查詢運算式 (例如
allrdeps
和
rbuildfiles
請務必使用
--infer_universe_scope
。
與預設查詢相比,「星空查詢」有一些優缺點。主要
缺點是無法根據圖表順序排列輸出內容,因此可能會
系統禁止使用輸出格式。這麼做的好處是
兩種運算子 (allrdeps
和
rbuildfiles
) 未在預設查詢中使用。
「星空查詢」同樣會遵循
顯示 SkyFrame 圖表,而非建立新的
這也是預設導入方式的功用因此,在某些情況下
且使用較少的記憶體
運算式:文法的語法和語意
以下是 Bazel 查詢語言的文法,以 EBNF 標記法表示:
expr ::= word
| let name = expr in expr
| (expr)
| expr intersect expr
| expr ^ expr
| expr union expr
| expr + expr
| expr except expr
| expr - expr
| set(word *)
| word '(' int | word | expr ... ')'
以下各節將依序說明這個文法的產生內容。
目標模式
expr ::= word
就語法上來說,「目標模式」只是一個字詞。會被系統視為
(未排序) 目標組合。最簡單的目標模式是標籤
識別單一目標 (檔案或規則)例如:目標模式
//foo:bar
會評估為包含目標 (目標、bar
) 的集合
規則。
目標模式一般化標籤,在套件及套件及
目標。舉例來說,foo/...:all
(或只是 foo/...
) 是目標模式
,評估成包含每個套件中所有規則的組合
在 foo
目錄下;bar/baz:all
是一項會評估
設為包含 bar/baz
套件中所有規則的集合,但不含該套件中的所有規則
子套件。
同樣地,foo/...:*
是一種目標模式,會評估為包含
在每個套件中遞迴的「目標」 (規則「以及」檔案)
foo
目錄;bar/baz:*
會評估為包含
bar/baz
套件,而非子套件。
由於 :*
萬用字元會比對檔案和規則,因此通常較常顯示
比 :all
更實用。相反地,:all
萬用字元 (隱含
通常更適合用於建構,例如 foo/...
)。
bazel query
目標模式的運作方式與 bazel build
建構目標相同。
詳情請參閱「目標模式」一文,或
類型 bazel help target-syntax
。
目標模式可能會評估為單例模式 (在標籤的情況下),進而為
組合包含多個元素 (就像 foo/...
的情況,子共有數千個元素)
如果目標模式不相符,則傳回空白集合。
目標模式運算式結果產生的所有節點皆已正確排序
系統會依據依附元件關係
管理彼此間的相對路徑解碼器產生出類神經網路後
foo:*
不僅是套件 foo
中的目標組合,也是
圖表會顯示在這些目標上。(不保證相對排序,
依據其他節點的結果節點數量)詳情請參閱
圖表順序區段。
變數
expr ::= let name = expr1 in expr2
| $name
Bazel 查詢語言允許
變數。let
運算式的評估結果與
大於 expr2,所有免費出現次數
變數 name 的值會替換為
expr1.
例如,let v = foo/... in allpaths($v, //common) intersect $v
是
相當於 allpaths(foo/...,//common) intersect foo/...
。
變數參照 name
出現,
包含 let name = ...
運算式是
錯誤。換句話說,頂層查詢運算式不能含有免費值
變數。
以上述文法建立方式而言,name
與 word 相似,但
做為 C 程式設計中法律 ID 的額外限制
語言。變數參照的前面必須加上「$」字元。
每個 let
運算式都只能定義單一變數,但您可以為其建立巢狀結構。
目標模式和變數參照都包含 只會傳回一個符記,代表語法模糊不清不過 語意不明確,因為屬於法律變數的字詞 名稱與合法目標模式字詞的子集不一致。
嚴格說來,let
運算式並未增加
查詢語言的表達性,也就是
也能表達出沒有用字遣詞但
因此有助於簡化許多查詢,也可能使
以有效率的方式進行查詢評估
加括號的運算式
expr ::= (expr)
括號聯結子運算式可強制執行評估順序。 加括號的運算式會評估其引數的值。
代數集運算:交集、聯集、設定差異
expr ::= expr intersect expr
| expr ^ expr
| expr union expr
| expr + expr
| expr except expr
| expr - expr
這三個運算子會計算其引數的一般集運算。
每個運算子都有兩種形式:名目形式 (例如 intersect
),以及
等符號形式,例如 ^
。這兩種形式都相同;符號形式的
輸入速度更快(為求明確,本頁其餘部分採用了名目形式)。
例如:
foo/... except foo/bar/...
會評估符合 foo/...
但不含 foo/bar/...
的目標組合。
您可以編寫相同的查詢:
foo/... - foo/bar/...
intersect
(^
) 和 union
(+
) 作業為可交換 (對稱)
except
(-
) 不對稱。剖析器會將這三種運算子
左右優先順序,因此建議您使用括號。適用對象
例如,前兩個運算式是相等的,第三個不是:
x intersect y union z
(x intersect y) union z
x intersect (y union z)
從外部來源讀取目標:組合
expr ::= set(word *)
set(a b c ...)
運算子會計算 0 或多個實體集合的聯集
目標模式,以空白字元分隔 (不含半形逗號)。
結合 Bourne 殼層的 $(...)
功能時,set()
可提供
將單一查詢的結果儲存在一般文字檔中,
其他程式 (例如標準 UNIX 殼層工具) 擷取文字檔,然後
將結果傳回查詢工具,做為進一步
和資料處理之間例如:
bazel query deps(//my:target) --output=label | grep ... | sed ... | awk ... > foo
bazel query "kind(cc_binary, set($(<foo)))"
在下一個範例中,kind(cc_library, deps(//some_dir/foo:main, 5))
是
是使用 awk
程式篩選 maxrank
值後得出的結果。
bazel query 'deps(//some_dir/foo:main)' --output maxrank | awk '($1 < 5) { print $2;} ' > foo
bazel query "kind(cc_library, set($(<foo)))"
在這些範例中,$(<foo)
是 $(cat foo)
的簡寫,而是殼層
可能也會使用 cat
以外的指令,例如先前的 awk
指令。
函式
expr ::= word '(' int | word | expr ... ')'
查詢語言定義了多個函式。函式的名稱 決定所需的引數數量和類型下列 可用的函式:
allpaths
attr
buildfiles
rbuildfiles
deps
filter
kind
labels
loadfiles
rdeps
allrdeps
same_pkg_direct_rdeps
siblings
some
somepath
tests
visible
遞移依附元件: deps
expr ::= deps(expr)
| deps(expr, depth)
deps(x)
運算子會評估轉換為圖形
其引數集的依附元件的遞移性關閉
x。例如,deps(//foo)
的值是
源自單一節點 foo
的依附元件圖表,包括該節點的所有
依附元件deps(foo/...)
的值是具有根層級的依附元件圖表
都是 foo
目錄下每個套件的所有規則。在這個情況下
「dependencies」表示只有規則和檔案目標,因此 BUILD
和
這裡不包含建立這些指定目標所需的 Starlark 檔案。為此
應使用 buildfiles
運算子。
產生的圖表會根據依附元件關係排序。如要 詳情,請參閱「圖表順序」一節。
deps
運算子接受選用的第二個引數 (整數是整數)
用於指定搜尋深度上限的常值。以下內容
deps(foo:*, 0)
會傳回 foo
套件中的所有目標,而
deps(foo:*, 1)
還包括
foo
套件,而 deps(foo:*, 2)
進一步包含節點
可從 deps(foo:*, 1)
中的節點連線,以此類推。(這些數字
排名會對應至 minrank
輸出格式中顯示的排名)
如果省略 depth 參數,則搜尋會
無限制:會計算先決條件的反彈性遞移性關閉。
遞移依附元件的遞移依附元件:rdeps
expr ::= rdeps(expr, expr)
| rdeps(expr, expr, depth)
rdeps(u, x)
運算子會評估引數集的反依附性
宇宙集大眾運輸系統中的 x
u。
產生的圖表會根據依附元件關係排序。詳情請參閱 圖表順序一節。
rdeps
運算子接受選用的第三個引數 (整數)
用於指定搜尋深度上限的常值。最終產生的
圖表只包含指定深度與任意深遠距離內的節點
加入任何 Pod 的節點因此,rdeps(//foo, //common, 1)
會評估所有節點
在 //foo
的遞移性封閉中,直接依附於 //common
(這些
數字對應 minrank
輸出內容中顯示的排名
format.)如果省略 depth 參數,
可以無限搜尋。
所有反向依附元件的遞移性關閉:allrdeps
expr ::= allrdeps(expr)
| allrdeps(expr, depth)
allrdeps
運算子的行為與 rdeps
相同
運算子,不過系統會是 --universe_scope
旗標
而非單獨指定因此,如果
系統已通過 --universe_scope=//foo/...
,之後 allrdeps(//bar)
為
相當於 rdeps(//foo/..., //bar)
。
直接在同一個套件中直接反向依附元件:same_pkg_direct_rdeps
expr ::= same_pkg_direct_rdeps(expr)
same_pkg_direct_rdeps(x)
運算子會評估完整的目標組合
與引數集的目標位於同一個套件中,且直接依附於該套件。
處理目標的套件:同層級
expr ::= siblings(expr)
siblings(x)
運算子會評估在
與引數集中目標相同的套件
任意選擇:部分
expr ::= some(expr)
| some(expr, count )
some(x, k)
運算子
最多只能從以下位置選擇最多 k 個目標
引數集 x,且評估為包含
只有這些目標「k」是選用參數;如果
結果,結果會是只包含一個目標的單例模式集
任意選取如果引數集 x 的大小
小於 k,則整個引數集
即將退回 x。
例如,some(//foo:main union //bar:baz)
運算式會得出
包含 //foo:main
或 //bar:baz
的單例模式集,不過
尚未定義運算式 some(//foo:main union //bar:baz, 2)
或
some(//foo:main union //bar:baz, 3)
會同時傳回 //foo:main
和
//bar:baz
。
如果引數為單例模式,則 some
會計算身分函式:some(//foo:main)
是
相當於 //foo:main
。
如果指定的引數集為空白,就會發生錯誤,例如
運算式 some(//foo:main intersect //bar:baz)
。
路徑運算子:somepath、allpaths
expr ::= somepath(expr, expr)
| allpaths(expr, expr)
somepath(S, E)
和
allpaths(S, E)
運算子運算功能
找出兩組目標之間的路徑兩項查詢都接受兩種查詢
以及一組 S 起點和集合
終點 E。somepath
會傳回
來自以下目標的部分任意路徑節點的圖表:
將 S 套用至 E 中的目標;allpaths
會傳回以下項目中任何目標的所有路徑節點圖表:
將 S 套用至 E 中的任何目標。
產生的圖表會根據依附元件關係排序。 詳情請參閱「圖表順序」一節。
目標種類篩選:Kind
expr ::= kind(word, expr)
kind(pattern, input)
運算子可將篩選器套用至一組目標,然後捨棄這些目標
不屬於預期的類別pattern
參數會指定要比對的目標類型。
例如 BUILD
檔案定義的四個目標種類。
(適用於套件 p
) 如下表所示:
程式碼 | 目標 | 種類 |
---|---|---|
genrule( name = "a", srcs = ["a.in"], outs = ["a.out"], cmd = "...", ) |
//p:a |
Genrule 規則 |
//p:a.in |
來源檔案 | |
//p:a.out |
產生的檔案 | |
//p:BUILD |
來源檔案 |
因此,kind("cc_.* rule", foo/...)
的評估結果為
包含所有 cc_library
、cc_binary
等
foo
和 kind("source file", deps(//foo))
底下的規則目標
評估標準為遞移性關閉中的所有來源檔案集
指定 //foo
目標的依附元件
通常必須使用引號 pattern 引數
如果沒有,則許多規則運算式 (例如 source
file
和 .*_test
) 不會被剖析器視為字詞。
比對 package group
時,結尾為
:all
可能不會產生任何結果。請改用 :all-targets
。
目標名稱篩選:篩選器
expr ::= filter(word, expr)
filter(pattern, input)
運算子會將篩選器套用至一組目標,並捨棄含有該條件的
標籤 (絕對格式) 與模式不符;該資料來源
會得出輸入內容的子集
第一個引數 pattern 是內含
規則運算式,勝過目標名稱。filter
運算式
會評估包含所有指定目標 x 的組合,
x 是 input 集合的成員,
標籤 (以絕對格式,例如 //foo:bar
)
的 x 包含 (未錨定) 比對
規則運算式 pattern和所有參與者
目標名稱開頭為 //
,可當做替代名稱使用
加到 ^
規則運算式錨點
這個運算子通常會提供更快、更可靠的替代方案。
intersect
運算子。舉例來說,假設您要查看
//foo:foo
目標的 bar
項依附元件,一項可
評估
deps(//foo) intersect //bar/...
不過,這個陳述式需要剖析BUILD
bar
樹狀結構,速度較慢,且容易出現錯誤
不相關的 BUILD
檔案。替代方法是:
filter(//bar, deps(//foo))
系統會先計算一組 //foo
依附元件
這樣就只會篩選符合指定模式的目標,其他
且名稱包含 //bar
做為子字串的目標。
filter(pattern,
expr)
運算子的另一個常見用法是按照
或副檔名例如:
filter("\.cc$", deps(//foo))
將會提供一份清單,列出所有用於建構 //foo
的 .cc
檔案。
規則屬性篩選:attr
expr ::= attr(word, word, expr)
attr(name, pattern, input)
運算子會將篩選器套用至一組目標,並捨棄不符合的目標
規則, 規則目標不含 name 屬性
定義或規則目標,但屬性值與提供的
規則運算式 pattern;模型會評估
屬於輸入內容子集
第一個引數 name 是規則名稱
應與所提供
規則運算式模式。第二個引數
pattern 是屬性上的規則運算式
輕鬆分配獎金attr
運算式會評估為包含所有目標的資料集
x,且 x 是
input 集合的成員是具有已定義
屬性 [name],而屬性值則包含
(未錨定) 比對規則運算式
pattern。如果 name 是
選擇性屬性和規則並未明確指定預設值
屬性值會用於比較。例如:
attr(linkshared, 0, deps(//foo))
將會選取所有 //foo
可存取的依附元件
連結共用屬性 (例如 cc_binary
規則) 並加上
明確設為 0 或完全不設定,但預設值為 0 (例如
cc_binary
規則)。
清單類型屬性 (例如 srcs
、data
等)
並轉換為 [value<sub>1</sub>, ..., value<sub>n</sub>]
格式的字串
以 [
方括號開始,結尾為 ]
並使用「,
」(逗號、空格) 來分隔多個值。
您可以使用
標籤。舉例來說,屬性 deps=[":foo",
"//otherpkg:bar", "wiz"]
會轉換為
字串 [//thispkg:foo, //otherpkg:bar, //thispkg:wiz]
。
括號一律存在,因此空白清單會使用字串值 []
進行比對例如:
attr("srcs", "\[\]", deps(//foo))
將會選取 //foo
個依附元件中具有
srcs
屬性為空白,而
attr("data", ".{3,}", deps(//foo))
將會選取 //foo
項依附元件當中指定下列所有規則的規則
data
屬性中至少有一個值 (每個標籤至少
由於 //
和 :
的關係,長度為 3 個字元)。
如要在 //foo
依附元件中,具有特定 value
的所有規則,請在
list-type 屬性,請使用
attr("tags", "[\[ ]value[,\]]", deps(//foo))
這麼做的原因在於 value
之前的字元是 [
或空格,
value
之後的字元會是半形逗號或 ]
。
規則瀏覽權限篩選:可見
expr ::= visible(expr, expr)
visible(predicate, input)
運算子
將篩選器套用至一組目標,並在沒有
所需的瀏覽權限
第一個引數 predicate 是一組目標 還是只有能看得見的結果visible 運算式 會評估包含所有目標 x 的資料集,進而x 屬於 input 集合的成員,且為 y 中的所有目標 「y」可以看到 predicate x。例如:
visible(//foo, //bar:*)
將會選取 //foo
套件中 //bar
的所有目標
仰賴沒有違反瀏覽權限限制的依附元件。
評估「label」類型的規則屬性
expr ::= labels(word, expr)
labels(attr_name, inputs)
運算子會傳回在
「label」類型的屬性 attr_name或「標籤清單」英吋
「inputs」組合中的一些規則。
舉例來說,labels(srcs, //foo)
會傳回一組
出現在目標網頁的 srcs
屬性中
//foo
規則。如果有多個規則
在 inputs 中設定 srcs
屬性時,
其 srcs
的聯集會傳回。
展開並篩選 test_suites:測試
expr ::= tests(expr)
tests(x)
運算子會傳回所有測試的集合
將任何 test_suite
規則展開為「x」集內的規則
並套用篩選條件
tag
和size
。
根據預設,查詢評估
會忽略所有 test_suite
規則中的任何非測試目標。可用的值包括
已變更為包含 --strict_test_suite
選項的錯誤
舉例來說,查詢 kind(test, foo:*)
會列出所有
*_test
和 test_suite
規則
foo
套件中。所有結果皆為 (
定義) 加入 foo
套件的成員。相對地
tests(foo:*)
查詢會傳回
由 bazel test
foo:*
執行的個別測試:這可能包括其他套件的測試
直接或間接參照
透過 test_suite
規則指定及更新政策
套件定義檔:buildfiles
expr ::= buildfiles(expr)
buildfiles(x)
運算子會傳回集合
定義每個目標套件的檔案
設定 x;也就是每個套件的 BUILD
檔案
加上任何透過 load
參照的 .bzl 檔案。請注意,此
也會傳回含有這些參數的套件的 BUILD
檔案
load
個檔案。
這個運算子通常用於判斷
必須安裝套件才能建構指定的目標,且通常會搭配使用
下方的 --output package
選項)。例如:
bazel query 'buildfiles(deps(//foo))' --output package
會傳回 //foo
間接依附的所有套件組合。
套件定義檔案:rbuildfiles
expr ::= rbuildfiles(word, ...)
rbuildfiles
運算子會使用以半形逗號分隔的路徑片段清單,並傳回
間接依附於這些路徑片段的 BUILD
檔案組合。舉例來說
//foo
是套件,則 rbuildfiles(foo/BUILD)
會傳回
//foo:BUILD
目標。如果 foo/BUILD
檔案的
進入 load('//bar:file.bzl'...
,之後「rbuildfiles(bar/file.bzl)
」會
會傳回 //foo:BUILD
目標,以及其他 BUILD
檔案的目標
載入 //bar:file.bzl
--universe_scope
旗標。未直接對應至 BUILD
檔案和 .bzl
的檔案
檔案不會影響結果。舉例來說,系統會忽略來源檔案 (例如 foo.cc
),
(即使 BUILD
檔案中明確提及)。但系統會遵循符號連結,因此
如果 foo/BUILD
是連結至 bar/BUILD
的符號連結,則
「rbuildfiles(bar/BUILD)
」的結果中會包含「//foo:BUILD
」。
rbuildfiles
運算子幾乎是
buildfiles
運算子。然而,這種道德反轉
就連單一方向來說都較為強烈:rbuildfiles
的輸出內容和
輸入 buildfiles
;前者只會包含套件中的 BUILD
個檔案目標,
後者則可能包含這類目標反之,通訊則較弱。
buildfiles
運算子的輸出內容是與所有套件和 相對應的目標。bzl
特定輸入內容所需的檔案不過,rbuildfiles
運算子的輸入內容
而非這些目標,而是對應這些目標的路徑片段。
套件定義檔:loadfiles
expr ::= loadfiles(expr)
loadfiles(x)
運算子會傳回一組
當中載入每個目標套件所需的 Starlark 檔案
設定「x」。換句話說,這個套件會針對各個套件傳回
從其 BUILD
檔案參照的 .bzl 檔案。
輸出格式
bazel query
會產生圖表。
由您指定內容、格式和順序
bazel query
呈現這張圖表
是由 --output
指令列選項提供
使用 Sky Query 執行時,只會輸出與下列項目相容的格式:
系統會接受未排序的輸出內容。具體來說,graph
、minrank
和
禁止使用 maxrank
輸出格式。
有些輸出格式接受其他選項。名稱
每個輸出選項的輸出格式都會前置字串
,因此 --graph:factored
只會套用
使用 --output=graph
時;如果不需要
則會使用 graph
以外的輸出格式。同樣地
--xml:line_numbers
僅適用於--output=xml
根據結果的排序
雖然查詢運算式一律會遵循「
也就是圖表順序」,表示結果可能已完成
按照依附元件排序或未排序的方式編寫。這不會
影響結果集的目標或查詢的計算方式。只有
會影響結果輸出至 stdout 的方式。此外,節點在
依附元件順序的對等項目不一定會有字母順序。
--order_output
旗標可用來控管這項行為。
(--[no]order_results
標記具備部分功能的子集)
--order_output
旗標,且已淘汰)。
此標記的預設值為 auto
,因此會以 字詞順序顯示結果
訂單。不過,使用 somepath(a,b)
時,系統會將結果列印於
deps
訂單。
當此標記為 no
,且 --output
為其中一個標記時
build
、label
、label_kind
、location
、package
、proto
或
xml
,系統會按照任意順序列印輸出內容。這是為了
(通常最快的方法):但是在
--output
是 graph
、minrank
或
maxrank
:使用這些格式,Bazel 一律會輸出結果
依依附元件順序或排名排序。
當這個標記為 deps
時,Bazel 會依據拓撲順序顯示結果,也就是
先將依附元件放在前但這些節點會依依附元件順序排列。
(因為沒有路徑之間的路徑) 可以任意排列。
當這個標記為 full
時,Bazel 會以完全確定 (總計) 的順序顯示節點。
首先,所有節點會依字母順序排序。然後清單中的每個節點都會做為
進入深度優先搜尋後,系統會週遊至未造訪節點的連出邊緣
後續節點的字母順序。最後,節點會按順序顯示
。
依這個順序列印節點的速度可能較慢,因此請只在確定性為 非常重要
顯示 BUILD 中顯示的目標來源形式
--output build
使用這個選項時,每個目標的呈現方式會像
以 BUILD 語言手寫輸入。所有變數和函式呼叫
(例如 glob、巨集) 會展開,方便您查看
Starlark 巨集。此外,每項有效的規則都會回報
generator_name
和/或 generator_function
) 的值,
這個名稱為系統評估後為產生有效規則的巨集名稱
雖然輸出內容使用的語法與 BUILD
檔案相同,但兩者
請務必產生有效的 BUILD
檔案
列印每個目標的標籤
--output label
使用此選項時,每個目標的名稱集合 (或「標籤」)
這樣產生的圖表就會列印出來,一行一個標籤
頂層順序 (除非指定了 --noorder_results
,請參閱
此屬性適用於結果的排序)。
(按拓撲排序即為
節點比其所有繼承者更早出現)。當然
這些都是圖形的可能拓撲排序 (往回推移)
postorder 僅剩一個);也就是未指定的
輸出 somepath
查詢的輸出內容時,
節點會依照路徑的順序顯示。
注意:在某些極端的情況下,可能會有兩個不同的目標
加入相同標籤例如 sh_binary
規則及其
單一 (隱含) srcs
檔案可同時呼叫
foo.sh
。如果查詢結果同時包含
這些目標就會以 label
格式顯示輸出結果
不包含重複項目使用 label_kind
時 (請參閱
這兩種格式),兩者的區別變得很清楚:這兩個目標
名稱相同,但其中一個包含 sh_binary rule
種類
其他種類 source file
。
列印每個目標的標籤和種類
--output label_kind
和 label
一樣,此輸出格式會輸出
建立圖表中的每個目標
並在標籤前面加上目標的 Kind。
採用通訊協定緩衝區格式的列印目標
--output proto
將查詢輸出內容列印為
QueryResult
敬上
通訊協定緩衝區
以長度分隔的通訊協定緩衝區格式列印目標
--output streamed_proto
列印
長度分隔
串流
Target
敬上
通訊協定緩衝區這有助於 (i) 掌握
尺寸限制
單一通訊協定緩衝區無法容納超過 15 個目標
QueryResult
或 (ii),用來在 Bazel 仍在輸出中開始處理。
以文字 proto 格式列印目標
--output textproto
與 --output proto
類似,系統會輸出
QueryResult
通訊協定緩衝區
文字格式。
以 ndjson 格式列印目標
--output streamed_jsonproto
與 --output streamed_proto
類似,會輸出串流的
Target
通訊協定緩衝區,但格式為 ndjson。
按照排名順序顯示每個目標的標籤
--output minrank --output maxrank
與label
(minrank
) 相似
maxrank
輸出格式則會輸出
但您不會在結果圖表中看到
依時間順序排列,但先是
排名編號這些不會影響結果順序
--[no]order_results
標記 (請參閱
結果的排序)。
這種格式有兩個變化版本:minrank
排名
依據根節點之間最短路徑長度篩選每個節點。
「根」沒有連入邊緣的節點排名為 0
他們的繼承者的排名為 1,依此類推 (一如既往,
並指定其先決條件:所需的目標)。
maxrank
會根據最長長度為各個節點排名
提供完整路徑再說一次「根層級」排名為 0、所有其他
節點的排名高於所有節點
包括前身。
系統會將週期中的所有節點視為相同排名,(大多數圖表
循環不斷,卻出現循環
只是因為 BUILD
檔案包含錯誤循環)。
這些輸出格式可用於瞭解圖表的深度。
如果用於 deps(x)
、rdeps(x)
的結果
或 allpaths
查詢,那麼排名數字等於
最短 (含 minrank
) 或最長的長度
(含 maxrank
) 從 x
到 中節點的路徑
排名maxrank
可用來判斷
建構目標所需的最長建構步驟序列。
舉例來說,左側圖表會產生右側圖表的輸出內容
當--output minrank
和--output maxrank
時
會分別指定
minrank 0 //c:c 1 //b:b 1 //a:a 2 //b:b.cc 2 //a:a.cc |
maxrank 0 //c:c 1 //b:b 2 //a:a 2 //b:b.cc 3 //a:a.cc |
列印每個目標的位置
--output location
和 label_kind
一樣,這個選項會輸出
目標是在結果中的每一個項目、目標的種類和標籤
開頭為一個字串,用來描述該目標的位置,
檔案名稱和行號格式類似
grep
。因此,可以剖析後者的工具 (例如 Emacs)
或 vi) 也可以使用查詢輸出內容,逐步執行一系列的
這樣就能將 Bazel 查詢工具做為
可偵測依附元件的「grep for BUILD 檔案」。
位置資訊會因目標種類而異 (請參閱 Kind 運算子)。對於規則,
系統會列印規則宣告在 BUILD
檔案中的位置。
就來源檔案而言,實際檔案的第 1 行位置為
針對產生的檔案,執行規則的位置
加以列印(查詢工具缺乏條件)
資訊來找出產生檔案的實際位置
無論在任何情況下,如果尚未執行建構作業,就可能不存在。)
列印套件組合
--output package
這個選項會將名稱輸出至 結果集中的部分目標這些名稱會顯示在 字母順序;排除重複項目。從形式來說 是整組標籤 (套件、目標) 的投影到 套件
外部存放區中的套件會採用以下格式:
主要存放區中的套件處於 @repo//foo/bar
狀態
格式為 foo/bar
。
搭配 deps(...)
查詢時,這個輸出結果
這個選項可用來找出需要檢查的套件組合
以便建立一組特定目標
顯示結果圖表
--output graph
這個選項會使查詢結果按照指示列印
採用熱門 AT&T GraphViz 格式的圖表。一般而言,
結果會儲存至 .png
或 .svg
等檔案。
(如果工作站上未安裝 dot
程式,
可以使用 sudo apt-get install graphviz
指令安裝這個套件)。
請參閱下方範例的叫用範例。
這個輸出格式特別適用於 allpaths
。
deps
或 rdeps
查詢,結果
包含無法輕鬆繪製圖表的路徑組合
以線性格式算繪,例如使用 --output label
。
根據預設,圖表會以「因數」格式呈現。也就是說
對等的節點會合併為單一
含有多個標籤的節點讓圖表更精簡
因為典型的結果圖表含有極高的
重複出現的圖形例如 java_library
規則
可能依附於數百個 Java 原始碼檔案,所有檔案均由
相同的 genrule
;所有這些檔案
都以單一節點表示系統可能會停用這項行為
與 --nograph:factored
選項連結。
--graph:node_limit n
這個選項會指定
輸出圖表節點過長的標籤將遭到截斷;-1
會停用截斷功能由於
節點標籤可能會很長GraphViz 無法
處理標籤超過 1024 個字元 (此為預設值)
只要採用這個選項如果只有
正在使用「--output=graph
」。
--[no]graph:factored
根據預設,圖表會以因式結構的形式顯示,詳情請參閱本文說明
上述。
如果指定 --nograph:factored
,則圖表會
列印出來這項功能會使用 GraphViz 視覺化呈現
不切實際,但較簡單的格式可能會被其他標記來簡化
(例如 grep)。這個選項不會產生任何效果
除非已使用 --output=graph
。
XML
--output xml
這個選項會使產生的目標以 XML 輸出 表單中要求的資訊。輸出內容開頭是 XML 標頭,如下所示
<?xml version="1.0" encoding="UTF-8"?>
<query version="2">
然後針對每個目標繼續處理 XML 元素 都會在結果圖表中依熱門順序排列 (除非 未排序的結果); 並在最後使用
</query>
針對 file
種類的目標,系統會發出簡易項目:
<source-file name='//foo:foo_main.cc' .../>
<generated-file name='//foo:libfoo.so' .../>
但以規則來說,XML 便包含
規則屬性,包括非
規則的 BUILD
檔案中明確指定。
此外,結果包含 rule-input
和
rule-output
元素,因此可為
不必知道如何重新建構依附關係圖
例如,srcs
屬性的元素
前向依附元件 (必要條件) 以及
outs
屬性是回溯依附元件 (使用者)。
隱含依附元件的 rule-input
元素會遭到抑制,前提是
已指定 --noimplicit_deps
。
<rule class='cc_binary rule' name='//foo:foo' ...>
<list name='srcs'>
<label value='//foo:foo_main.cc'/>
<label value='//foo:bar.cc'/>
...
</list>
<list name='deps'>
<label value='//common:common'/>
<label value='//collections:collections'/>
...
</list>
<list name='data'>
...
</list>
<int name='linkstatic' value='0'/>
<int name='linkshared' value='0'/>
<list name='licenses'/>
<list name='distribs'>
<distribution value="INTERNAL" />
</list>
<rule-input name="//common:common" />
<rule-input name="//collections:collections" />
<rule-input name="//foo:foo_main.cc" />
<rule-input name="//foo:bar.cc" />
...
</rule>
目標的每個 XML 元素都含有 name
屬性,其值是目標的標籤,以及
location
屬性,其值是目標
如 --output location
列印的位置。
--[no]xml:line_numbers
根據預設,XML 輸出內容顯示的位置會包含行號。
指定 --noxml:line_numbers
時,系統不會列印行數。
--[no]xml:default_values
根據預設,XML 輸出不會包含含有值的規則屬性
是該種類屬性的預設值 (例如,
未在 BUILD
檔案中指定,或預設值為
明確提供)。這個選項會使這類屬性值
會包含在 XML 輸出中
規則運算式
查詢語言中的規則運算式使用 Java regex 程式庫,因此您可以使用
完整的語法
java.util.regex.Pattern
。
使用外部存放區查詢
如果建構取決於外部存放區的規則 (
WORKSPACE 檔案),查詢結果會包含這些依附元件。適用對象
舉例來說,如果 //foo:bar
依賴 //external:some-lib
//external:some-lib
會繫結至 @other-repo//baz:lib
,然後
bazel query 'deps(//foo:bar)'
會列出「@other-repo//baz:lib
」和
//external:some-lib
做為依附元件。
外部存放區本身不是建構作業的依附元件。也就是說
上述範例,//external:other-repo
不是依附元件。這項服務
也可視為 //external
套件的成員進行查詢
例如:
# Querying over all members of //external returns the repository.
bazel query 'kind(http_archive, //external:*)'
//external:other-repo
# ...but the repository is not a dependency.
bazel query 'kind(http_archive, deps(//foo:bar))'
INFO: Empty results