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:
如果這個參數設為 回呼必須是頂層 (不得使用 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 會將這項屬性中的元素做為引數傳遞至指令。這個指令可以使用殼層變數 (例如 如果 |
mnemonic
|
string; or None ;
default = None動作的單字說明,例如 CppCompile 或 GoLink。 |
command
|
string; or sequence of strings ;
必要的指令執行。這可以是字串 (建議) 或一系列字串 (已淘汰)。 如果 (已淘汰) 如果 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 並不代表目標無法執行,只是未完成驗證程序。此符號在建構期間可能不能使用同式符號連結,因此並不適合使用 |
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 輸出檔案是否可執行。 |