動作

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

成員

args

Args actions.args()

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

declare_directory

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

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

參數

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

declare_file

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

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

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

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

參數

參數 說明
filename 必要
如果不是「同層級」的新檔案路徑 (相對於目前套件)。否則，檔案的基本名稱 (由「同胞」決定目錄)。
sibling File; or None; default = None
與新建檔案位於同一目錄的檔案。該檔案必須位於目前的套件中。 

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

Experimental。這個參數仍在實驗階段，可能隨時變更。請勿仰賴這項功能。您可以設定 --experimental_allow_unresolved_symlinks，啟用這項實驗功能

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

參數

參數 說明
filename 必要
如果未提供「sibling」，則為新符號連結的路徑，相對於目前套件。否則，檔案的基礎名稱 (sibling 會定義目錄)。
sibling File; or None; default = None
與新宣告的符號連結位於同一目錄中的檔案。

do_nothing

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

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

參數

參數 說明
mnemonic 必填
動作的單字說明，例如 CppCompile 或 GoLink。
inputs sequence of Files; or 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 default = {}
展開範本時要進行的替換。
is_executable default = False
是否應可執行輸出檔案。
computed_substitutions TemplateDict； 預設值 = 未綁定
實驗。這項參數仍在實驗階段，隨時可能變更。請勿依賴這項功能。你可以設定 --+experimental_lazy_template_expansion
實驗功能：替代項目，在展開範本時進行實驗。

得分

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=None)

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

參數

參數 說明
outputs sequence of Files; 必要
動作的輸出檔案清單。
inputs sequence of Files; or depset; 預設 = []
可列出或解碼動作的輸入檔案。
unused_inputs_list File; or None; 預設值 = 無
此檔案包含動作未使用的輸入項目清單。

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

executable File; or string; or FilesToRunProvider; required
Action 要呼叫的執行檔。
tools sequence; or depset; 預設值 = 不繫結
列出或去除動作所需的任何工具。工具是包含額外執行檔案的輸入資料，系統會自動提供給動作使用。提供清單時，可能會構成異質的 Files、FileToRunProvider 例項或 Files 的 Depset。系統會自動新增清單中直接來自 ctx.executable 的檔案。如果提供 Depset，則其中只能含有 Files，無論是哪種情況，依附元件集合中的檔案都不會與執行檔的 ctx.executable 交叉參照。
arguments sequence; 預設 = []
動作的指令列引數。必須是字串或 actions.args() 物件的清單。
mnemonic string; or None; default = None
動作的單字說明，例如 CppCompile 或 GoLink。
progress_message string; or None; 預設值 = 無
建構期間向使用者顯示的進度訊息，例如「Compiling foo.cc to create foo.o」。訊息可能包含 %{label}、%{input} 或 %{output} 模式，這些模式分別會替換為標籤字串、第一個輸入內容或輸出路徑。偏好使用模式而非靜態字串，因為前者的效率較高。
use_default_shell_env 預設值 = 否
動作是否應使用內建殼層環境。
env dict; or None; 預設值 = 無
設定環境變數的字典。
execution_requirements dict; or None; 預設值 = None
用於排定動作的資訊。如需實用索引鍵的標記，請參閱標記。
input_manifests sequence; or None； 預設值 = None
(實驗功能) 會設定輸入的執行檔中繼資料，這些資料通常是由 resolve_command 產生。
exec_group string; or None; default = None
在指定執行群組的執行平台上執行動作。如果沒有，則會使用目標的預設執行平台。
shadowed_action Action; 預設值 = None
使用已新增至動作輸入清單和環境的指定遮罩動作輸入和環境，執行動作。動作環境可以覆寫任何遮蔽動作的環境變數。如果沒有，則只使用動作的輸入內容和指定環境。
resource_set callable; or None; 預設值 = None
如果在本機執行此動作，回呼函式會傳回資源集字典，用於估算執行時間的資源使用量。

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

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

