字元

每日版本 · 9.0 · 8.5 · 8.4 · 8.3 · 8.2 · 7.7
傳遞至規則或層面實作函式的內容物件。可存取分析目前目標所需的資訊和方法。

具體來說，實作函式可藉此存取目前目標的標籤、屬性、設定，以及依附元件的供應商。這個類別提供的方法可宣告輸出檔案，以及產生這些檔案的動作。

基本上，內容物件的生命週期與實作函式的呼叫時間相同。在相關聯函式以外存取這些物件並無用處。詳情請參閱規則頁面。

成員

作業

actions ctx.actions

包含用於宣告輸出檔案的方法，以及產生這些檔案的動作。

aspect_ids

list ctx.aspect_ids

套用至目標的所有層面 ID 清單。僅適用於層面實作函式。

attr

struct ctx.attr

用來存取屬性值的 struct。這些值由使用者提供 (如未提供，則會使用預設值)。struct 的屬性和值的類型，對應於提供給 rule 函式的 attrs dict 的鍵和值。查看使用範例。

bin_dir

root ctx.bin_dir

對應至 bin 目錄的根目錄。

build_file_path

string ctx.build_file_path

已淘汰：請改用 ctx.label.package + '/BUILD'。這個規則的 BUILD 檔案路徑，相對於來源根目錄。

build_setting_value

unknown ctx.build_setting_value

代表目前目標的建構設定值。如果這不是設定 build_setting 屬性的規則執行個體的情境，讀取這項屬性會發生錯誤。

設定

configuration ctx.configuration

目前目標的建構設定。詳情請參閱「Starlark 設定類型」和設定說明文件。

coverage_instrumented

bool ctx.coverage_instrumented(target=None)

傳回為這項規則執行編譯動作時，是否應產生程式碼涵蓋率檢測程式碼；如果提供 target，則傳回該 Target 指定的規則。(如果提供非規則或 Starlark 規則的目標，則會傳回 False)。根據 --instrumentation_filter 和 --instrument_test_targets 設定，檢查目前規則的來源 (如果未提供目標) 或目標的來源是否應經過檢測。這與設定中的 coverage_enabled 不同，後者會記錄是否為整個執行階段啟用涵蓋率資料收集功能，但不會記錄是否應為特定目標插入檢測程式碼。

參數

參數 說明
target 目標；或 None； 預設為 None
指定規則的目標。如未提供，則預設為目前的規則。

created_actions

StarlarkValue ctx.created_actions()

如果規則的 _skylark_testable 設為 True，這會傳回 Actions 提供者，代表目前規則至今建立的所有動作。如果是其他規則，則會傳回 None。請注意，建立後續動作時，系統不會更新供應商，因此如要檢查供應商，請再次呼叫這個函式。

這項功能旨在協助編寫規則實作輔助函式的測試，這類函式可能會接收 ctx 物件，並對該物件建立動作。

disabled_features

list ctx.disabled_features

使用者為這項規則明確停用的功能集。

exec_groups

ExecGroupCollection ctx.exec_groups

這個規則的可用執行群組集合 (以名稱編列索引)。使用 ctx.exec_groups[name_of_group] 存取。

執行檔

struct ctx.executable

包含以 executable=True 標示的標籤類型屬性中定義的可執行檔。structStruct 欄位對應至屬性名稱。Struct 中的每個值都是 File 或 None。如果規則中未指定選填屬性，對應的 struct 值為 None。如果標籤類型未標示為 executable=True，系統就不會產生對應的 struct 欄位。查看使用範例。

expand_location

string ctx.expand_location(input, targets=[])

