ctx.actions 存取這個模組。成員
- args
- declare_directory
- declare_file
- declare_symlink
- do_nothing
- expand_template
- run
- run_shell
- symlink
- 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
|
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;
預設值 = []動作的輸入檔案清單。 |
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；預設值 = unbound實驗功能。這個參數仍在實驗階段，隨時可能變更。請勿完全仰賴它。您可以設定 --+experimental_lazy_template_expansion 實驗功能：擴展範本時要進行的替代變數，藉此進行實驗。 |
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;
預設值 = []列出動作的輸入檔案或解壓縮。 |
unused_inputs_list
|
File; or None;
default = None檔案包含動作未使用的輸入內容清單。 這個檔案的內容 (通常是動作的其中一個輸出內容) 會對應至整個動作執行期間未使用的輸入檔案清單。這些檔案中的任何變更，都不得以任何方式影響動作的輸出內容。 |
executable
|
File; or string; or FilesToRunProvider；必要動作要呼叫的執行檔。 |
tools
|
sequence; or depset;
預設值 = 解除繫結列出動作所需的任何工具或將其取消。工具是輸入內容並加入其他執行檔案，會自動提供給動作使用。當提供的清單可能是 Files、FileToRunProvider 執行個體的異質集合，或檔案解碼。凡是直接列於清單且來自 ctx.executable 的檔案，系統都會自動新增其執行檔案。提供 dep 時，只能包含「File」檔案。不論是哪一種情況， depset 中的檔案都不會與 runfile 交叉參照 ctx.executable。 |
arguments
|
sequence;
預設值 = []動作的指令列引數。必須是字串或 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;
預設值 = 無排定動作的資訊。如需瞭解實用鍵，請參閱標記。 |
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；預設值 = 無這個動作所用執行檔或工具的工具鍊類型。必須設定這個參數，才能讓動作在正確的執行平台上執行。 目前為免人工管理，但建議您在使用工具鍊時設定這項工具，因為日後的 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;
預設值 = []列出動作的輸入檔案或解壓縮。 |
tools
|
sequence of Files; or depset;
預設值 = 解除繫結列出動作所需的任何工具或將其取消。工具是輸入內容並加入其他執行檔案，會自動提供給動作使用。清單中可以包含 Files 或 FilesToRunProvider 執行個體。 |
arguments
|
sequence;
預設值 = []動作的指令列引數。必須是字串或 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;
預設值 = 無排定動作的資訊。如需瞭解實用鍵，請參閱標記。 |
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；預設值 = 無這個動作所用執行檔或工具的工具鍊類型。必須設定這個參數，才能讓動作在正確的執行平台上執行。 目前為免人工管理，但建議您在使用工具鍊時設定這項工具，因為日後的 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 = 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 輸出檔案是否應執行。 |