如果這個參數設為 None，或是 --experimental_action_resource_set 為 false，系統會使用預設值。

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

toolchain Label; or string; or None; 預設值 = 無

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

目前免人工管理，但建議您在使用工具鍊時設定這項工具，因為之後的 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=None)

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

參數

參數 說明
outputs sequence of Files; required
Action 的輸出檔案清單。
inputs sequence of Files; or depset; default = []
action 的輸入檔案清單或 depset。
tools sequence of Files; or depset; default = unbound
action 所需工具的清單或 depset。工具是指含有額外執行檔的輸入內容，這些執行檔會自動提供給動作。清單可包含 Files 或 FilesToRunProvider 例項。
arguments sequence; default = []
Action 的指令列引數。必須是字串或 actions.args() 物件的清單。

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

如果 command 是字串清單，則可能不會使用這項參數。
mnemonic string; or None; 預設值 = 無
動作的單字說明，例如 CppCompile 或 GoLink。
command string; or sequence of strings; 必要
Shell 指令 (要執行)。該字串可以是字串 (建議) 或一系列字串 (已淘汰)。

如果 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; or None; default = None
建構期間向使用者顯示的進度訊息，例如「Compiling foo.cc to create foo.o」。訊息可能包含 %{label}、%{input} 或 %{output} 模式，這些模式會分別替換成標籤字串、首次輸入或輸出的路徑。請盡量使用模式，而非靜態字串，因為前者效率較高。
use_default_shell_env 預設值 = 否
動作是否應使用內建殼層環境。
env dict; or None; default = None
設定環境變數字典。
execution_requirements dict; or None; 預設值 = 無
排定動作時程的資訊。如需實用索引鍵的標記，請參閱標記。
input_manifests sequence; or None； 預設值 = None
(實驗功能) 會設定輸入的 runfile 中繼資料，這些資料通常是由 resolve_command 產生。
exec_group string; or None; 預設值 = 無
在指定 exec 群組的執行平台上執行動作。如果沒有，則會使用目標的預設執行平台。
shadowed_action Action; 預設值 = 無
這個外掛程式能使用已新增至動作輸入清單的特定遭覆蓋動作的偵測到輸入項目，執行此動作。如果沒有，則只使用動作的輸入內容。
resource_set callable; or None; 預設值 = None
回呼函式，用於在本機執行時估算資源使用量。請見 ctx.actions.run()。
toolchain Label; or string; or None; 預設值 = 無

此動作所用執行檔或工具的工具鍊類型。必須設定參數，才能在正確的執行平台上執行動作。

目前免人工管理，但建議您在使用工具鍊時設定這項工具，因為之後的 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_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 required
此動作的輸出內容。
target_file File; or None; 預設值 = 無
輸出符號連結指向的檔案。
target_path string; or None; default = None
(實驗功能) 輸出符號連結會指向的確切路徑。系統不會套用正規化或其他處理程序。如要使用這項功能，請設定 --experimental_allow_unresolved_symlinks。
is_executable 預設值 = 否
只能搭配 target_file 使用，無法用於 target_path。如果為 true，執行動作時，系統會檢查 target_file 的路徑，確認是否可執行，如果無法執行，系統會回報錯誤。如果將 is_executable 設為 False，不表示目標無法執行，只是不會進行驗證。

這項功能對 target_path 來說並不合理，因為在建構期間可能不存在懸而未決的符號連結。
progress_message string; or None; 預設值 = 無
建構期間要向使用者顯示的進度訊息。

template_dict

TemplateDict actions.template_dict()

Experimental。這個 API 仍在實驗階段，可能隨時變更。請勿依賴這項功能。您可以設定 --+experimental_lazy_template_expansion
Experimental，以實驗方式啟用此功能：返回 TemplateDict 物件，以便進行記憶體效率高的範本展開作業。

write

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

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

參數

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