動作

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

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

成員

args

Args actions.args()

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

declare_directory

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

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

參數

參數 說明
filename 必要
如果未提供「sibling」,則為相對於目前套件的新目錄路徑。否則,檔案的基本名稱 (「兄弟」定義目錄)。
sibling 檔案None;預設為 None
。 與新宣告的目錄位於同一目錄中的檔案。檔案必須位於目前的套件中。

declare_file

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

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

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

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

參數

參數 說明
filename 必要
如果未提供「sibling」,則為新檔案相對於目前套件的路徑。否則,檔案的基本名稱 (由「同胞」決定目錄)。
sibling File;或 None;預設值為 None
。這是指與新建檔案位於相同目錄中的檔案。檔案必須位於目前的套件中。

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

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

參數

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

do_nothing

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

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

參數

參數 說明
mnemonic 必要
動作的單字說明,例如 CppCompile 或 GoLink。
inputs Filesequence;或 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 預設為 {}
展開範本時要進行的替換。
is_executable 預設為 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 File序列; 必要
動作的輸出檔案清單。
inputs Filedepset序列;預設為 []
。 動作的輸入檔案清單或 depset。
unused_inputs_list File;或 None;預設值為 None
,其中包含動作未使用的輸入清單。

這個檔案的內容 (通常是動作的其中一個輸出項目) 會對應至在整個動作執行期間未使用的輸入檔案清單。這些檔案中的任何變更,都不會影響動作的輸出。

executable File;或 string;或 FilesToRunProvider;必要
動作要呼叫的可執行檔案。
tools sequencedepset;預設為 unbound
。列出動作所需的任何工具,或 depset。工具是指含有額外執行檔的輸入內容,這些執行檔會自動提供給動作。提供清單時,可以是 Files、FilesToRunProvider 例項或 Files 的 depset 的異質集合。系統會自動新增清單中直接來自 ctx.executable 的檔案。提供的 depset 只能包含檔案。無論是哪種情況,在執行檔的 depset 中,檔案都不會與 ctx.executable 交叉參照。
arguments sequence;預設值為 []
。動作的指令列引數。必須是字串或 actions.args() 物件的清單。
mnemonic 字串None;預設為 None
。 動作的單字說明,例如 CppCompile 或 GoLink。
progress_message 字串None;預設為 None
。顯示在建構期間向使用者顯示的進度訊息,例如「Compiling foo.cc to create foo.o」。訊息可能包含 %{label}%{input}%{output} 模式,這些模式會分別替換為標籤字串、第一個輸入內容或輸出路徑。偏好使用模式而非靜態字串,因為前者的效率較高。
use_default_shell_env 預設值為 False
動作是否應使用預設的 Shell 環境,其中包含幾個依作業系統而異的變數,以及透過 --action_env 設定的變數。

如果 use_default_shell_envenv 都設為 True,在啟用 --incompatible_merge_fixed_and_default_shell_env (預設) 的情況下,env 中設定的值會覆寫預設的殼層環境。如果未啟用旗標,系統會忽略 env

env dict;或 None;預設為 None
設定環境變數的字典。

如果 use_default_shell_envenv 都設為 True,在啟用 --incompatible_merge_fixed_and_default_shell_env (預設) 的情況下,env 中設定的值會覆寫預設的殼層環境。如果未啟用旗標,系統會忽略 env

execution_requirements dict;或 None; 預設值為 None
用於排程動作的資訊。如需瞭解實用的鍵,請參閱「標記」。
input_manifests sequence;或 None; 預設值為 None
(實驗功能) 會設定輸入執行檔中繼資料,這些資料通常是由 resolve_command 產生。
exec_group 字串None; 預設為 None
在指定執行群組的執行平台上執行動作。如果沒有,則使用目標的預設執行平台。
shadowed_action 動作;預設為 None
。 使用指定的遮罩動作輸入內容和環境,執行動作,並將其加入動作的輸入內容清單和環境。動作環境可以覆寫任何遮蔽動作的環境變數。如果沒有,則只使用動作的輸入內容和指定環境。
resource_set 可呼叫;或 None;預設值為 None
這個回呼函式會傳回資源集字典,用於在本機執行這個動作時預估在執行時間的資源用量。

這個函式會接受兩個位置引數:代表作業系統名稱的字串 (例如「osx」),以及代表動作輸入數量的整數。傳回的字典可能包含下列項目,而每個項目可能為浮點值或 int:

  • "cpu":CPU 數量;預設值為 1
  • 「memory」:以 MB 為單位,預設值為 250
  • 「local_test」:本機測試數量;預設為 1

