動作往往需要大型指令列,其中含有從遞移依附元件累積的值。例如,連結器指令列可能會列出連結的所有程式庫所需的每個物件檔案。建議您將這類轉換資料儲存在 depset
,以便多個目標共用。不過,如果規則作者必須將這些解碼器轉換為字串清單,以建立動作指令列,便會導致這項記憶體共用最佳化作業失敗。
因此,動作建構函式除了接受字串之外,也接受 Args
物件。每個 Args
物件都代表字串和字串的串連,並提供可操控資料的選用轉換。在執行階段計算指令列時,Args
物件不會處理其封裝的解碼器。這會將任何昂貴的複製作業延後到分析階段結束為止。詳情請參閱最佳化效能頁面。
Args
是透過呼叫 ctx.actions.args()
所建構。這些參數可做為 ctx.actions.run()
或 ctx.actions.run_shell()
的 arguments
參數傳遞。Args
物件的每個異動都會將值附加到最終指令列。
map_each
功能可讓您自訂項目轉換為字串的方式。如未提供 map_each
函式,標準轉換如下:
- 已經包含字串的值會維持不變。
- 系統會將
File
物件轉換成File.path
值。 - 所有其他類型的類型都會以未指定的方式轉換成字串。因此,您應避免將不屬於字串或
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
|
default = unbound 要附加的物件。系統會按照上述的標準轉換,轉換為字串。由於這個函式沒有 map_each 參數,因此 value 應為字串或 File 。清單、元組、解碼器或目錄 File 必須傳遞至 add_all() 或 add_joined() ,而不是這個方法。 |
format
|
string; or None ;
default = 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; or depset ;
default = unbound要附加其項目的清單、元組或解碼器。 |
map_each
|
callable; or None ;
default = None這個函式會將每個項目轉換為零或多個字串,附加作業可進一步處理完畢。如果未提供這個參數,則會使用標準轉換。 系統會傳遞一或兩個位置引數:要轉換的項目,後面接著選用的 傳回值的類型取決於項目產生的引數數量:
None 的效果與分別傳回長度為 1 或長度 0 的清單相同。但是,這樣更有效率且易於讀取,避免在不需要建立清單時建立。一般而言,設定 為了避免在執行階段中意外保留大型分析階段資料結構, 警告:呼叫 |
format_each
|
string; or None ;
default = None這是選用的格式字串模式,會套用至 map_each 函式傳回的每個字串。格式字串只能有一個「%s」預留位置。 |
before_each
|
string; or None ;
default = None在從 values 衍生的每個引數之前附加的選用字串。
|
omit_if_empty
|
default = True 如果為 true,則不會附加從 values 衍生的引數,所有進一步的處理作業都會遭到禁止,指令列將維持不變。如果設為 false,無論是否有其他引數,系統仍會附加引數名稱和 terminate_with (如有提供)。 |
uniquify
|
default = False 如果為 true,系統會省略 values 衍生的重複引數。系統只會保留每個引數的第一個出現記錄。一般而言,由於依附元件已省略重複項目,因此不需要這項功能。不過,如果 map_each 為多個項目發出相同的字串,這項功能就能派上用場。
|
expand_directories
|
default = True 如果為 true, values 中的所有目錄都會展開為一般檔案清單。這會在套用 map_each 前發生。 |
terminate_with
|
string; or None ;
default = None選擇性附加在所有其他引數後方的字串。如果 omit_if_empty 為 true (預設),且未附加其他項目 (例如 values 空白或其中所有項目都遭到篩除),系統就不會新增這個字串。 |
allow_closure
|
default = 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; or depset ;
default = unbound用來彙整所含項目的清單、元組或分隔符號。 |
join_with
|
必要 分隔字串,用於結合套用 map_each 和 format_each 所取得的字串,做法與 string.join() 相同。 |
map_each
|
callable; or None ;預設值 = 無與 add_all 相同。
|
format_each
|
string; or None ;預設值 = 無與 add_all 相同。
|
format_joined
|
string; or None ;
default = None選用格式字串模式,已套用至彙整的字串。格式字串只能有一個「%s」預留位置。 |
omit_if_empty
|
default = True 如果沒有可結合的字串 (因為 values 空白或當中所有項目都經過篩選),則系統會略過所有進一步的處理程序,指令列將維持不變。如果為 false,則即使沒有可彙整的字串,系統還是會附加兩個引數:引數名稱後面接著空字串 (這是零字串的邏輯彙整)。
|
uniquify
|
default = False 與 add_all 相同。
|
expand_directories
|
default = True 與 add_all 相同。
|
allow_closure
|
default = 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
|
default = False 是否一律將引數傳遞至參數檔案。如果設為 false,bazel 將根據系統和引數長度判斷引數是否需要散佈。 |