動作

回報問題 查看來源 夜間 · 8.3 · 8.2 · 8.1 · 8.0 · 7.6

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

成員

args

Args actions.args()

傳回 Args 物件，可用於建構節省記憶體的指令列。

declare_directory

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

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

參數

參數 說明
filename string; required
If no 'sibling' provided, path of the new directory, relative to the current package. 否則為檔案的基本名稱 (「同層級」會定義目錄)。
sibling 檔案；或 None； 預設為 None
與新宣告目錄位於同一目錄中的檔案。檔案必須位於目前的套件中。

declare_file

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

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

請注意，除了宣告檔案外，您還必須另外建立會發出檔案的動作。建立該動作時，需要將傳回的 File 物件傳遞至動作的建構函式。

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

參數

參數 說明
filename 字串； 必要
如未提供「同層級」，則為新檔案的路徑 (相對於目前套件)。否則為檔案的基本名稱 (「同層」會決定目錄)。
sibling 檔案；或 None； 預設為 None
與新建立的檔案位於同一目錄的檔案。檔案必須位於目前的套件中。 

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

宣告規則或構面會在目前的套件中建立具有指定名稱的符號連結。您必須建立產生這個符號連結的動作。Bazel 絕不會取消參照這個符號連結，而是會逐字轉移至沙箱或遠端執行器。目前不支援樹狀結構構件內的符號連結。

參數

參數 說明
filename 字串； 必要
如果未提供「同層級」，則為相對於目前套件的新符號連結路徑。否則為檔案的基本名稱 (「同層級」會定義目錄)。
sibling 檔案；或 None； 預設為 None
與新宣告的符號連結位於同一目錄中的檔案。

do_nothing

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

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

參數

參數 說明
mnemonic string; required
動作的單字說明，例如 CppCompile 或 GoLink。
inputs 序列的 File；或 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
展開範本時要進行的替換作業。

得分

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 sequence of Files; required
List of the output files of the action.
inputs 序列的 File 或 depset； 預設為 []
動作的輸入檔案清單或 depset。
unused_inputs_list 檔案；或 None； 預設為 None
包含動作未使用的輸入內容清單的檔案。

這個檔案的內容 (通常是動作的其中一個輸出內容) 對應於整個動作執行期間未使用的輸入檔案清單。這些檔案的任何變更不得以任何方式影響動作的輸出。

executable File；或 string；或 FilesToRunProvider； 必要
動作要呼叫的可執行檔。
tools sequence 或 depset； 預設為 unbound
動作所需的任何工具清單或 depset。工具是輸入內容，其中包含系統自動提供給動作的其他執行檔。如果提供清單，可以是檔案、FilesToRunProvider 執行個體或檔案 depsets 的異質集合。清單中直接來自 ctx.executable 的檔案會自動新增執行檔。如果提供 depsets，則只能包含檔案。在這兩種情況下，depsets 中的檔案都不會與 ctx.executable 交叉參照，以取得執行檔。
arguments sequence； 預設為 []
動作的指令列引數。必須是字串或 actions.args() 物件的清單。
mnemonic 字串；或 None； 預設為 None
動作的單字說明，例如 CppCompile 或 GoLink。
progress_message 字串；或 None; 預設為 None
在建構期間向使用者顯示的進度訊息，例如「正在編譯 foo.cc 以建立 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 字串；或 None； 預設為 None
在指定執行群組的執行平台上執行動作。如果沒有，則使用目標的預設執行平台。
shadowed_action 動作； 預設為 None
使用指定陰影動作的輸入內容和環境執行動作，並將這些內容新增至動作的輸入內容清單和環境。動作環境可以覆寫任何陰影動作的環境變數。如果沒有，則只會使用動作的輸入內容和指定環境。
resource_set 可呼叫的函式；或 None； 預設為 None
回呼函式，會傳回資源集字典，用於在本機執行這項動作時，估算執行階段的資源用量。

這個函式接受兩個位置引數：代表 OS 名稱的字串 (例如「osx」)，以及代表動作輸入數量的整數。傳回的字典可能包含下列項目，每個項目可能是浮點數或整數：

  • 「cpu」：CPU 數量，預設為 1
  • 「memory」：以 MB 為單位，預設為 250
  • 「local_test」：本機測試次數，預設為 1

如果這個參數設為 None，系統會使用預設值。

回呼必須是頂層函式 (不允許使用 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)

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

參數

參數 說明
outputs sequence of Files; required
List of the output files of the action.
inputs 序列的 File 或 depset； 預設為 []
動作的輸入檔案清單或 depset。
tools File 的序列；或 depset； 預設為 unbound
動作所需的任何工具清單或 depset。工具是輸入內容，其中包含系統自動提供給動作的其他執行檔。清單可以包含 Files 或 FilesToRunProvider 執行個體。
arguments sequence； 預設為 []
動作的指令列引數。必須是字串或 actions.args() 物件的清單。

Bazel 會將這個屬性中的元素做為引數傳遞至指令。指令可以使用殼層變數替換 (例如 $1、$2 等) 存取這些引數。請注意，由於 Args 物件會在編製索引前扁平化，如果 Args 物件的大小不明，後續所有字串都會位於無法預測的索引。如果 Args 物件的大小不確定，建議搭配使用 $@ (擷取所有引數)。

如果 command 是字串清單，可能不會使用這個參數。

mnemonic 字串；或 None； 預設為 None
動作的單字說明，例如 CppCompile 或 GoLink。
command 字串；或字串序列； 必要
要執行的 Shell 指令。這可以是字串 (建議使用)，也可以是字串序列 (已淘汰)。

如果 command 是字串，則會以 sh -c <command> "" <arguments> 執行，也就是說，arguments 中的元素會以 $1、$2 (或 %1、%2，如果使用 Windows 批次) 等形式提供給指令。如果 arguments 包含任何 actions.args() 物件，其內容會逐一附加至指令列，因此 $i 可以參照 Args 物件中的個別字串。請注意，如果將大小不明的 Args 物件做為 arguments 的一部分傳遞，字串就會位於不明的索引；在這種情況下，$@ 殼層替代 (擷取所有引數) 可能會很有用。

(已淘汰) 如果 command 是字串序列，第一個項目是要執行的可執行檔，其餘項目則是引數。如果使用這個表單，就不得提供 arguments 參數。請注意，這份表單已淘汰，近期內會移除。並使用 `--incompatible_run_shell_command_string` 停用。請使用這個標記驗證程式碼是否相容。

Bazel 會使用與 genrule 相同的殼層執行指令。
progress_message 字串；或 None; 預設為 None
在建構期間向使用者顯示的進度訊息，例如「正在編譯 foo.cc 以建立 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 字串；或 None； 預設為 None
在指定執行群組的執行平台上執行動作。如果沒有，則使用目標的預設執行平台。
shadowed_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 物件，以利進行記憶體效率高的範本擴充。

寫出好文

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

建立檔案寫入動作。執行動作時，系統會將指定內容寫入檔案。這項功能會使用分析階段提供的資訊產生檔案。如果檔案很大且包含大量靜態內容，建議使用 expand_template。

參數

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