Args

以節省記憶體的方式封裝物件，建構部分或所有指令列所需的資料。

通常會發生動作需要大型指令列，其中含有從遞移依附元件累積的值。例如，連結器指令列可能會列出所有連結程式庫所需的每個物件檔案。最佳做法是將這類遞移資料儲存在 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

# 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_all
• add_joined
• set_param_file_format
• use_param_file

add

Args Args.add(arg_name_or_value, value=unbound, *, format=None)

參數

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)

處理程序大多會透過附加的引數清單進行，如以下步驟所示：

1. 每個目錄的 File 項目都會由該目錄以遞迴方式納入的所有 File 取代。
2. 如果指定 map_each，就會套用至每個項目，而產生的字串清單會串連起來，以形成初始引數清單。否則，初始引數清單是為每個項目套用標準轉換的結果。
3. 清單中的每個引數都會採用 format_each 的格式 (如果有的話)。
4. 如果 uniquify 為 true，則會移除重複的引數。第一段是剩下的
5. 如果指定了 before_each 字串，系統會將該字串以新引數的形式插入清單中的每個現有引數。這會有效使這個點附加的引數數量增加了一倍。
6. 除了清單為空白且 omit_if_empty 為 true (預設值) 的情況下，系統會在有指定引數時，分別插入引數名稱和 terminate_with 做為第一個和最後一個引數。

參數

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，則聯結字串將會是空字串。

參數

set_param_file_format

Args Args.set_param_file_format(format)

參數

use_param_file

Args Args.use_param_file(param_file_arg, *, use_always=False)

Bazel 可能會選擇盡量減少在執行期間將參數檔案寫入輸出樹狀結構，藉此提高效率。如果您要對動作進行偵錯，並想檢查參數檔案，請將 --materialize_param_files 傳遞至建構作業。

參數