Args

回報問題 查看原始碼 Nightly · 7.4 . 7.3 · 7.2 · 7.1 · 7.0 · 6.5

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

動作經常需要大型指令列，其中包含從傳遞依附元件累積的值。舉例來說，連結器指令列可能會列出所有連結的程式庫所需的每個物件檔案。最佳做法是在 depset 中儲存這類傳遞資料，以便多個目標共用。不過，如果規則作者必須將這些 depset 轉換為字串清單，才能建構動作指令行，這就會破壞這項記憶體共用最佳化功能。

因此，除了字串之外，動作建構函式也接受 Args 物件。每個 Args 物件都代表字串和 depset 的串接，並提供可選轉換，用於操作資料。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 函式。

使用字串格式設定 (format、format_each 和 format_joined 參數的 add*() 方法) 時，系統會以與字串 % 替換相同的方式解讀格式範本，但範本必須有且僅有一個替換預留位置，且該預留位置必須為 %s。您可以使用 %% 逸出文字百分比。格式會在值轉換為字串後套用，如下所示。

每個 add*() 方法都有另一種形式，可接受額外的位址參數，也就是在其餘引數之前插入的「arg name」字串。如果序列為空白，add_all 和 add_joined 就不會新增額外字串。舉例來說，同樣的用法可將 --foo val1 val2 val3 --bar 或 --bar 新增至指令列，這取決於指定序列是否包含 val1..val3 或為空白。

如果指令列的大小會超過系統允許的最大大小，引數就會溢出至參數檔案。請參閱 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
• add_all
• add_joined
• set_param_file_format
• use_param_file

add

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

將引數附加至這個指令列。

參數

參數	說明
arg_name_or_value	required 如果傳遞兩個位置參數，系統會將這項資訊解讀為引數名稱。引數名稱會加在值之前，且不會經過任何處理。如果只傳遞一個位置參數，系統會將其解讀為 value (請參閱下方說明)。
value	預設為 unbound 要附加的物件。系統會使用上述的標準轉換格式，將該字串轉換為字串。由於此函式沒有 map_each 參數，value 應為字串或 File。清單、元組、depset 或目錄 File 必須傳遞至 add_all() 或 add_joined()，而非這個方法。
format	字串或 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)

將多個引數附加至這個指令列。項目會在執行階段延遲處理。

大部分的處理作業會在要附加的引數清單上進行，如下列步驟所示：

1. 每個目錄的 File 項目都會由該目錄以遞迴方式納入的所有 File 取代。
2. 如果提供 map_each，系統會將其套用至每個項目，並將產生的字串清單串連起來，形成初始引數清單。否則，初始引數清單是將標準轉換套用至每個項目的結果。
3. 清單中的每個引數都會以 format_each 格式化 (如有)。
4. 如果 uniquify 為 true，系統會移除重複的引數。系統會保留第一個出現的值。
5. 如果提供 before_each 字串，系統會將其插入清單中每個現有引數之前，做為新的引數。這實際上會將此處要附加的引數數量加倍。
6. 除了清單為空白且 omit_if_empty 為 true (預設值) 的情況外，如果有指定引數名稱和 terminate_with，系統會分別將這些引數插入為第一個和最後一個引數。

請注意，空白字串是需要執行所有處理步驟的有效引數。

參數

參數	說明
arg_name_or_values	required 如果傳遞兩個位置參數，系統會將這項資訊解讀為引數名稱。引數名稱會顯示在 values 之前，做為單獨的引數，不含任何處理。如果 omit_if_empty 為 true (預設值)，且未附加其他項目 (也就是 values 空白或所有項目都遭到篩除)，系統就不會新增這個引數名稱。如果只傳遞一個位置參數，系統會將其解讀為 values (請參閱下方說明)。
values	序列或depset；預設為 unbound 。 要附加項目的清單、元組或 depset。
map_each	可呼叫；或 None；預設值為 None 此函式可將各個項目轉換為零或多個字串，這些項目可能會在附加前進一步處理。如果未提供這個參數，系統會使用標準轉換。 系統會傳送一或兩個位置引數：要轉換的項目，後面加上選用的 DirectoryExpander。只有在提供的函式為使用者定義 (非內建) 且宣告多個參數時，才會傳遞第二個引數。 回傳值的類型取決於要為項目產生多少引數： 常見情況下，當每個項目變成一個字串時，函式應傳回該字串。 如果要完全篩除項目，函式應傳回 None。 如果項目轉換為多個字串，函式會傳回這些字串的清單。 傳回單一字串或 None 的效果，分別等同於傳回長度為 1 或 0 的清單。不過，這種做法會更有效率且易於閱讀，避免在非必要的情況下建立清單。 通常，當設定 expand_directories=True 時，目錄項目會自動展開至其內容。不過，這不會展開其他值內的目錄，例如項目是結構體，而目錄是欄位。在這種情況下，您可以套用 DirectoryExpander 引數，手動取得指定目錄的檔案。 為避免在執行階段中意外保留大量分析階段資料結構，map_each 函式必須透過頂層 def 陳述式宣告；根據預設，這可能不是巢狀函式結束。 警告：在呼叫 map_each 期間執行的 print() 陳述式不會產生任何可見的輸出內容。
format_each	字串或 None；預設為 None 。可選的格式字串模式，套用至 map_each 函式傳回的每個字串。格式字串只能有一個「%s」預留位置。
before_each	string；或 None；預設值為 None 在每個衍生自 values 的引數之前，要附加的選用引數。
omit_if_empty	預設為 True 如果為 true，如果沒有衍生自 values 的引數可附加，則會抑制所有後續處理作業，且命令列不會變更。如果為 false，則無論是否有其他引數，都會附加引數名稱和 terminate_with (如果提供)。
uniquify	預設為 False 如果為 true，系統會略過衍生自 values 的重複引數。系統只會保留每個引數的第一次出現。通常不需要這項功能，因為 depset 已略過重複項目，但如果 map_each 為多個項目傳出相同的字串，這項功能就很實用。
expand_directories	預設為 True 如果為 true，values 中的任何目錄都會展開為扁平的檔案清單。這會在套用 map_each 之前發生。
terminate_with	字串或 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	required 如果傳遞兩個位置參數，系統會將這項資訊解讀為引數名稱。且在 values 前方加入 arg 名稱，不經過任何處理。如果 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	字串或 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」：與「multiline」相同，但項目會加上殼層引號 「flag_per_line」：與「multiline」相同，但 (1) 只有標記 (開頭為「--」) 會寫入 param 檔案，且 (2) 標記的值 (如有) 會寫入同一行，並以「=」分隔。這是 Abseil 旗標程式庫預期的格式。 如果未呼叫，格式預設為「shell」。

use_param_file

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

將引數溢位至參數檔案，並以指向參數檔案的指標取代引數。當引數可能超過系統指令長度限制時，請使用 。

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

參數

參數	說明
param_file_arg	必要 "%s" 格式字串。如果引數溢出至參數檔案，則會替換為引數，該引數包含以參數檔案路徑格式化的字串。 舉例來說，如果引數會溢出至參數檔案「params.txt」，指定「--file=%s」會導致動作指令列包含「--file=params.txt」。
use_always	預設值為 False 是否一律將引數排到參數檔案。如果為 false，bazel 會根據系統和 arg 長度決定是否需要溢出引數。