Bazel 查詢參考資料

回報問題 查看原始碼 。 。 。 。 夜間7.3 。 。 7.2 。 。 7.1 。 。 7.0 。 。 6.5

本頁面提供使用 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)。

導入排序限制的運算子包括: allpathsdepsrdepssomepath 和目標模式萬用字元 package:*dir/...

星空查詢

「Sky Query」是一種查詢模式,可針對指定「宇宙」運作。

僅適用於 SkyQuery 的特殊函式

「星空查詢」模式具有額外的查詢函式 allrdepsrbuildfiles。這類函式會針對 範圍 (所以這對一般查詢來說無意義)。

指定宇宙範圍

傳遞下列兩個旗標,即可啟用 Sky Query 模式: (--universe_scope--infer_universe_scope) 和 --order_output=no--universe_scope=<target_pattern1>,...,<target_patternN> 會告知查詢: 預先載入目標模式指定目標模式的遞移性閉包, 影響程度可能為加減然後評估這個「範圍」中的所有查詢。我們要用 allrdepsrbuildfiles 運算子只會傳回這個範圍的結果。 --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 自行剖析查詢運算式。

因此,對於使用宇宙範圍運算子的查詢運算式 (例如 allrdepsrbuildfiles 請務必使用 --infer_universe_scope

與預設查詢相比,「星空查詢」有一些優缺點。主要 缺點是無法根據圖表順序排列輸出內容,因此可能會 系統禁止使用輸出格式。這麼做的好處是 兩種運算子 (allrdepsrbuildfiles) 未在預設查詢中使用。 「星空查詢」同樣會遵循 顯示 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 = ... 運算式是 錯誤。換句話說,頂層查詢運算式不能含有免費值 變數。

以上述文法建立方式而言,nameword 相似,但 做為 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 ... ')'

查詢語言定義了多個函式。函式的名稱 決定所需的引數數量和類型下列 可用的函式:

遞移依附元件: 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 起點和集合 終點 Esomepath 會傳回 來自以下目標的部分任意路徑節點的圖表: 將 S 套用至 E 中的目標;allpaths 會傳回以下項目中任何目標的所有路徑節點圖表: 將 S 套用至 E 中的任何目標。

產生的圖表會根據依附元件關係排序。 詳情請參閱「圖表順序」一節。

部分路徑
somepath(S1 + S2, E),一項可能的結果。
部分路徑
somepath(S1 + S2, E),這是另一個可能的結果。
所有路徑
allpaths(S1 + S2, 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_librarycc_binaryfookind("source file", deps(//foo)) 底下的規則目標 會評估遞移性關閉中的所有來源檔案集 指定 //foo 目標的依附元件

通常必須使用引號 pattern 引數 如果沒有,則許多規則運算式 (例如 source file.*_test) 不會被剖析器視為字詞。

比對 package group 時,結尾為 :all 可能不會產生任何結果。請改用 :all-targets

目標名稱篩選:篩選器

expr ::= filter(word, expr)

filter(pattern, input) 運算子會將篩選器套用至一組目標,並捨棄含有該條件的 標籤 (絕對格式) 與模式不符;該資料來源 會得出輸入內容的子集

第一個引數 pattern 是內含 規則運算式,勝過目標名稱。filter 運算式 會評估包含所有指定目標 x 的組合, xinput 集合的成員, 標籤 (以絕對格式,例如 //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,且 xinput 集合的成員是具有已定義 屬性 [name],而屬性值則包含 (未錨定) 比對規則運算式 pattern。如果 name 是 選擇性屬性和規則並未明確指定預設值 屬性值會用於比較。例如:

attr(linkshared, 0, deps(//foo))

將會選取所有 //foo 可存取的依附元件 連結共用屬性 (例如 cc_binary 規則) 並加上 明確設為 0 或完全不設定,但預設值為 0 (例如 cc_binary 規則)。

清單類型屬性 (例如 srcsdata 等) 並轉換為 [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」集內的規則 並套用篩選條件 tagsize

根據預設,查詢評估 會忽略所有 test_suite 規則中的任何非測試目標。可用的值包括 已變更為包含 --strict_test_suite 選項的錯誤

舉例來說,查詢 kind(test, foo:*) 會列出所有 *_testtest_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

rbuildfiles 運算子的範圍是指 --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 執行時,只會輸出與下列項目相容的格式: 系統會接受未排序的輸出內容。具體來說,graphminrank和 禁止使用 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 為其中一個標記時 buildlabellabel_kindlocationpackageprotoxml,系統會按照任意順序列印輸出內容。這是為了 (通常最快的選項)。但是在 --outputgraphminrankmaxrank:使用這些格式,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 仍在輸出中開始處理。

--output textproto

--output proto 類似,系統會輸出 QueryResult 通訊協定緩衝區 文字格式

--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 指令安裝這個套件)。 請參閱下方範例的叫用範例。

這個輸出格式特別適用於 allpathsdepsrdeps 查詢,結果 包含無法輕鬆繪製圖表的路徑組合 以線性格式算繪,例如使用 --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-inputrule-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