提供建立動作的函式模組。使用 ctx.actions
存取此模組。
成員
- args
- declare_directory
- declare_file
- declare_symlink
- do_nothing
- expand_template
- run
- run_shell
- symlink
- template_dict
- write
args
Args actions.args()
declare_directory
File actions.declare_directory(filename, *, sibling=None)
Args.add_all()
在動作指令中展開目錄。只有一般檔案和目錄可納入 declare_directory 的展開內容。
參數
參數 | 說明 |
---|---|
filename
|
必要 如果未提供「sibling」,則為相對於目前套件的新目錄路徑。否則,檔案的基本名稱 (「兄弟」定義目錄)。 |
sibling
|
檔案或 None ;預設為 None 。 與新宣告的目錄位於同一目錄中的檔案。檔案必須位於目前的套件中。 |
declare_file
File actions.declare_file(filename, *, sibling=None)
sibling
,則檔案名稱與套件目錄相對關係,否則檔案會與 sibling
位於相同的目錄中。無法在目前套件外建立檔案。請注意,除了宣告檔案之外,您還必須另外建立可發出檔案的動作。建立該動作時,必須將傳回的 File
物件傳遞至動作的建構函式。
請注意,預先宣告的輸出檔案不需要 (也無法) 使用這個函式宣告。您可以改為從 ctx.outputs
取得其 File
物件。查看使用範例。
參數
參數 | 說明 |
---|---|
filename
|
必要 如果未提供「sibling」,則為新檔案相對於目前套件的路徑。否則,檔案的基本名稱 (由「同胞」決定目錄)。 |
sibling
|
File;或 None ;預設值為 None 。這是指與新建檔案位於相同目錄中的檔案。檔案必須位於目前的套件中。 |
declare_symlink
File actions.declare_symlink(filename, *, sibling=None)
參數
參數 | 說明 |
---|---|
filename
|
必要 如未提供同層級符號,則新符號連結的路徑 (相對於目前套件)。否則,檔案的基本名稱 (「兄弟」定義目錄)。 |
sibling
|
File 或 None ;預設為 None 。 與新宣告的符號連結位於同一個目錄中的檔案。 |
do_nothing
None
actions.do_nothing(mnemonic, inputs=[])
參數
參數 | 說明 |
---|---|
mnemonic
|
必要 動作的單字說明,例如 CppCompile 或 GoLink。 |
inputs
|
File 的 sequence;或 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
|
File 的序列;
必要 動作的輸出檔案清單。 |
inputs
|
File 或 depset 的序列;預設為 [] 。 動作的輸入檔案清單或 depset。 |
unused_inputs_list
|
File;或 None ;預設值為 None ,其中包含動作未使用的輸入清單。 這個檔案的內容 (通常是動作的其中一個輸出項目) 會對應至在整個動作執行期間未使用的輸入檔案清單。這些檔案中的任何變更,都不會影響動作的輸出。 |
executable
|
File;或 string;或 FilesToRunProvider;必要 動作要呼叫的可執行檔案。 |
tools
|
sequence 或 depset;預設為 unbound 。列出動作所需的任何工具,或 depset。工具是指含有額外執行檔的輸入內容,這些執行檔會自動提供給動作。提供清單時,可以是 Files、FilesToRunProvider 例項或 Files 的 depset 的異質集合。系統會自動新增清單中直接來自 ctx.executable 的檔案。提供的 depset 只能包含檔案。無論是哪種情況,在執行檔的 depset 中,檔案都不會與 ctx.executable 交叉參照。 |
arguments
|
sequence;預設值為 [] 。動作的指令列引數。必須是字串或 actions.args() 物件的清單。 |
mnemonic
|
字串或 None ;預設為 None 。 動作的單字說明,例如 CppCompile 或 GoLink。 |
progress_message
|
字串或 None ;預設為 None 。顯示在建構期間向使用者顯示的進度訊息,例如「Compiling foo.cc to create foo.o」。訊息可能包含 %{label} 、%{input} 或 %{output} 模式,這些模式會分別替換為標籤字串、第一個輸入內容或輸出路徑。偏好使用模式而非靜態字串,因為前者的效率較高。 |
use_default_shell_env
|
預設值為 False 動作是否應使用預設的 Shell 環境,其中包含幾個依作業系統而異的變數,以及透過 --action_env 設定的變數。如果 |
env
|
dict;或 None ;預設為 None 設定環境變數的字典。 如果 |
execution_requirements
|
dict;或 None ;
預設值為 None 用於排程動作的資訊。如需瞭解實用的鍵,請參閱「標記」。 |
input_manifests
|
sequence;或 None ;
預設值為 None (實驗功能) 會設定輸入執行檔中繼資料,這些資料通常是由 resolve_command 產生。 |
exec_group
|
字串或 None ;
預設為 None 在指定執行群組的執行平台上執行動作。如果沒有,則使用目標的預設執行平台。 |
shadowed_action
|
動作;預設為 None 。 使用指定的遮罩動作輸入內容和環境,執行動作,並將其加入動作的輸入內容清單和環境。動作環境可以覆寫任何遮蔽動作的環境變數。如果沒有,則只使用動作的輸入內容和指定環境。 |
resource_set
|
可呼叫;或 None ;預設值為 None 這個回呼函式會傳回資源集字典,用於在本機執行這個動作時預估在執行時間的資源用量。 這個函式會接受兩個位置引數:代表作業系統名稱的字串 (例如「osx」),以及代表動作輸入數量的整數。傳回的字典可能包含下列項目,而每個項目可能為浮點值或 int:
如果此參數設為 回呼必須是頂層 (不允許 lambda 和巢狀函式)。 |
toolchain
|
Label;或 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
|
File 的序列;
必要 動作的輸出檔案清單。 |
inputs
|
File 或 depset 的序列;預設為 [] 。 動作的輸入檔案清單或 depset。 |
tools
|
File 的序列,或 depset;預設為 unbound 。 列出動作所需的任何工具,或 depset。工具是包含額外執行檔案的輸入資料,系統會自動提供給動作使用。清單中可包含 Files 或 FilesToRunProvider 執行個體。 |
arguments
|
sequence;預設值為 [] 。動作的指令列引數。必須是字串或 actions.args() 物件的清單。Bazel 會將這個屬性中的元素做為引數傳遞至指令。指令可使用殼層變數替換 (例如 如果 |
mnemonic
|
字串或 None ;預設為 None 。 動作的單字說明,例如 CppCompile 或 GoLink。 |
command
|
字串;或 字串的字串序列;必須執行的 殼層指令。這可以是字串 (建議) 或字串序列 (已淘汰)。 如果 (已淘汰)如果 Bazel 會使用與 genrules 相同的殼層執行指令。 |
progress_message
|
字串或 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
|
字典或 None ;預設為 None 。用於排定動作的資訊。如需瞭解實用的鍵,請參閱「標記」。 |
input_manifests
|
sequence;或 None ;
預設值為 None (實驗功能) 會設定輸入執行檔中繼資料,這些資料通常是由 resolve_command 產生。 |
exec_group
|
字串或 None ;
預設為 None 在指定執行群組的執行平台上執行動作。如果沒有,則使用目標的預設執行平台。 |
shadowed_action
|
動作;
預設為 None 使用已新增至動作輸入清單的指定遮罩動作所發現的輸入內容,執行動作。如果沒有,則只會使用動作的輸入內容。 |
resource_set
|
可呼叫;或 None ;預設值為 None 。在本機執行時,可預估資源用量的回呼函式。請參閱 ctx.actions.run() 。 |
toolchain
|
Label;或 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
|
required 此動作的輸出內容。 |
target_file
|
File 或 None ;
預設為 None 輸出符號連結會指向的檔案。 |
target_path
|
字串;或 None ;預設為 None 輸出符號連結會指向的確切路徑。系統不會套用任何標準化或其他處理作業。 |
is_executable
|
預設值為 False 。 只能與 target_file 搭配使用,不能與 target_path 搭配使用。如果為 true,執行動作時,系統會檢查 target_file 的路徑,確認是否可執行,如果無法執行,系統會回報錯誤。將 is_executable 設為 False 並不表示目標無法執行,只是表示系統不會進行驗證。這項功能對 |
progress_message
|
字串或 None ;
預設為 None 。 在建構期間向使用者顯示的進度訊息。 |
template_dict
TemplateDict actions.template_dict()
write
None
actions.write(output, content, is_executable=False)
expand_template
。
參數
參數 | 說明 |
---|---|
output
|
必要 輸出檔案。 |
content
|
字串或 Args;
必要 檔案內容。可以是字串或 actions.args() 物件。 |
is_executable
|
預設為 False 是否應可執行輸出檔案。 |