如果此參數設為 None,或 --experimental_action_resource_set 為 false,則會使用預設值。

回呼必須是頂層 (不允許 lambda 和巢狀函式)。

toolchain Label;或 string;或 None; 預設為 unbound

在這個動作中使用的可執行檔或工具的工具鍊類型。必須設定參數,才能在正確的執行平台上執行動作。

目前這項屬性不會執行任何操作,但我們建議您在使用工具鍊時設定這項屬性,因為日後的 Bazel 版本將需要這項屬性。

請注意,建立此動作的規則需要在其「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 File序列; 必要
動作的輸出檔案清單。
inputs Filedepset序列;預設為 []
。 動作的輸入檔案清單或 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 字串;或 字串字串序列;必須執行的
殼層指令。這可以是字串 (建議) 或字串序列 (已淘汰)

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

(已淘汰)如果 command 是字串序列,第一個項目就是要執行的可執行檔,其餘項目則是引數。如果使用這個表單,就必須提供 arguments 參數。請注意,這份表單已淘汰,不久後就會移除。使用 `--incompatible_run_shell_command_string` 即可停用此功能。請使用這個標記來驗證您的程式碼是否相容。

Bazel 會使用與 genrules 相同的殼層執行指令。

progress_message 字串None;預設為 None
。顯示在建構期間向使用者顯示的進度訊息,例如「Compiling foo.cc to create foo.o」。訊息可能包含 %{label}%{input}%{output} 模式,這些模式會分別替換為標籤字串、第一個輸入內容或輸出路徑。請盡量使用模式,而非靜態字串,因為前者效率較高。
use_default_shell_env 預設值為 False
是否應使用預設殼層環境,其中包含幾個 OS 變數以及透過 --action_env 設定的變數。

如果 use_default_shell_envenv 都設為 True,在啟用 --incompatible_merge_fixed_and_default_shell_env 的情況下,env 中設定的值會覆寫預設殼層環境 (預設)。如果未啟用旗標,系統會忽略 env

env dictNone;預設為 None
。設定環境變數字典。

如果 use_default_shell_envenv 都設為 True,在啟用 --incompatible_merge_fixed_and_default_shell_env (預設) 的情況下,env 中設定的值會覆寫預設的殼層環境。如果未啟用旗標,系統會忽略 env

execution_requirements 字典None;預設為 None
。用於排定動作的資訊。如需瞭解實用的鍵,請參閱「標記」。
input_manifests sequence;或 None; 預設值為 None
(實驗功能) 會設定輸入執行檔中繼資料,這些資料通常是由 resolve_command 產生。
exec_group 字串None; 預設為 None
在指定執行群組的執行平台上執行動作。如果沒有,則使用目標的預設執行平台。
shadowed_action 動作; 預設為 None
使用已新增至動作輸入清單的指定遮罩動作所發現的輸入內容,執行動作。如果沒有,則只會使用動作的輸入內容。
resource_set 可呼叫;或 None;預設值為 None
。在本機執行時,可預估資源用量的回呼函式。請參閱 ctx.actions.run()
toolchain Label;或 string;或 None; 預設為 unbound

在這個動作中使用的可執行檔或工具的工具鍊類型。你必須設定這個參數,動作會在正確的執行平台上執行。

目前這項屬性不會執行任何操作,但我們建議您在使用工具鍊時設定這項屬性,因為日後的 Bazel 版本將需要這項屬性。

請注意,建立此動作的規則需要在其「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_filetarget_path 其中一個。

使用 target_file 時,請使用 declare_file()declare_directory() 宣告 output,並與 target_file 的類型相符。這會讓符號連結指向 target_file。每當符號連結的目標或內容有所變更,Bazel 就會讓這個動作的輸出內容失效。

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

參數

參數 說明
output required
此動作的輸出內容。
target_file FileNone; 預設為 None
輸出符號連結會指向的檔案。
target_path 字串;或 None;預設為 None
輸出符號連結會指向的確切路徑。系統不會套用任何標準化或其他處理作業。
is_executable 預設值為 False
。 只能與 target_file 搭配使用,不能與 target_path 搭配使用。如果為 true,執行動作時,系統會檢查 target_file 的路徑,確認是否可執行,如果無法執行,系統會回報錯誤。將 is_executable 設為 False 並不表示目標無法執行,只是表示系統不會進行驗證。

這項功能對 target_path 來說並不合理,因為建構期間可能沒有孤立的符號連結。

progress_message 字串None; 預設為 None
。 在建構期間向使用者顯示的進度訊息。

template_dict

TemplateDict actions.template_dict()

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

write

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

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

參數

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