依附元件

7.3 · 7.2 · 7.1 · 7.0 · 6.5

如果 A 在建構或執行期間需要 B,目標 A 就會依附目標 Bdepends upon 關係會在目標上誘導有向非循環圖 (DAG),稱為依附元件圖

目標的「直接」依附元件是指在依附元件圖中透過長度為 1 的路徑可到達的其他目標。目標的「轉換」依附元件是指透過圖形中任意長度的路徑所依據的目標。

事實上,在建構作業的背景下,有兩個依附元件圖表,分別是實際依附元件的圖表,以及已宣告依附元件的圖表。在大多數情況下,這兩種圖表都十分相似,因此不必做出這項區別,不過在下文討論時相當實用。

實際和宣告的依附元件

只有在 Y 必須存在、建構及處於最新狀態,才能正確建構 X 時,目標 X 就「實際依賴」目標 Y。「已建構」可能代表產生、處理、編譯、連結、封存、壓縮、執行或任何其他在建構期間經常發生的工作。

如果 X 套件中的依附元件範圍從 XY,目標 X 就會具有目標 Y宣告依附元件

如要正確建構,實際依附元件 A 的圖表必須是宣告依附元件 D 圖表的子圖表。也就是說,A 中的每對直接連結節點 x --> y 也必須直接在 D 中連結。儘管 DA高估值,

BUILD 檔案寫入者必須針對建構系統中的每項規則明確宣告所有實際直接依附元件,除此之外也不例外。

若未觀察到這項原則,會導致未定義的行為:建構作業可能會失敗,但更糟的是,建構作業可能會依賴先前的某些作業,或者目標有遞移宣告的依附元件。Bazel 會檢查缺少的依附元件並回報錯誤,但無法在所有情況下完成這項檢查。

您不必 (也無須) 嘗試列出所有間接匯入的項目,即使 A 在執行期間需要也一樣。

在建構目標 X 的過程中,建構工具會檢查 X 依附元件的整個傳遞閉環,確保這些目標的任何變更都會反映在最終結果中,並視需要重新建構中介層。

依附元件的遞移性質會導致常見錯誤。有時,某個檔案中的程式碼可能會使用間接依附元件提供的程式碼,也就是在已宣告依附元件圖表中為傳遞而非直接邊緣。間接依附元件不會顯示在 BUILD 檔案中。由於規則不會直接依附供應器,因此您無法追蹤變更,如以下時間軸範例時間軸所示:

1. 宣告的依附元件與實際依附元件相符

首先是一切都能正常運作套件 a 中的程式碼使用套件 b 中的程式碼。套件 b 中的程式碼使用套件 c 中的程式碼,因此 a 間接依賴 c

a/BUILD b/BUILD
rule(
    name = "a",
    srcs = "a.in",
    deps = "//b:b",
)
      
rule(
    name = "b",
    srcs = "b.in",
    deps = "//c:c",
)
      
a / a.in b / b.in
import b;
b.foo();
    
import c;
function foo() {
  c.bar();
}
      
已宣告的依附元件圖,內含連接 a、b 和 c 的箭頭
已宣告依附元件圖表
與宣告的依附元件圖相符的實際依附元件圖,箭頭連結 a、b 和 c
「實際」依附元件圖

宣告的依附元件高於實際依附元件。一切都很好。

2. 新增未宣告的依附元件

如果有人在 a 中加入程式碼,並在 c 上建立直接的「實際」依附元件,但忘記在建構檔案 a/BUILD 中宣告,就會引發潛在危險。

a / a.in  
        import b;
        import c;
        b.foo();
        c.garply();
      
 
已宣告的依附元件圖,內含連接 a、b 和 c 的箭頭
已宣告的依附元件圖表
實際依附元件圖表,箭頭連結 a、b 和 c。箭頭現在也會將 A 連結至 C。這與宣告的依附元件圖表不符
實際依附元件圖表

宣告的依附元件不再過度近似實際依附元件。這可能會建構正常,因為兩個圖表的傳遞閉包相等,但會掩蓋一個問題:ac 有實際但未宣告的依附元件。

3. 宣告的依附元件與實際依附元件圖表之間的差異

當有人重構 b 以便不再依賴 c,而無意中斷 a,就會揭露此種危險。

  b/BUILD
 
