以節省記憶體的方式封裝物件,建構部分或所有指令列所需的資料。
通常會發生動作需要大型指令列,其中含有從遞移依附元件累積的值。例如,連結器指令列可能會列出所有連結程式庫所需的每個物件檔案。最佳做法是將這類遞移資料儲存在 depset
中,以便多個目標共用。不過,如果規則作者必須將這些解碼集轉換為字串清單,才能建構動作指令列,就會使這項記憶體共用最佳化作業失效。
因此,除了字串外,動作建構函式也接受 Args
物件。每個 Args
物件都代表字串與解碼集的串連,並可選擇用於操控資料的選用轉換。在計算指令列時,Args
物件不會處理其封裝到執行階段之前封裝的 DepSet。這有助於將任何昂貴的複製作業延後,直到分析階段結束為止。詳情請參閱最佳化成效頁面。
呼叫 ctx.actions.args()
即可建構 Args
。可做為 ctx.actions.run()
或 ctx.actions.run_shell()
的 arguments
參數傳遞。每項 Args
物件的異動事件都會在最終指令列中附加值。
map_each
功能可讓您自訂項目轉換為字串的方式。如未提供 map_each
函式,標準轉換會如下所示:
- 已經是字串的值會保持原樣。
File
物件會轉換為其File.path
值。Label
物件會轉換為字串表示法,在主要存放區的內容中解析後,就會解析為同一個物件。如果可以,字串表示法會使用存放區的顯著名稱,取而代之的是存放區的正式名稱,因此這種表示法相當適合 BUILD 檔案使用。雖然無法保證實際呈現方式,但一般範例為//foo:bar
、@repo//foo:bar
和@@canonical_name~//foo:bar.bzl
。- 所有其他類型都會以未指定的方式轉換為字串。因此,請避免將非字串或
File
類型的值傳遞至add()
,如果您將其傳遞至add_all()
或add_joined()
,則應提供map_each
函式。
使用字串格式 (add*()
方法的 format
、format_each
和 format_joined
參數) 時,格式範本的解讀方式與字串上的 %
替代方式相同,但範本只能有一個替換預留位置,且必須為 %s
。常值百分比可以逸出為 %%
。系統會依照上述方法,在值轉換為字串後套用格式設定。
每個 add*()
方法都有其替代形式,可接受額外的位置參數「引數名稱」字串,插入其餘引數前方。針對 add_all
和 add_joined
,如果序列變成空白,將不會新增額外的字串。舉例來說,視指定序列包含 val1..val3
或為空白而定,相同的使用方式可在指令列中新增 --foo val1 val2 val3 --bar
或 --bar
。
如果指令列的大小可超過系統允許的大小上限,則可將引數溢出至參數檔案中。請查看 use_param_file()
和 set_param_file_format()
。
範例:假設我們想產生指令列:
--foo foo1.txt foo2.txt ... fooN.txt --bar bar1.txt,bar2.txt,...,barM.txt --baz
Args
物件:# foo_deps and bar_deps are depsets containing # File objects for the foo and bar .txt files. args = ctx.actions.args() args.add_all("--foo", foo_deps) args.add_joined("--bar", bar_deps, join_with=",") args.add("--baz") ctx.actions.run( ... arguments = [args], ... )
成員
add
Args Args.add(arg_name_or_value, value=unbound, *, format=None)
參數
參數 | 說明 |
---|---|
arg_name_or_value
|
必要 如果傳遞兩個位置參數,系統會將其解讀為引數名稱。引數名稱會加在值之前,且不會經過任何處理。如果只傳遞一個位置參數,系統會將其視為 value (詳見下文)。
|
value
|
預設值為 unbound 要附加的物件。系統會使用上述的標準轉換格式,將該字串轉換為字串。這個函式沒有 map_each 參數,因此 value 應該是字串或 File 。清單、元組、Depset 或目錄 File 必須傳遞至 add_all() 或 add_joined() ,而非此方法。
|
format
|
string;或 None ;
預設值為 None 要套用至 value 字串化版本的格式字串模式。
|
add_all
Args Args.add_all(arg_name_or_values, values=unbound, *, map_each=None, format_each=None, before_each=None, omit_if_empty=True, uniquify=False, expand_directories=True, terminate_with=None, allow_closure=False)
處理程序大多會透過附加的引數清單進行,如以下步驟所示:
- 每個目錄的
File
項目都會由該目錄以遞迴方式納入的所有File
取代。 - 如果指定
map_each
,就會套用至每個項目,而產生的字串清單會串連起來,以形成初始引數清單。否則,初始引數清單是為每個項目套用標準轉換的結果。 - 清單中的每個引數都會採用
format_each
的格式 (如果有的話)。 - 如果
uniquify
為 true,則會移除重複的引數。第一段是剩下的 - 如果指定了
before_each
字串,系統會將該字串以新引數的形式插入清單中的每個現有引數。這會有效使這個點附加的引數數量增加了一倍。 - 除了清單為空白且
omit_if_empty
為 true (預設值) 的情況下,系統會在有指定引數時,分別插入引數名稱和terminate_with
做為第一個和最後一個引數。
參數
參數 | 說明 |
---|---|
arg_name_or_values
|
必要 如果傳遞兩個位置參數,系統會將其解讀為引數名稱。引數名稱會在 values 之前新增為單獨的引數,且未進行任何處理。如果 omit_if_empty 為 true (預設值),且未附加其他項目 (也就是 values 空白或所有項目都遭到篩除),系統就不會新增這個引數名稱。如果只傳遞一個位置參數,系統會將其視為 values (詳見下文)。
|
values
|
sequence;或 depset;
預設值為 unbound 要附加其項目的清單、元組或解碼集。 |
map_each
|
可呼叫;或 None ;
預設值為 None 可將每個項目轉換為零或多個字串的函式。系統會在附加前進一步處理。如未提供這個參數,系統會使用標準轉換。 系統會傳送一或兩個位置引數:要轉換的項目,後面加上選用的 傳回值的類型取決於需要為項目產生的引數數量:
None ,效果等同於傳回長度為 1 或長度 0 的清單。不過,這種做法會更有效率且易於閱讀,避免在非必要的情況下建立清單。一般來說,如果設定了 為避免在執行階段中意外保留大型分析階段資料結構,必須透過頂層 警告:在呼叫 |
format_each
|
string;或 None ;
預設值為 None 選用的格式字串模式,套用至 map_each 函式傳回的每個字串。格式字串只能有一個「%s」預留位置。
|
before_each
|
string;或 None ;
預設值為 None 每個衍生自 values 的引數之前,都會附加選用的引數。
|
omit_if_empty
|
預設值為 True 如為 true,如果沒有要附加 values 衍生的引數,系統會抑制所有後續處理作業,並變更指令列。如果是 False,則無論是否有其他引數,仍會附加引數名稱和 terminate_with (如有)。
|
uniquify
|
預設值為 False 如果設為 true,系統會省略衍生自 values 的重複引數。系統只會保留每個引數的第一個出現引數。由於 depsets 已省略重複項目,因此通常不需要這項功能,但如果 map_each 對多個項目發出同一個字串,將能派上用場。
|
expand_directories
|
預設值為 True 如為 true, values 中的任何目錄都會展開為平面檔案清單。這項作業會在套用 map_each 前執行。
|
terminate_with
|
string;或 None ;
預設值為 None 視需要在所有其他引數之後附加的選用引數。如果 omit_if_empty 為 true (預設值),且未附加其他項目,就不會新增這個引數 (例如 values 空白或所有項目都遭到篩除)。
|
allow_closure
|
預設值為 False 如果設為 true,系統會允許在函式參數 (例如 map_each ) 中使用閉包。一般來說,這並非必要,而且可能會導致在執行階段保留大量的分析階段資料結構。
|
add_joined
Args Args.add_joined(arg_name_or_values, values=unbound, *, join_with, map_each=None, format_each=None, format_joined=None, omit_if_empty=True, uniquify=False, expand_directories=True, allow_closure=False)
處理方式與 add_all()
類似,但從 values
衍生的引數清單會合併為單一引數,就像由 join_with.join(...)
一樣,然後使用指定的 format_joined
字串範本格式化。與 add_all()
不同,由於項目合併為單一引數時,這類參數通常沒有幫助,因此沒有 before_each
或 terminate_with
參數。
篩選之後,如果沒有可聯結到引數的字串,且 omit_if_empty
為 true (預設值),則系統不會處理任何處理作業。如果沒有要彙整的字串,但 omit_if_empty
為 false,則聯結字串將會是空字串。
參數
參數 | 說明 |
---|---|
arg_name_or_values
|
必要 如果傳遞兩個位置參數,系統會將其解讀為引數名稱。引數名稱是在 values 之前新增,沒有任何處理。如果 omit_if_empty 為 true (預設值),且沒有從 values 彙整的任何字串 (如果 values 為空白或所有項目都遭到篩除,系統就不會新增此引數)。如果只傳遞一個位置參數,系統會將其視為 values (詳見下文)。
|
values
|
sequence;或 depset;
預設值為 unbound 要彙整其項目的清單、元組或 depset。 |
join_with
|
必要 用於彙整從套用 map_each 和 format_each 取得的字串的分隔符號字串,與 string.join() 的方式相同。
|
map_each
|
可呼叫;或 None ;
預設值為 None 與 add_all 相同。
|
format_each
|
string;或 None ;
預設值為 None 與 add_all 相同。
|
format_joined
|
string;或 None ;
預設值為 None 套用至已彙整字串的選用格式字串模式。格式字串只能有一個「%s」預留位置。 |
omit_if_empty
|
預設值為 True 如果設為 true,如果沒有要合併的字串 (因為 values 空白或所有項目都經過篩選),系統將停止後續處理作業,且指令列會保持不變。如果設為 false,則沒有可以彙整的字串,仍會加上兩個引數:引數名稱後接空字串 (零字串的邏輯彙整)。
|
uniquify
|
預設值為 False 與 add_all 相同。
|
expand_directories
|
預設值為 True 與 add_all 相同。
|
allow_closure
|
預設值為 False 與 add_all 相同。
|
set_param_file_format
Args Args.set_param_file_format(format)
參數
參數 | 說明 |
---|---|
format
|
必要 必須是下列其中一個:
格式預設為「shell」如未呼叫。 |
use_param_file
Args Args.use_param_file(param_file_arg, *, use_always=False)
Bazel 可能會選擇盡量減少在執行期間將參數檔案寫入輸出樹狀結構,藉此提高效率。如果您要對動作進行偵錯,並想檢查參數檔案,請將 --materialize_param_files
傳遞至建構作業。
參數
參數 | 說明 |
---|---|
param_file_arg
|
必要 包含單一「%s」的格式字串。如果引數溢出至參數檔案,系統會將引數替換成由這個字串 (採用參數檔案路徑格式) 組成的引數。 舉例來說,如果引數會放在參數檔案「params.txt」,請指定「--file=%s」會導致動作指令列包含「--file=params.txt」。 |
use_always
|
預設值為 False 是否一律將引數傳遞至參數檔案。設為 false 時,bazel 會根據系統和引數長度決定是否需要將引數排出。 |