動作

Nightly · 8.4 · 8.3 · 8.2 · 8.1 · 8.0 · 7.7
提供函式來建立動作的模組。使用 ctx.actions 存取這個模組。

成員

args

Args actions.args()

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

declare_directory

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

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

參數

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

declare_file

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

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

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

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

參數

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

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

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

參數

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

do_nothing

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

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

參數

參數 說明
mnemonic string; required
A one-word description of the action, for example, CppCompile or GoLink.
inputs sequence of Files；或 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
展開範本時要進行的替換作業。

map_directory

None actions.map_directory(*, input_directories, additional_inputs={}, output_directories, tools, additional_params={}, execution_requirements=None, exec_group=None, toolchain=None, use_default_shell_env=False, env=None, mnemonic=None, implementation)

根據一或多個輸入目錄中的檔案建立多個動作，以輸出一或多個輸出目錄。

參數

參數 說明
input_directories File 的 dict；必要
字串對應至輸入目錄的字典，如 ctx.actions.declare_directory() 所宣告 (這裡只允許目錄做為值)。這些值會指定要展開的目錄，以便在實作函式中存取檔案。索引鍵 (字串) 會做為 ID，方便在實作函式中參照特定目錄。
additional_inputs dict；預設為 {}
字串對應至額外輸入內容的字典 (這裡只允許檔案、FilesToRunProvider(s) 和 Depset(s))。這些值會指定要讓實作函式建立的動作存取的任何額外輸入內容。這些鍵 (字串) 可做為 ID，方便您在實作函式中參照特定輸入內容。
output_directories dict 的 File；必要
字串到輸出目錄的字典對應，如 ctx.actions.declare_directory() 所宣告。這些值會指定實作函式所建立動作要產生的輸出目錄。這些鍵 (字串) 可做為 ID，方便您從實作函式中參照特定輸出目錄。
tools dict; required
字串到工具的字典對應 (這裡只允許檔案、FilesToRunProvider(s) 和 Depset(s))。這些值會指定要讓實作函式建立的動作存取的工具。這些鍵 (字串) 可做為 ID，方便您從實作函式中參照特定工具。
additional_params dict; 預設值為 {}
字串到其他參數的字典對應 (這裡只允許字串、布林值和整數值)。這些值會指定要讓實作函式存取的任何其他參數，可用於影響函式的行為。鍵 (字串) 可做為 ID，方便從實作函式中參照特定參數。
execution_requirements dict 或 None；預設為 None
排定所建立動作的時間。請參閱標記瞭解實用鍵。
exec_group string；或 None；預設為 None
在指定執行群組的執行平台上，執行建立的動作。如果沒有，則使用目標的預設執行平台。
toolchain Label；或 string；或 None；預設值為 None

可執行檔或所建立動作使用的工具的工具鍊類型。

如果可執行檔和工具不是來自工具鍊，請將這個參數設為 None。

如果可執行檔和工具來自工具鍊，則必須設定工具鍊類型，確保建立的動作在正確的執行平台執行。

請注意，建立這些動作的規則需要在「rule()」函式中定義這個工具鍊。

如果同時設定 toolchain 和 exec_group 參數，系統會使用 exec_group。如果 exec_group 未指定相同的工具鍊，系統就會發出錯誤。
use_default_shell_env bool；預設為 False
建立的動作是否應使用預設的殼層環境，其中包含幾個與 OS 相關的變數，以及透過 --action_env 設定的變數。

如果 use_default_shell_env 和 env 都設為 True，env 中設定的值會覆寫預設的殼層環境。

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

如果 use_default_shell_env 和 env 都設為 True，env 中設定的值會覆寫預設的殼層環境。

mnemonic string；或 None； 預設值為 None
所建立動作的單字說明，例如 CppCompile 或 GoLink。
implementation 函式； 必要
輸入目錄建構完成後，系統會呼叫這個 Starlark 函式，產生將檔案輸出至指定輸出目錄的動作。這個函式會傳遞下列引數：
  • template_ctx (位置)：可用於建立動作的 template_ctx 物件。
  • input_directories (僅限關鍵字)：字典，將 actions.map_directory() 的 input_directories 引數字串鍵對應至其值對應的 ExpandedDirectory 物件。
  • output_directories (僅限關鍵字)：actions.map_directory() 的 output_directories 引數值；從字串到輸出目錄的字典對應。
  • additional_inputs (僅限關鍵字)：actions.map_directory() 的 additional_inputs 引數值；從字串到輸入檔案的字典對應。
  • tools (僅限關鍵字)：actions.map_directory() 的 tools 引數值；從字串到工具的字典對應。
  • additional_params (僅限關鍵字)：actions.map_directory() 的 additional_params 引數值；從字串到字串、布林值或整數的字典對應。
