動作

回報問題 查看來源 Nightly

提供用於建立動作的模組。使用 ctx.actions 存取這個模組。

成員

• args
• declare_directory
• declare_file
• declare_symlink
• do_nothing
• expand_template
• run
• run_shell
• symlink
• template_dict
• write

args

Args actions.args()

傳回可用來建構記憶體效率指令列的 Args 物件。

declare_directory

File actions.declare_directory(filename, *, sibling=None)

宣告規則或切面會在目前的套件中，以指定的名稱建立目錄。您必須建立可產生目錄的動作。無法直接從 Starlark 存取目錄的內容，但是可以在動作指令中使用 Args.add_all() 來展開內容。只有一般檔案和目錄可位於 dec_directory 的展開內容中。

參數

參數	說明
filename	string; required 如未提供「sibling」，代表新目錄的路徑 (相對於目前套件)。否則為檔案的基礎名稱 (「ibling」定義了目錄)。
sibling	File；或 None；預設值為 None 。檔案與新宣告的目錄位於相同目錄中。該檔案必須位於目前的套件中。

declare_file

File actions.declare_file(filename, *, sibling=None)

宣告規則或切面建立具有指定檔案名稱的檔案。如果未指定 sibling，則檔案名稱與套件目錄相對關係，否則檔案會與 sibling 位於相同的目錄中。無法在目前套件以外的地方建立檔案。

請注意，除了宣告檔案外，您也必須個別建立會發送檔案的動作。建立該動作時，必須將傳回的 File 物件傳遞至動作的建構函式。

請注意，您不需要使用這個函式來宣告預先宣告的輸出檔案。您可以改為從 ctx.outputs 取得其 File 物件。查看使用範例。

參數

參數	說明
filename	string; required 如果沒有提供「sibling」，表示新檔案的路徑 (相對於目前套件)。否則，檔案的基本名稱 (「ibling」會決定目錄)。
sibling	File；或 None；預設值為 None 。這是指與新建檔案位於相同目錄中的檔案。該檔案必須位於目前的套件中。

declare_symlink

File actions.declare_symlink(filename, *, sibling=None)

宣告該規則或切面將在目前套件中建立具有指定名稱的符號連結。您必須建立會產生此符號連結的動作。Bazel 絕對不會解除參照這個符號連結，而是會完整地轉移至沙箱或遠端執行程式。目前不支援樹狀結構構件中的符號連結。

參數

參數	說明
filename	string; required 如未提供「sibling」，表示新符號連結的路徑 (相對於目前套件)。否則為檔案的基礎名稱 (「ibling」定義了目錄)。
sibling	File；或 None；預設值為 None 。檔案與新宣告的符號連結位於相同目錄中。

do_nothing

None actions.do_nothing(mnemonic, inputs=[])

建立空白動作，既不會執行指令，也不會產生任何輸出內容，但這對於插入「額外動作」很有幫助。

參數

參數	說明
mnemonic	string; required 單字的動作說明，例如 CppCompile 或 GoLink。
inputs	File 的 sequence；或 depset；預設為 [] 動作的輸入檔案清單。

expand_template

None actions.expand_template(template, output, substitutions={}, is_executable=False, computed_substitutions=unbound)

建立範本擴展動作。執行動作時，系統會根據範本產生檔案。系統會按照指定替代項目的順序，使用 substitutions 字典取代範本的部分部分。每當範本中顯示字典鍵 (或先前的替代結果) 時，就會將其替換為相關聯的值。金鑰沒有任何特殊語法。舉例來說，您可以使用大括號來避免衝突 (例如 {KEY})。查看使用範例。

參數

參數	說明
template	檔案；必要 範本檔案為 UTF-8 編碼的文字檔案。
output	檔案；必要 輸出檔案為 UTF-8 編碼的文字檔。
substitutions	dict；預設值為 {} 在展開範本時替代替代項目。
is_executable	bool；預設為 False 輸出檔案是否應執行。
computed_substitutions	TemplateDict； 預設值為 unbound 在展開範本時建立的替代項目。

