ctx.actions 存取這個模組。會員
- args
- declare_directory
- declare_file
- declare_symlink
- do_nothing
- expand_template
- run
- run_shell
- 符號連結
- template_dict
- write
args
Args actions.args()傳回可用來建構節省記憶體的指令列的 Args 物件。
declare_directory
File actions.declare_directory(filename, *, sibling=None)宣告規則或切面在目前的套件中建立同名的目錄。必須建立用來產生目錄的動作。您無法直接從 Starlark 存取目錄內容，但您可以使用
Args.add_all() 在動作指令中展開目錄。
參數
| 參數 | 說明 |
|---|---|
filename
|
必要 如未提供「同層級」，請提供新目錄的路徑 (相對於目前套件)。或者是檔案的基本名稱 (「同層級」會定義目錄)。 |
sibling
|
File; or None;
default = None與新宣告目錄位於同一個目錄中的檔案。檔案必須位於目前的套件中。 |
declare_file
File actions.declare_file(filename, *, sibling=None)宣告規則或切面使用指定的檔案名稱建立檔案。如未指定
sibling，檔案名稱會與套件目錄相關，否則檔案會與 sibling 位於相同的目錄中。無法在目前檔案包之外建立檔案。請記住，除了宣告檔案之外，您必須另外建立發出檔案的動作。如要建立動作，必須將傳回的 File 物件傳遞至動作的建構函式。
請注意，您不需要 (也不得) 使用這個函式宣告預先宣告的輸出檔案。您可以改為從 ctx.outputs 取得其 File 物件。查看使用範例。
參數
| 參數 | 說明 |
|---|---|
filename
|
必要 如未提供「同層級」，請提供新檔案相對於目前套件的路徑。否則，即為檔案的基本名稱 (「sibling」則定義目錄)。 |
sibling
|
File; or None;
default = None與新建檔案位於同一個目錄中的檔案。檔案必須位於目前的套件中。 |
declare_symlink
File actions.declare_symlink(filename, *, sibling=None)
實驗功能。這個參數仍在實驗階段，隨時可能變更。請勿依附於此項目。您可以設定 --experimental_allow_unresolved_symlinks，以實驗性的方式啟用這項功能
宣告規則或切面在目前套件中，以指定名稱建立符號連結。您必須建立能產生這個符號連結的動作。Bazel 絕不會對這個符號連結進行解除參照，並完全轉移至沙箱或遠端執行工具。
參數
| 參數 | 說明 |
|---|---|
filename
|
必要 如未提供「同層級」，請提供新符號連結的路徑，也就是與目前套件相對的路徑。或者是檔案的基本名稱 (「同層級」會定義目錄)。 |
sibling
|
File; or None;
default = None與新宣告符號連結位於同一個目錄中的檔案。 |
do_nothing
None actions.do_nothing(mnemonic, inputs=[])建立空白動作，該動作不會執行指令或產生任何輸出內容，但對於插入「額外動作」很有幫助。
參數
| 參數 | 說明 |
|---|---|
mnemonic
|
必要 用單字組成的動作說明，例如 CppCompile 或 GoLink。 |
inputs
|
sequence of Files; or depset;
default = []動作的輸入檔案清單。 |
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;
default = unboundExperimental。這個參數仍在實驗階段，隨時可能變更。請勿依附於此項目。您可以設定 --+experimental_lazy_template_expansion Experimental: SubAlternatives，在展開範本時啟用這項實驗功能。 |
run
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;
default = []列出或切割動作的輸入檔案。 |
unused_inputs_list
|
File; or None;
default = None檔案，內含動作未使用的輸入項目清單。 這個檔案的內容 (通常是動作的其中一種) 會對應至整個動作執行期間未使用的輸入檔案清單。這些檔案中的任何變更皆不得對動作的輸出造成任何影響。 |
executable
|
File; or string; or FilesToRunProvider；必要動作要呼叫的可執行檔案。 |
tools
|
sequence; or depset;
default = unbound列出動作所需的任何工具，或停止使用。「工具」是附有額外執行檔案的輸入內容，可以自動用於動作。提供清單時，可以是 Files、FileToRunProvider 執行個體的異質集合，或檔案廢棄物。如果檔案直接列在清單中，並且來自 ctx.executable，系統便會自動新增自身的執行檔案。如有提供 depset，則只能包含「Files」。在這兩種情況下， depset 內的檔案都不會與 ctx.executable 交叉參照執行檔。 |
arguments
|
sequence;
default = []動作的指令列引數。必須是字串或 actions.args() 物件清單。 |
mnemonic
|
string; or None;
default = None單字的動作說明，例如 CppCompile 或 GoLink。 |
progress_message
|
string; or None;
default = None在建構期間向使用者顯示的進度訊息，例如「Compiling foo.cc to create 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;
default = None(實驗功能) 會設定輸入執行檔案的中繼資料，通常由 resolve_command 產生。 |
exec_group
|
string; or None;
default = None在指定執行群組的執行平台上執行動作。如果沒有，則會使用目標的預設執行平台。 |
shadowed_action
|
Action;
default = None使用已新增至動作輸入清單和環境的指定遮蔽動作輸入和環境執行動作。動作環境可以覆寫任何覆蓋動作的環境變數。如果沒有，則只會使用動作的輸入內容和指定的環境。 |
resource_set
|
callable; or None;
default = None此回呼函式會傳回資源集字典，如果在本機執行這項動作，則用於預估執行時間的資源用量。 這個函式接受兩個位置引數：一個代表 OS 名稱的字串 (例如「osx」)，以及代表動作輸入數量的整數。傳回的字典可能包含下列項目，每個項目可以是浮點值或 int：
如果此參數設為 回呼必須是頂層函式 (不得使用 lambda 和巢狀函式)。 |
toolchain
|
Label; or string; or None;
default = 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；必要動作的輸出檔案清單。 |
inputs
|
sequence of Files; or depset;
default = []列出或切割動作的輸入檔案。 |
tools
|
sequence of Files; or depset;
default = unbound列出動作所需的任何工具，或停止使用。「工具」是附有額外執行檔案的輸入內容，可以自動用於動作。清單中可包含 Files 或 FilesToRunProvider 執行個體。 |
arguments
|
sequence;
default = []動作的指令列引數。必須是字串或 actions.args() 物件清單。Bazel 會將此屬性中的元素做為引數傳遞至指令。這個指令可以使用殼層變數替代項目 (例如 如果 |
mnemonic
|
string; or None;
default = None單字的動作說明，例如 CppCompile 或 GoLink。 |
command
|
string; or sequence of strings；必須執行殼層指令。這可以是字串 (建議) 或一系列的字串 (已淘汰)。 如果 (已淘汰) 如果 Bazel 會使用與 Genrules 相同的殼層執行指令。 |
progress_message
|
string; or None;
default = None在建構期間向使用者顯示的進度訊息，例如「Compiling foo.cc to create 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;
default = None(實驗功能) 會設定輸入執行檔案的中繼資料，通常由 resolve_command 產生。 |
exec_group
|
string; or None;
default = None在指定執行群組的執行平台上執行動作。如果沒有，則會使用目標的預設執行平台。 |
shadowed_action
|
Action;
default = None使用已新增至動作輸入清單的特定遮蔽動作發現的輸入內容執行動作。如果沒有，則只會使用動作的輸入內容。 |
resource_set
|
callable; or None;
default = None如果在本機執行，用於估算資源用量的回呼函式。請見 ctx.actions.run()。
|
toolchain
|
Label; or string; or None;
default = 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;
default = None輸出符號連結將指向的檔案。 |
target_path
|
string; or None;
default = None(實驗功能) 輸出符號連結會指向的確切路徑。不會套用正規化或其他處理。如要使用這項功能，必須設定 --experimental_allow_unresolved_symlinks。 |
is_executable
|
default = False 只能與 target_file 搭配使用，而不能與 target_path 搭配使用。如果為 true，當動作執行時，系統會檢查 target_file 的路徑，確認其為可執行檔並回報錯誤。將 is_executable 設為 False 並不代表無法執行目標，只是不會執行任何驗證程序。這項功能不適用於 |
progress_message
|
string; or None;
default = None在建構期間向使用者顯示的進度訊息。 |
template_dict
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 指出輸出檔案是否應可執行。 |