rule(
    name = "b",
    srcs = "b.in",
    deps = "//d:d",
)
      
  b / b.in
 
      import d;
      function foo() {
        d.baz();
      }
      
已宣告的依附元件圖表,內含連接 a 和 b 的箭頭。b 不再連線至 c,因此 a 與 c 的連線中斷
已宣告依附元件圖表
實際依附元件圖,顯示連結至 b 和 c,但 b 不再連線至 c
實際依附元件圖表

所宣告依附元件圖表現在是實際依附元件的近似值,即使間接關閉也一樣;建構可能會失敗。

您可以透過確保在步驟 2 中引入的 ac 的實際依附元件已在 BUILD 檔案中正確宣告,來避免這個問題。

依附元件類型

大多數的建構規則都有三個屬性,可用來指定不同類型的一般依附元件:srcsdepsdata。說明如下:詳情請參閱「所有規則的共同屬性」。

許多規則也有其他屬性,用於規則專屬的依附元件類型,例如 compilerresources。詳情請參閱「建構百科全書」。

srcs 項依附元件

直接由輸出來源檔案的規則或規則使用的檔案。

deps 項依附元件

指向單獨編譯模組的規則,提供標頭檔案、符號、程式庫、資料等。

data 依附元件

建構目標可能需要一些資料檔案才能正確執行。這些資料檔案並非原始碼,不會影響目標的建構方式。舉例來說,單元測試可能會將函式的輸出內容與檔案內容進行比較。建構單元測試時不需要這個檔案,但執行測試時就需要。同樣的原則也適用於執行期間啟動的工具。

建構系統會在獨立目錄中執行測試,其中僅有列為 data 的檔案可用。因此,如果二進位檔/程式庫/測試需要執行某些檔案,請在 data 中指定這些檔案 (或包含這些檔案的建構規則)。例如:

# I need a config file from a directory named env:
java_binary(
    name = "setenv",
    ...
    data = [":env/default_env.txt"],
)

# I need test data from another directory
sh_test(
    name = "regtest",
    srcs = ["regtest.sh"],
    data = [
        "//data:file1.txt",
        "//data:file2.txt",
        ...
    ],
)

這些檔案可透過相對路徑 path/to/data/file 取得。在測試中,您可以彙整測試來源目錄的路徑和工作區相對於路徑 (例如 ${TEST_SRCDIR}/workspace/path/to/data/file),藉此參照這些檔案。

使用標籤參照目錄

查看 BUILD 檔案時,可能會發現有些 data 標籤參照目錄。這些標籤結尾是 /./,如下所示:

不建議使用data = ["//data/regression:unittest/."]

不建議使用 - data = ["testdata/."]

不建議使用data = ["testdata/"]

這看起來很方便,特別是用於測試,因為允許測試使用目錄中的所有資料檔案。

但請盡量避免這麼做。為確保變更後能正確地重新建構及重新執行測試,建構系統必須瞭解是建構 (或測試) 輸入的完整檔案組合。指定目錄後,建構系統只會在目錄本身變更 (因新增或刪除檔案) 時執行重建作業,但無法偵測個別檔案的編輯內容,因為這些變更不會影響包含的目錄。請不要將目錄指定為建構系統的輸入內容,而是應列舉其中包含的檔案集,方法是明確指定或使用 glob() 函式。(使用 ** 即可強制 glob() 變成遞迴)。

建議data = glob(["testdata/**"])

不過,在某些情況下,您必須使用目錄標籤。舉例來說,如果 testdata 目錄包含檔案,且檔案名稱不符合標籤語法,則明確列舉檔案,或使用 glob() 函式,就會產生無效標籤錯誤。在此情況下,您必須使用目錄標籤。不過要注意上述錯誤重新建構可能帶來的相關風險。

如果您必須使用目錄標籤,請注意,您無法使用相對 ../ 路徑參照父項套件,請改用 //data/regression:unittest/. 等絕對路徑。

需要使用多個檔案的任何外部規則 (例如測試),都必須明確宣告所有規則的依附性。您可以使用 filegroup()BUILD 檔案中將檔案分組:

filegroup(
        name = 'my_data',
        srcs = glob(['my_unittest_data/*'])
)

接著,您可以將標籤 my_data 做為測試中的資料依附元件。

BUILD 檔案 瀏覽權限