run

None actions.run(outputs, inputs=[], unused_inputs_list=None, executable, tools=unbound, arguments=[], mnemonic=None, progress_message=None, use_default_shell_env=False, env=None, execution_requirements=None, input_manifests=None, exec_group=None, shadowed_action=None, resource_set=None, toolchain=unbound)

建立可執行執行檔的動作。查看使用範例。

參數

參數	說明
outputs	「File」的 sequence；必要 動作的輸出檔案清單。
inputs	File 的 sequence；或 depset；預設為 [] 動作的輸入檔案清單或解碼集。
unused_inputs_list	File；或 None；預設值為 None ，其中包含動作未使用的輸入清單。 這個檔案的內容 (通常是動作的輸出內容之一) 會對應至整個動作執行期間未使用的輸入檔案清單。這些檔案中的任何變更，都不會影響動作的輸出。
executable	File；或 string；或 FilesToRunProvider；必要 動作要呼叫的可執行檔案。
tools	sequence；或 depset；預設為 unbound 列出或取消設定動作所需的任何工具。工具是包含額外執行檔案的輸入資料，系統會自動提供給動作使用。提供清單時，可能會構成異質的 Files、FileToRunProvider 例項或 Files 的 Depset。如果檔案也列在清單中，且來自 ctx.executable 檔案，系統就會自動新增其執行檔。如果提供 Depset，則其中只能含有 Files，在這兩種情況下， depset 中的檔案都不會與 ctx.executable 交叉參照執行檔案。
arguments	sequence；預設值為 [] ，動作的指令列引數。必須是字串或 actions.args() 物件的清單。
mnemonic	string；或 None；預設值為 None 單字的動作說明，例如 CppCompile 或 GoLink。
progress_message	string; 或 None；預設值為 None 在建構期間向使用者顯示的進度訊息，例如「Compiling foo.cc to create foo.o」。訊息可能包含 %{label}、%{input} 或 %{output} 模式，這些模式會分別替換成標籤字串、首次輸入或輸出的路徑。偏好使用模式而非靜態字串，因為前者的效率較高。
use_default_shell_env	bool；預設值為 False 動作是否應使用預設殼層環境，其中包含幾個 OS 變數和透過 --action_env 設定的變數。 如果 use_default_shell_env 和 env 都設為 True，在啟用 --incompatible_merge_fixed_and_default_shell_env 的情況下，env 中設定的值會覆寫預設殼層環境 (預設)。如未啟用這個標記，系統會忽略 env。
env	dict；或 None；預設為 None 設定環境變數的字典。 如果 use_default_shell_env 和 env 都設為 True，在啟用 --incompatible_merge_fixed_and_default_shell_env 的情況下，env 中設定的值會覆寫預設殼層環境 (預設)。如未啟用這個標記，系統會忽略 env。
execution_requirements	dict；或 None； 預設值為 None 用於排程動作的資訊。如需實用索引鍵的標記，請參閱標記。
input_manifests	sequence 或 None；預設值為 None 舊版引數。忽略。
exec_group	string；或 None；預設值為 None 在指定的執行群組的執行平台上執行動作。如果沒有，則會使用目標的預設執行平台。
shadowed_action	動作；預設為 None 使用新增至動作的輸入清單和環境的特定遭覆蓋動作的輸入內容和環境，執行此動作。動作環境可以覆寫任何覆蓋動作的環境變數。如果沒有，則只會使用動作的輸入內容和給定環境。
resource_set	可呼叫；或 None；預設值為 None 這個回呼函式會傳回資源集字典，用於在本機執行這個動作時預估在執行時間的資源用量。 這個函式接受兩個位置引數：一個代表 OS 名稱的字串 (例如「osx」)，以及一個整數，代表該動作的輸入項目數量。傳回的字典可能包含下列項目，而每個項目可能為浮點值或 int： "cpu"：CPU 數量；預設值為 1 「memory」：MB；預設值為 250 「local_test」：本機測試數量；預設值為 1 如果此參數設為 None，或 --experimental_action_resource_set 為 false，則會使用預設值。 回呼必須是頂層 (不允許 lambda 和巢狀函式)。
toolchain	Label；或 string; 或 None；預設值為 unbound 此動作所用執行檔或工具的工具鍊類型。 如果可執行檔和工具並非來自工具鍊，請將此參數設為 `None`。 如果執行檔和工具來自工具鍊，就必須設定工具鍊類型，讓動作在正確的執行平台上執行。 請注意，建立這個動作的規則必須在其「rule()」函式中定義這個工具鍊。 如果同時設定 `toolchain` 和 `exec_group` 參數，則會使用 `exec_group`。如果 `exec_group` 未指定相同工具鍊，就會發生錯誤。

