提供建立動作的函式模組。使用 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」,則為新符號連結的路徑,相對於目前套件。否則為檔案的基礎名稱 (「ibling」定義了目錄)。 |
sibling
|
File;或 None ;預設值為 None 。檔案與新宣告的符號連結位於相同目錄中。 |
do_nothing
None
actions.do_nothing(mnemonic, inputs=[])
參數
參數 | 說明 |
---|---|
mnemonic
|
必要 動作的單字說明,例如 CppCompile 或 GoLink。 |
inputs
|
File 或 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
|
字典或 None ;預設為 None 。用於排定動作的資訊。如需瞭解實用的鍵,請參閱「標記」。 |
input_manifests
|
sequence;或 None ;預設值為 None (實驗功能) 會設定輸入執行檔案的中繼資料,而這些中繼資料通常由 resolve_command 產生。 |
exec_group
|
字串或 None ;
預設為 None 在指定執行群組的執行平台上執行動作。如果沒有,則會使用目標的預設執行平台。 |
shadowed_action
|
動作;預設為 None 使用新增至動作的輸入清單和環境的特定遭覆蓋動作的輸入內容和環境,執行此動作。動作環境可以覆寫任何遮蔽動作的環境變數。如果沒有,則只使用動作的輸入內容和指定環境。 |
resource_set
|
可呼叫;或 None ;預設值為 None 這個回呼函式會傳回資源集字典,用於在本機執行這個動作時預估在執行時間的資源用量。 這個函式會接受兩個位置引數:代表作業系統名稱的字串 (例如「osx」),以及代表動作輸入數量的整數。傳回的字典可能包含下列項目,每個項目可能是浮點值或整數:
如果這個參數設為 回呼必須是頂層 (不允許 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」的 sequence;必要 動作的輸出檔案清單。 |
inputs
|
File 或 depset 的序列;預設為 [] 。 動作的輸入檔案清單或 depset。 |
tools
|
File 的序列,或 depset;預設為 unbound 。 列出動作所需的任何工具,或 depset。工具是指含有額外執行檔的輸入內容,這些執行檔會自動提供給動作。清單中可包含 Files 或 FilesToRunProvider 執行個體。 |
arguments
|
sequence;預設值為 [] 。動作的指令列引數。必須是字串或 actions.args() 物件的清單。Bazel 會將這個屬性中的元素做為引數傳送至指令。此指令可以使用殼層變數替代機制 (例如 如果 |
mnemonic
|
字串或 None ;預設為 None 。 動作的單字說明,例如 CppCompile 或 GoLink。 |
command
|
string; 或 string 的 sequence;必要 要執行的殼層指令。這可以是字串 (建議) 或字串序列 (已淘汰)。 如果 (已淘汰)如果 Bazel 會使用與 genrules 相同的殼層執行指令。 |
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
|
字典或 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
|
string;或 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 是否應可執行輸出檔案。 |