動作

回報問題 查看來源

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

成員

args

Args actions.args()

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

宣告目錄

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

在目前的套件中宣告規則或長寬比的指定名稱。您必須建立會產生目錄的動作。您無法從 Starlark 直接存取目錄的內容，但可透過 Args.add_all() 在動作指令中擴充。只有 一般檔案和目錄可以放在 Dec_directory 的展開內容中。

參數

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

宣告檔案

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

宣告規則或長寬比會使用指定檔案名稱建立檔案。如果未指定 sibling，檔案名稱即為相對目錄，否則檔案與 sibling 位於同一個目錄中。無法在目前的套件中建立檔案。

請記得，除了宣告檔案之外，您也必須建立會模擬檔案的動作。建立該動作時，必須將傳回的 File 物件傳遞至動作的建構函式。

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

參數

參數 說明
filename 必要
如果未提供「同層級」，則為新檔案的路徑相對於目前的套件。否則檔案的基本名稱 (「sibling」) 會決定目錄。
sibling File; or None; default = None
位於新建立的檔案所在的目錄中。檔案必須位於目前的套件中。		 

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

此參數處於實驗階段，可能隨時會變更。設定 --noexperimental_allow_unresolved_symlinks 可能會停用

宣告規則或外觀，在目前的套件中以指定名稱建立符號連結。您必須建立可產生這個符號連結的動作。Bazel 一律不會參照這個符號連結，並將該口頭傳輸至沙箱或遠端執行工具。系統目前不支援樹狀結構構件中的符號連結。

參數

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

CANNOT TRANSLATE

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

建立空白指令，且不會執行指令或產生任何輸出內容，但很適合插入「額外動作」。

參數

參數 說明
mnemonic 必要
動作的單字說明，例如 CppCompile 或 GoLink。
inputs sequence of Files; or depset; default = []
動作的輸入檔案清單。

展開範本

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

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

參數

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

這個檔案的內容 (通常是其中一個動作的輸出) 對應至整個動作執行期間未使用的輸入檔案清單。這些檔案中的任何變更都不會影響動作的輸出結果。
executable File; or string; or FilesToRunProvider；必要
動作要呼叫的執行檔。
tools sequence; or depset； 預設 = 不受限
列出或縮減動作所需的任何工具。工具是具有其他執行檔的輸入內容，該檔案會自動提供可執行這項操作。提供清單時，這可能是檔案、FileToRunProvider 執行個體的異質性集合，或檔案集的解碼集。直接列於清單上且來自 ctx.executable 的檔案，則會自動新增執行檔案。如果提供 Deset，則必須僅包含 Files。無論是哪一種情況，系統都會針對 setfile 中的交叉執行檔案與交叉檔案一起參照 ctx.executable。
arguments sequence; default = []
動作的指令列引數。必須是字串清單或 actions.args() 物件。
mnemonic string; or None; default = None
動作的單字說明，例如 CppCompile 或 GoLink。
progress_message string; or None; default = 無
建構期間會向使用者顯示的進度訊息，例如「編譯 foo.cc 以建立 foo.o」。訊息可能包含 %{label}、%{input} 或 %{output} 模式，分別替換為標籤字串、第一個輸入項目或輸出路徑。建議使用模式取代靜態字串，因為前者可以更有效率。
use_default_shell_env default = False
動作是否應使用內建殼層環境。
env dict; or None; default = None
設定環境變數的字典。
execution_requirements dict; or None; default = None
排程動作的資訊。請參閱標記以瞭解實用金鑰。
input_manifests sequence; or None； 預設 = 無
(實驗性) 會設定輸入執行檔案的中繼資料，通常由 resolve_command 產生。
exec_group string; or None; default = None
對特定執行群組的執行平台執行動作。如果沒有任何，則會使用目標的預設執行平台。
shadowed_action Action; default = None
使用指定陰影動作的輸入和環境新增至動作的輸入清單和環境執行動作。動作環境可覆寫任何遭到覆蓋的動作的環境變數。如果沒有任何，則只能使用動作的輸入內容和指定環境。
resource_set callable; or None; 預設 = 無
一個回呼函式，會傳回資源集字典，以便在執行這項動作時，評估執行期間的資源用量。

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

  • "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」未指定相同的條件，就會發生錯誤。

執行殼層

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 sequence of Files；必要
動作的輸出檔案清單。
inputs sequence of Files; or depset; default = []
動作或解碼動作的輸入檔案。
tools sequence of Files; or depset； 預設 = 不受限
列出或縮減動作所需的任何工具。工具是具有其他執行檔的輸入內容，該檔案會自動提供可執行這項操作。清單中可包含 Files 或 FilesToRunProvider 執行個體。
arguments sequence; default = []
動作的指令列引數。必須是字串或 actions.args() 物件清單。

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

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

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

(已淘汰) 如果 command 是字串序列，第一個項目是執行的執行項目，其餘項目則是其引數。如果使用這份表單，就無法提供 arguments 參數。請注意，這份表單已淘汰，並將在近期內移除。「--incompatible_run_shell_command_string」已停用。請使用此旗標來確認程式碼相容。

Bazel 使用與 genrule 相同的指令執行指令。

progress_message string; or None; default = 無
建構期間會向使用者顯示的進度訊息，例如「編譯 foo.cc 以建立 foo.o」。訊息可能包含 %{label}、%{input} 或 %{output} 模式，分別替換為標籤字串、第一個輸入項目或輸出路徑。建議使用模式取代靜態字串，因為前者可以更有效率。
use_default_shell_env default = False
動作是否應使用內建殼層環境。
env dict; or None; default = None
設定環境變數的字典。
execution_requirements dict; or None; default = None
排程動作的資訊。請參閱標記以瞭解實用金鑰。
input_manifests sequence; or None； 預設 = 無
(實驗性) 會設定輸入執行檔案的中繼資料，通常由 resolve_command 產生。
exec_group string; or None; default = None
對特定執行群組的執行平台執行動作。如果沒有任何，則會使用目標的預設執行平台。
shadowed_action Action; default = None
使用指定陰影動作的探索輸入項目新增至動作輸入清單，以便執行動作。如果沒有任何，則只會使用動作的輸入內容。
resource_set callable; or 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 必要
這個動作的輸出內容。
target_file File; or None; default = 無
要提供輸出符號連結的檔案。
target_path string; or None; default = None
輸出符號指向的確切路徑。不會套用正規化或其他處理程序。
is_executable default = False
只能搭配 target_file 使用，不適用於 target_path。如果設為 true，系統會檢查 target_file 的路徑，確認其可執行，且如果不是，會回報錯誤。將 is_executable 設為 False 並不代表目標無法執行，只是未完成驗證程序。

此符號在建構期間可能不能使用同式符號連結，因此並不適合使用 target_path。
progress_message string; or None; default = 無
建構期間會向使用者顯示的進度訊息。

範本狀態

TemplateDict actions.template_dict()

實驗功能。這個 API 目前處於實驗階段，隨時可能變更。請勿依附於此。設定 --+experimental_lazy_template_expansion
實驗功能：傳回 TemplateDict 物件，以便提高記憶體效率，以便啟用實驗功能。

write

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

建立檔案寫入動作。執行這個動作後，就會將指定內容寫入檔案。這可用於使用分析階段提供的資訊產生檔案。如果檔案較大且含有大量靜態內容，請考慮使用 expand_template。

參數

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