run_shell

None actions.run_shell(outputs, inputs=[], tools=unbound, arguments=[], mnemonic=None, command, progress_message=None, use_default_shell_env=False, env=None, execution_requirements=None, input_manifests=None, exec_group=None, shadowed_action=None, resource_set=None, toolchain=unbound)

建立會執行殼層指令的動作。查看使用範例。

參數

參數	說明
outputs	「File」的 sequence；必要 動作的輸出檔案清單。
inputs	File 的 sequence；或 depset；預設為 [] 動作的輸入檔案清單或解碼集。
tools	File 的 sequence；depset；預設為 unbound 列出執行動作所需的任何工具或解碼器。工具是包含額外執行檔案的輸入資料，系統會自動提供給動作使用。清單中可包含 Files 或 FilesToRunProvider 執行個體。
arguments	sequence；預設值為 [] ，動作的指令列引數。必須是字串或 actions.args() 物件的清單。 Bazel 會將這個屬性中的元素做為引數傳送至指令。此指令可以使用殼層變數替代機制 (例如 $1、$2 等) 來存取這些引數。請注意，由於 Args 物件會在建立索引之前以扁平化，因此如果存在大小不明的 Args 物件，所有後續字串都會在無法預測的索引範圍內。將 $@ (擷取所有引數) 與不確定大小的 Args 物件搭配使用，可能會有所幫助。 如果 command 是字串清單，就不能使用這個參數。
mnemonic	string；或 None；預設值為 None 單字的動作說明，例如 CppCompile 或 GoLink。
command	string; 或 string 的 sequence；必要 要執行的殼層指令。該字串可以是字串 (建議) 或一系列字串 (已淘汰)。 如果 command 是字串，則會以 sh -c <command> "" <arguments> 的形式執行；也就是說，arguments 中的元素會以 $1、$2 (或 %1，如使用 Windows 批次) 等形式提供給指令使用。如果 arguments 包含任何 actions.args() 物件，其內容會逐一附加至指令列中，因此 $i 可以參照 Args 物件中的個別字串。%2請注意，如果不明大小的 Args 物件作為 arguments 的一部分傳遞，字串將出現未知的索引。在此情況下，建議改用 $@ 殼層替代 (擷取所有引數)。 (已淘汰) 如果 command 是字串序列，第一個項目是執行的執行檔，而其餘項目則是其引數。如果使用這份表單，請勿提供 arguments 參數。請注意，這份表單已淘汰，即將移除。這個項目已由「--incompatible_run_shell_command_string」停用。請使用此標記來驗證程式碼是否相容。 Bazel 會使用與 genrules 相同的殼層來執行指令。
progress_message	string; 或 None；預設值為 None 在建構期間向使用者顯示的進度訊息，例如「Compiling foo.cc to create foo.o」。訊息可能包含 %{label}、%{input} 或 %{output} 模式，這些模式會分別替換成標籤字串、首次輸入或輸出的路徑。偏好使用模式而非靜態字串，因為前者的效率較高。
use_default_shell_env	bool；預設值為 False 動作是否應使用預設殼層環境，其中包含幾個 OS 變數和透過 --action_env 設定的變數。 如果 use_default_shell_env 和 env 都設為 True，在啟用 --incompatible_merge_fixed_and_default_shell_env 的情況下，env 中設定的值會覆寫預設殼層環境 (預設)。如未啟用這個標記，系統會忽略 env。
env	dict；或 None；預設為 None 設定環境變數的字典。 如果 use_default_shell_env 和 env 都設為 True，在啟用 --incompatible_merge_fixed_and_default_shell_env 的情況下，env 中設定的值會覆寫預設殼層環境 (預設)。如未啟用這個標記，系統會忽略 env。
execution_requirements	dict；或 None； 預設值為 None 用於排程動作的資訊。如需實用索引鍵的標記，請參閱標記。
input_manifests	sequence 或 None；預設值為 None 舊版引數。忽略。
exec_group	string；或 None；預設值為 None 在指定的執行群組的執行平台上執行動作。如果沒有，則會使用目標的預設執行平台。
shadowed_action	Action；預設為 None 使用已新增至動作輸入清單的特定遭覆蓋動作的偵測到輸入項目，執行此動作。如果沒有，則只會使用動作的輸入內容。
resource_set	可呼叫；或 None；預設值為 None 。在本機執行時，可預估資源用量的回呼函式。請見 ctx.actions.run()。
toolchain	Label；或 string; 或 None；預設值為 unbound 此動作所用執行檔或工具的工具鍊類型。 如果可執行檔和工具並非來自工具鍊，請將此參數設為 `None`。 如果執行檔和工具來自工具鍊，就必須設定工具鍊類型，讓動作在正確的執行平台上執行。 請注意，建立這個動作的規則必須在其「rule()」函式中定義這個工具鍊。 如果同時設定 `toolchain` 和 `exec_group` 參數，則會使用 `exec_group`。如果 `exec_group` 未指定相同工具鍊，就會發生錯誤。

