提供用於建立動作的模組。使用 ctx.actions
存取這個模組。
成員
- 引數
- declare_directory
- declare_file
- declare_symlink
- do_nothing
- expand_template
- run
- run_shell
- 符號連結
- template_dict
- 撰寫
args
Args actions.args()傳回可用來建構記憶體效率指令列的 Args 物件。
declare_directory
File actions.declare_directory(filename, *, sibling=None)宣告規則或切面會在目前的套件中,以指定的名稱建立目錄。您必須建立可產生目錄的動作。無法直接從 Starlark 存取目錄的內容,但是可以在動作指令中使用
Args.add_all()
來展開內容。只有一般檔案和目錄可位於 dec_directory 的展開內容中。
參數
參數 | 說明 |
---|---|
filename
|
必要 如果不是「同層級」的新目錄路徑 (相對於目前套件)。否則,檔案的基礎名稱 (sibling 會定義目錄)。 |
sibling
|
檔案;或 None ;
預設值為 None 位於與新宣告目錄相同的目錄中的檔案。該檔案必須位於目前的套件中。 |
declare_file
File actions.declare_file(filename, *, sibling=None)宣告規則或切面建立具有指定檔案名稱的檔案。如果未指定
sibling
,則檔案名稱與套件目錄相對關係,否則檔案會與 sibling
位於相同的目錄中。無法在目前套件以外的地方建立檔案。請注意,除了宣告檔案外,您也必須個別建立會發送檔案的動作。建立該動作時,必須將傳回的 File
物件傳遞至動作的建構函式。
請注意,您不需要使用這個函式來宣告預先宣告的輸出檔案。您可以改為從 ctx.outputs
取得其 File
物件。查看使用範例。
參數
參數 | 說明 |
---|---|
filename
|
必要 如果不是「同層級」的新檔案路徑 (相對於目前套件)。否則,檔案的基本名稱 (「ibling」會決定目錄)。 |
sibling
|
檔案;或 None ;
預設值為 None 位於與新建檔案相同的目錄中的檔案。該檔案必須位於目前的套件中。 |
declare_symlink
File actions.declare_symlink(filename, *, sibling=None)宣告該規則或切面將在目前套件中建立具有指定名稱的符號連結。您必須建立會產生此符號連結的動作。Bazel 絕對不會解除參照這個符號連結,而是會完整地轉移至沙箱或遠端執行程式。目前不支援樹狀結構構件中的符號連結。
參數
參數 | 說明 |
---|---|
filename
|
必要 如果不是「同層級」的新符號連結路徑 (相對於目前套件)。否則,檔案的基礎名稱 (sibling 會定義目錄)。 |
sibling
|
檔案;或 None ;
預設值為 None 檔案與新宣告的符號連結位於同一個目錄中。 |
do_nothing
None
actions.do_nothing(mnemonic, inputs=[])
建立空白動作,既不是執行指令,也不會產生任何輸出,但這對於插入「額外動作」很有用。
參數
參數 | 說明 |
---|---|
mnemonic
|
必要 動作的單字說明,例如 CppCompile 或 GoLink。 |
inputs
|
檔案的序列;或 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
|
預設值為 {} 擴充範本時替代字元。 |
is_executable
|
預設值為 False 輸出檔案是否應執行。 |
computed_substitutions
|
TemplateDict;
預設值為 unbound 擴充範本時替代字元。 |
得分
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
|
檔案的序列;
必要 動作的輸出檔案清單。 |
inputs
|
檔案的序列;或 depset;
預設值為 [] 可列出或解碼動作的輸入檔案。 |
unused_inputs_list
|
檔案;或 None ;
預設值為 None 此檔案包含動作未使用的輸入項目清單。 這個檔案的內容 (通常是動作的輸出內容之一) 會對應至整個動作執行期間未使用的輸入檔案清單。這些檔案中的任何變更,都不會影響動作的輸出。 |
executable
|
檔案;或 string;或 FilesToRunProvider;
必要 要由動作呼叫的可執行檔。 |
tools
|
sequence;或 depset;
預設值為 unbound 列出或去除動作所需的任何工具。工具是包含額外執行檔案的輸入資料,系統會自動提供給動作使用。提供清單時,可能會構成異質的 Files、FileToRunProvider 例項或 Files 的 Depset。如果檔案也列在清單中,且來自 ctx.executable 檔案,系統就會自動新增其執行檔。如果提供 Depset,則其中只能含有 Files,在這兩種情況下, depset 中的檔案都不會針對 runfiles 交叉參照 ctx.executable。 |
arguments
|
sequence;
預設值為 [] 動作的指令列引數。必須是字串或 actions.args() 物件的清單。
|
mnemonic
|
string;或 None ;
預設值為 None 動作的單字說明,例如 CppCompile 或 GoLink。 |
progress_message
|
string;或 None ;
預設值為 None 建構期間向使用者顯示的進度訊息,例如「Compiling foo.cc to create foo.o」。訊息可能包含 %{label} 、%{input} 或 %{output} 模式,這些模式會分別替換成標籤字串、首次輸入或輸出的路徑。偏好使用模式而非靜態字串,因為前者的效率較高。
|
use_default_shell_env
|
預設值為 False 動作是否應使用預設的殼層環境,其中包含幾個 OS 相依變數,以及透過 --action_env 設定的變數。如果 |
env
|
dict;或 None ;
預設值為 None 設定環境變數的字典。 如果 |
execution_requirements
|
dict;或 None ;
預設值為 None 排定動作時程的資訊。如需實用索引鍵的標記,請參閱標記。 |
input_manifests
|
sequence;或 None ;
預設值為 None (實驗功能) 會設定輸入執行檔案中繼資料;通常是由 resolve_command 產生 |
exec_group
|
string;或 None ;
預設值為 None 在指定 exec 群組的執行平台上執行動作。如果沒有,則會使用目標的預設執行平台。 |
shadowed_action
|
行動
預設值為 None 這個外掛程式能使用指定覆蓋動作的輸入內容和動作至動作的輸入清單和環境來執行這項動作。動作環境可以覆寫任何覆蓋動作的環境變數。如果沒有,則只會使用動作的輸入內容和給定環境。 |
resource_set
|
可呼叫;或 None ;
預設值為 None 傳回資源集字典的回呼函式,用於在本機執行這個動作時,預估執行時間的資源用量。 這個函式接受兩個位置引數:一個代表 OS 名稱的字串 (例如「osx」),以及一個整數,代表該動作的輸入項目數量。傳回的字典可能包含下列項目,而每個項目可能為浮點值或 int:
如果此參數設為 回呼必須是頂層 (不允許 lambda 和巢狀函式)。 |
toolchain
|
標籤;或 string;或 None ;
預設值為 unbound 此動作所用執行檔或工具的工具鍊類型。你必須設定這個參數,動作會在正確的執行平台上執行。 目前免人工管理,但建議您在使用工具鍊時設定這項工具,因為之後的 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=unbound)
建立會執行殼層指令的動作。查看使用範例。
參數
參數 | 說明 |
---|---|
outputs
|
檔案的序列;
必要 動作的輸出檔案清單。 |
inputs
|
檔案的序列;或 depset;
預設值為 [] 可列出或解碼動作的輸入檔案。 |
tools
|
檔案的序列;或 depset;
預設值為 unbound 列出或去除動作所需的任何工具。工具是包含額外執行檔案的輸入資料,系統會自動提供給動作使用。清單中可包含 Files 或 FilesToRunProvider 執行個體。 |
arguments
|
sequence;
預設值為 [] 動作的指令列引數。必須是字串或 actions.args() 物件的清單。Bazel 會將這個屬性中的元素做為引數傳送至指令。此指令可以使用殼層變數替代機制 (例如 如果 |
mnemonic
|
string;或 None ;
預設值為 None 動作的單字說明,例如 CppCompile 或 GoLink。 |
command
|
string;字串的序列;
必要 要執行的殼層指令該字串可以是字串 (建議) 或一系列字串 (已淘汰)。 如果 (已淘汰) 如果 Bazel 會使用與 genrules 相同的殼層來執行指令。 |
progress_message
|
string;或 None ;
預設值為 None 建構期間向使用者顯示的進度訊息,例如「Compiling foo.cc to create foo.o」。訊息可能包含 %{label} 、%{input} 或 %{output} 模式,這些模式會分別替換成標籤字串、首次輸入或輸出的路徑。偏好使用模式而非靜態字串,因為前者的效率較高。
|
use_default_shell_env
|
預設值為 False 動作是否應使用預設的殼層環境,其中包含幾個 OS 相依變數,以及透過 --action_env 設定的變數。如果 |
env
|
dict;或 None ;
預設值為 None 設定環境變數的字典。 如果 |
execution_requirements
|
dict;或 None ;
預設值為 None 排定動作時程的資訊。如需實用索引鍵的標記,請參閱標記。 |
input_manifests
|
sequence;或 None ;
預設值為 None (實驗功能) 會設定輸入執行檔案中繼資料;通常是由 resolve_command 產生 |
exec_group
|
string;或 None ;
預設值為 None 在指定 exec 群組的執行平台上執行動作。如果沒有,則會使用目標的預設執行平台。 |
shadowed_action
|
行動
預設值為 None 這個外掛程式能使用已新增至動作輸入清單的特定遭覆蓋動作的偵測到輸入項目,執行此動作。如果沒有,則只會使用動作的輸入內容。 |
resource_set
|
可呼叫;或 None ;
預設值為 None 在本機執行時,用於估算資源用量的回呼函式。請見 ctx.actions.run() 。
|
toolchain
|
標籤;或 string;或 None ;
預設值為 unbound 此動作所用執行檔或工具的工具鍊類型。你必須設定這個參數,動作會在正確的執行平台上執行。 目前免人工管理,但建議您在使用工具鍊時設定這項工具,因為之後的 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
|
檔案;或 None ;
預設值為 None 輸出符號連結指向的檔案。 |
target_path
|
string;或 None ;
預設值為 None 輸出符號連結指向的確切路徑。系統不會套用正規化或其他處理程序。 |
is_executable
|
預設值為 False 只能與 target_file 搭配使用,無法使用 target_path 。如為 true,則在執行動作時,系統會檢查 target_file 的路徑確認是否可執行;如果沒有,則會回報錯誤。如果將 is_executable 設為 False,不表示目標無法執行,只是不會進行驗證。這項功能對 |
progress_message
|
string;或 None ;
預設值為 None 建構期間要向使用者顯示的進度訊息。 |
template_dict
TemplateDict actions.template_dict()傳回 TemplateDict 物件,用於擴充記憶體效率範本。
write
None
actions.write(output, content, is_executable=False)
建立檔案寫入動作。執行動作時,它會將指定內容寫入檔案。此方法用於透過分析階段中可用的資訊產生檔案。如果檔案較大且含有大量靜態內容,建議使用 expand_template
。
參數
參數 | 說明 |
---|---|
output
|
必要 輸出檔案。 |
content
|
string;或 Args;
必要 檔案內容可以是字串或 actions.args() 物件。
|
is_executable
|
預設值為 False 輸出檔案是否應執行。 |