將指定字串中的所有 $(location ...) 範本展開，並將 $(location //x) 替換為目標 //x 的輸出檔案路徑。擴展功能僅適用於指向這項規則直接依附元件的標籤，或選用引數 targets 中明確列出的標籤。如果參照的目標有多個輸出內容，

$(location ...) 就會導致錯誤。在這種情況下，請使用 $(locations ...)，因為它會產生以空格分隔的輸出路徑清單。也可以安全地用於單一輸出檔案。

這項函式可讓使用者在 BUILD 檔案中指定指令 (例如 genrule)，在其他情況下，直接操控標籤通常會比較好。

參數

參數 說明
input string；必要
要擴充的字串。
targets sequence of Targets； 預設值為 []
額外查閱資訊的目標清單。這些項目會擴展如下：DefaultInfo.files 中的單一檔案目標會擴展至該檔案。如果已設定其他目標，且已啟用 --incompatible_locations_prefers_executable，這些目標會展開至 DefaultInfo.executable 檔案，否則會展開至 DefaultInfo.files。
可能會傳回 None。

expand_make_variables

string ctx.expand_make_variables(attribute_name, command, additional_substitutions)

已淘汰。請改用 ctx.var 存取變數。
展開「建立變數」的所有參照後，傳回字串。變數必須採用下列格式：$(VAR_NAME)。此外，$$VAR_NAME expands to $VAR_NAME. Examples:
ctx.expand_make_variables("cmd", "$(MY_VAR)", {"MY_VAR": "Hi"})  # == "Hi"
ctx.expand_make_variables("cmd", "$$PWD", {})  # == "$PWD"
Additional variables may come from other places, such as configurations. Note that this function is experimental.
                  
      
Parameters

      

        
          
          
        
        
          

            Parameter
            Description
          

        
        
                  

            
              attribute_name
            
            
                          string;
                                     required

                          The attribute name. Used for error reporting.
            		
          

                  

            
              command
            
            
                          string;
                                     required

                          The expression to expand. It can contain references to "Make variables".
            		
          

                  

            
              additional_substitutions
            
            
                          dict;
                                     required

                          Additional substitutions to make beyond the default make variables.
            		
          

                
      


        
features

        
list ctx.features


    The set of features that are explicitly enabled by the user for this rule. See example of use.

        
file

        
struct ctx.file


    A struct containing files defined in label type attributes marked as allow_single_file. The struct fields correspond to the attribute names. The struct value is always a File or None. If an optional attribute is not specified in the rule then the corresponding struct value is None. If a label type is not marked as allow_single_file, no corresponding struct field is generated. It is a shortcut for:
list(ctx.attr.<ATTR>.files)[0]
In other words, use file to access the (singular) default output of a dependency. See example of use.

        
files

        
struct ctx.files


    A struct containing files defined in label or label list type attributes. The struct fields correspond to the attribute names. The struct values are list of Files.  It is a shortcut for:
[f for t in ctx.attr.<ATTR> for f in t.files]
 In other words, use files to access the  default outputs of a dependency. See example of use.

        
fragments

        
fragments ctx.fragments


    Allows access to configuration fragments in target configuration.

        
genfiles_dir

        
root ctx.genfiles_dir


    The root corresponding to genfiles directory.

        
info_file

        
File ctx.info_file


    The file that is used to hold the non-volatile workspace status for the current build request. See documentation for --workspace_status_command for more information.

        
label

        
Label ctx.label


    The label of the target currently being analyzed.

        
outputs

        
structure ctx.outputs


    A pseudo-struct containing all the predeclared output files, represented by File objects. See the Rules page for more information and examples.
This field does not exist on aspect contexts, since aspects do not have predeclared outputs.
The fields of this object are defined as follows. It is an error if two outputs produce the same field name or have the same label.
  •  If the rule declares an outputs dict, then for every entry in the dict, there is a field whose name is the key and whose value is the corresponding File.
  • For every attribute of type attr.output that the rule declares, there is a field whose name is the attribute's name. If the target specified a label for that attribute, then the field value is the corresponding File; otherwise the field value is None.
  • For every attribute of type attr.output_list that the rule declares, there is a field whose name is the attribute's name. The field value is a list of File objects corresponding to the labels given for that attribute in the target, or an empty list if the attribute was not specified in the target.
  • (Deprecated) If the rule is marked executable or test, there is a field named "executable", which is the default executable. It is recommended that instead of using this, you pass another file (either predeclared or not) to the executable arg of DefaultInfo.


        
package_relative_label

        
Label ctx.package_relative_label(input)


    Converts the input string into a Label object, in the context of the package of the target currently being analyzed. If the input is already a Label, it is returned unchanged.
The result of this function is the same Label value as would be produced by passing the given string to a label-valued attribute of the rule and accessing the corresponding Label() 是因為 Label() 使用呼叫它的 .bzl 檔案套件內容，而不是目前正在分析的目標套件。這個函式的行為與 
native.package_relative_label() 相同，無法在規則或層面實作函式中使用。

                  
      
參數

      

        
          
          
        
        
          

            參數
            說明
          

        
        
                  

            
              input
            
            
                          string；或 Label；必要
輸入標籤字串或 Label 物件。如果傳遞 Label 物件，則會原封不動地傳回該物件。
            		
          

                
      


        
resolve_command

        
tuple ctx.resolve_command(*, command='', attribute=None, expand_locations=False, make_variables=None, tools=[], label_dict={}, execution_requirements={})


    (實驗功能) 傳回已解析輸入內容清單和已解析指令的 argv 清單的元組 (inputs, command, empty list)，兩者都適合做為 ctx.action 方法的同名引數傳遞。
Windows 使用者注意事項：這個方法需要 Bash (MSYS2)。建議改用 resolve_tools() (如果符合您的需求)。為保持回溯相容性，系統會以元組的第三個成員傳回空白清單。
                  
      
參數

      

        
          
          
        
        
          

            參數
            說明
          

        
        
                  

            
              command
            
            
                          string；預設值為 ''
要解析的指令。		
          

                  

            
              attribute
            
            
                          string；或 None；預設為 None
要發出錯誤的相關聯屬性名稱，或 None。		
          

                  

            
              expand_locations
            
            
                          bool；預設為 False
是否要展開 $(location) 變數？詳情請參閱 ctx.expand_location()。
            		
          

                  

            
              make_variables
            
            
                          dict 或 None；預設為 None
要展開的變數，或 None。		
          

                  

            
              tools
            
            
                          目標的序列；
                                     預設為 []

                          工具清單 (目標清單)。		
          

                  

            
              label_dict
            
            
                          dict；
預設為 {}

已解析標籤的字典和對應的檔案清單 (Label : list of Files 的字典)。		
          

                  

            
              execution_requirements
            
            
                          dict；預設為 {}

                          排定動作以解決此指令的資訊。如需實用鍵，請參閱標記。
            		
          

                
      


        
resolve_tools

        
tuple ctx.resolve_tools(*, tools=[])


    傳回執行工具所需的已解析輸入內容的 depset (inputs, empty list) 元組，適合做為 ctx.actions.run 和 ctx.actions.run_shell 方法的同名引數傳遞。

與 ctx.resolve_command 不同，這個方法不需要在電腦上安裝 Bash，因此適用於在 Windows 上建構的規則。為保持回溯相容性，系統會將空白清單做為元組的一部分傳回。
                  
      
參數

      

        
          
          
        
        
          

            參數
            說明
          

        
        
                  

            
              tools
            
            
                          目標的序列；
                                     預設為 []

                          工具清單 (目標清單)。		
          

                
      


        
規則

        
rule_attributes ctx.rule


    適用於套用層面的規則的規則屬性描述元。僅適用於層面實作函式。

        
runfiles

        
runfiles ctx.runfiles(files=[], transitive_files=None, collect_data=False, collect_default=False, symlinks={}, root_symlinks={})


    建立 Runfiles 物件。
                  
      
參數

      

        
          
          
        
        
          

            參數
            說明
          

        
        
                  

            
              files
            
            
                          File 的序列；
預設為 []

要新增至執行檔的檔案清單。
            		
          

                  

            
              transitive_files
            
            
                          depset 的 File；或 None；預設為 None
要新增至執行檔的 (遞移) 檔案集。depsset 應使用 default 順序 (顧名思義，這是預設順序)。
            		
          

                  

            
              collect_data
            
            
                          bool；預設值為 False

                          不建議使用這個參數。請參閱執行檔指南。
是否要從 srcs、data 和 deps 屬性的依附元件收集資料執行檔。
            

          

                  

            
              collect_default
            
            
                          bool；預設值為 False

                          不建議使用這個參數。請參閱執行檔指南。
是否要從 srcs、data 和 deps 屬性的依附元件收集預設執行檔。
            

          

                  

            
            
                          dict；或 SymlinkEntry 的 depset；預設為 {}
。要新增至執行檔的符號連結 depset 或符號連結對應。符號連結一律會新增至主要工作區的 runfiles 目錄 (例如 <runfiles_root>/_main/<symlink_path>，而非對應目前目標存放區的目錄)。請參閱規則指南中的「Runfiles symlinks」。
            		
          

                  

            
            
                          dict；或 depset 的 SymlinkEntry；
                                     預設為 {}

                          要新增至執行檔的 SymlinkEntry depset 或符號連結對應。請參閱規則指南中的「Runfiles symlinks」。
            		
          

                
      


        
split_attr

        
struct ctx.split_attr


    用來存取具有分割設定的屬性值的 struct。如果屬性是標籤清單，split_attr 的值就是鍵的 dict (以字串形式)，對應至該分支中 ConfiguredTargets 的清單。如果屬性是標籤，則 split_attr 的值是鍵的 dict (以字串形式) 至單一 ConfiguredTargets。具有分割設定的屬性仍會顯示在 attr 結構中，但其值會是單一清單，其中包含所有合併的分支。

        
超級

        
unknown ctx.super()


    實驗性：呼叫父項的實作函式並傳回其供應器

        
target_platform_has_constraint

        
bool ctx.target_platform_has_constraint(constraintValue)


    如果指定的限制值屬於目前的目標平台，則傳回 true。
                  
      
參數

      

        
          
          
        
        
          

            參數
            說明
          

        
        
                  

            
              constraintValue
            
            
                          ConstraintValueInfo;
                                     required

                          要用來檢查目標平台的限制值。
            		
          

                
      


        
工具鏈

        
ToolchainContext ctx.toolchains


    這項規則預設執行群組的工具鍊。

        
var

        
dict ctx.var


    設定變數的字典 (字串到字串)。

        
version_file

        
File ctx.version_file


    這個檔案用於保存目前建構要求的不穩定工作區狀態。詳情請參閱 --workspace_status_command 的說明文件。

        
workspace_name

        
string ctx.workspace_name


    工作區的名稱，也就是主要存放區的執行根名稱和執行檔前置字串。如果 --enable_bzlmod 為開啟狀態，則為固定字串 _main。否則，這就是 WORKSPACE 檔案中定義的工作區名稱。