符號連結

None actions.symlink(output, target_file=None, target_path=None, is_executable=False, progress_message=None)

建立在檔案系統中寫入符號連結的動作。

呼叫這個函式時必須明確指定其中一個 target_file 或 target_path。

使用 target_file 時，請使用 declare_file() 或 declare_directory() 宣告 output，並符合 target_file 的類型。這會將符號連結指向 target_file。每當符號連結的目標或其內容有所變更，Bazel 就會撤銷這個動作的輸出內容。

否則，使用 target_path 時，請使用 declare_symlink() 宣告 output。在這種情況下，符號連結會指向 target_path。Bazel 一律不會解析符號連結，且只有在符號連結的文字內容 (也就是 readlink() 的值) 有所變更時，這個動作的輸出內容才會失效。尤其是可用於建立孤立的符號連結。

參數

參數	說明
output	檔案；必要 這個動作的輸出內容。
target_file	檔案; 或 None； 預設值為 None 輸出符號連結將指向的檔案。
target_path	字串; 或 None；預設值為 None 輸出符號連結指向的確切路徑。系統不會套用正規化或其他處理程序。
is_executable	bool；預設值為 False 只能搭配 target_file 使用，不能與 target_path 搭配使用。如為 true，則在執行動作時，系統會檢查 target_file 的路徑確認是否可執行；如果沒有，則會回報錯誤。如果將 is_executable 設為 False，不表示目標無法執行，只是不會進行驗證。 這項功能對 target_path 來說並不合理，因為建構期間可能沒有孤立的符號連結。
progress_message	string；或 None；預設值為 None 在建構期間要向使用者顯示的進度訊息。

template_dict

TemplateDict actions.template_dict()

傳回 TemplateDict 物件，用於擴充記憶體節省範本。

write

None actions.write(output, content, is_executable=False)

建立檔案寫入動作。執行動作時，它會將指定內容寫入檔案。此方法用於透過分析階段中可用的資訊產生檔案。如果檔案較大且含有大量靜態內容，建議使用 expand_template。

參數

參數	說明
output	File (檔案)；必要 輸出檔案。
content	string；或 Args；必要 檔案內容。可以是字串或 actions.args() 物件。
is_executable	bool；預設為 False 輸出檔案是否應執行。