這個函式必須是頂層函式，也就是說，不得使用 lambda 和巢狀函式。

得分

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；或 depset；預設為 []
動作的輸入檔案清單或 depset。
unused_inputs_list File 或 None； 預設為 None
包含動作未使用的輸入內容清單的檔案。

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

executable File；或 string；或 FilesToRunProvider；必要
動作要呼叫的可執行檔。
tools sequence 或 depset； 預設為 unbound
動作所需的任何工具清單或 depset。工具是可執行的輸入內容，可能會有自己的執行檔，系統會自動提供給動作。

如果提供清單，可以是下列異質集合：

  • File 秒
  • FilesToRunProvider 個執行個體
  • depset 秒的 File 秒
File清單中直接列出的 ctx.executable 和 FilesToRunProvider 會自動新增執行檔。所有工具都會隱含地新增為輸入內容。

arguments sequence；預設值為 []
動作的指令列引數。必須是字串或 actions.args() 物件的清單。
mnemonic string；或 None； 預設值為 None
動作的單字說明，例如 CppCompile 或 GoLink。
progress_message string；或 None；預設為 None
建構期間向使用者顯示的進度訊息，例如「正在編譯 foo.cc 以建立 foo.o」。訊息可能包含 %{label}、%{input} 或 %{output} 模式，分別會替換為標籤字串、第一個輸入內容或輸出內容的路徑。請盡量使用模式，而非靜態字串，因為前者效率較高。
use_default_shell_env bool；預設為 False
動作是否應使用預設的殼層環境，其中包含幾個與 OS 相關的變數，以及透過 --action_env 設定的變數。

如果 use_default_shell_env 和 env 都設為 True，env 中設定的值會覆寫預設的殼層環境。

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

如果 use_default_shell_env 和 env 都設為 True，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」)，以及代表動作輸入數量的整數。傳回的字典可能包含下列項目，每個項目可能是浮點數或整數：

  • 「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；必要
動作的輸出檔案清單。
inputs sequence of Files；或 depset；預設為 []
動作的輸入檔案清單或 depset。
tools sequence of Files；或 depset； 預設值為 unbound
動作所需的任何工具清單或 depset。工具是可執行的輸入內容，可能會有自己的執行檔，系統會自動提供給動作。

如果提供清單，可以是下列異質集合：

  • File 秒
  • FilesToRunProvider 個執行個體
  • depset 秒的 File 秒
File清單中直接列出的 ctx.executable 和 FilesToRunProvider 會自動新增執行檔。所有工具都會隱含地新增為輸入內容。

arguments sequence；預設值為 []
動作的指令列引數。必須是字串或 actions.args() 物件的清單。

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

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

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

如果 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 string；或 None；預設為 None
建構期間向使用者顯示的進度訊息，例如「正在編譯 foo.cc 以建立 foo.o」。訊息可能包含 %{label}、%{input} 或 %{output} 模式，分別會替換為標籤字串、第一個輸入內容或輸出內容的路徑。請盡量使用模式，而非靜態字串，因為前者效率較高。
use_default_shell_env bool；預設為 False
動作是否應使用預設的殼層環境，其中包含幾個與 OS 相關的變數，以及透過 --action_env 設定的變數。

如果 use_default_shell_env 和 env 都設為 True，env 中設定的值會覆寫預設的殼層環境。

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

如果 use_default_shell_env 和 env 都設為 True，env 中設定的值會覆寫預設的殼層環境。

execution_requirements dict；或 None； 預設為 None
排定動作的資訊。請參閱標記瞭解實用鍵。
input_manifests sequence 或 None；預設值為 None
舊版引數。已忽略。
exec_group string；或 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, target_type=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；或 None；預設為 None
輸出符號連結將指向的檔案。
target_path string；或 None；預設值為 None
輸出符號連結將指向的確切路徑。系統不會套用任何正規化或其他處理程序。
target_type string 或 None；預設值為 None
只能與 target_path 一起使用，不能與 target_file 一起使用。如要指定，值必須為「file」或「directory」，表示目標路徑的預期類型。

在 Windows 上，這會決定要建立哪種檔案系統物件 (目錄的接合點，檔案的符號連結)。不會影響其他作業系統。

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, *, mnemonic=None)

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

參數

參數 說明
output 檔案； 必要
輸出檔案。
content string；或 Args；必要
檔案內容。可以是字串或 actions.args() 物件。
is_executable bool；預設為 False
輸出檔案是否應為可執行檔。
mnemonic string；或 None； 預設值為 None
動作的單字說明，例如 CppCompile 或 GoLink。