Documentation

ctx

The context of the rule containing helper functions and information about attributes, depending targets and outputs. You get a ctx object as an argument to the implementation function when you create a rule.

action

None ctx.action(outputs, inputs=[], executable=None, arguments=[], mnemonic=None, command=None, progress_message=None, use_default_shell_env=False, env=None, execution_requirements=None, input_manifests=None)

Creates an action that runs an executable or a shell command. You must specify either command or executable. Actions and genrules are very similar, but have different use cases. Actions are used inside rules, and genrules are used inside macros. Genrules also have make variable expansion.

Parameters

Parameter Description
outputs

sequence of Files

list of the output files of the action.

inputs

sequence of Files

list of the input files of the action.

executable

File; or PathFragment; or None

the executable file to be called by the action.

arguments

sequence of strings

command line arguments of the action.

mnemonic

string

a one-word description of the action, e.g. CppCompile or GoLink.

command

string; or sequence of strings; or None

shell command to execute. It is usually preferable to use executable instead. Arguments are available with $1, $2, etc.

progress_message

string

progress message to show to the user during the build, e.g. "Compiling foo.cc to create foo.o".

use_default_shell_env

bool

whether the action should use the built in shell environment or not.

env

dict

sets the dictionary of environment variables.

execution_requirements

dict

information for scheduling the action. See tags for useful keys.

input_manifests

sequence

(Experimental) sets the input runfiles metadata; they are typically generated by resolve_command.

aspect_ids

List ctx.aspect_ids

Returns a list ids for all aspects applied to the target. Only available in aspect implementation functions.

attr

struct ctx.attr

A struct to access the values of the attributes. The values are provided by the user (if not, a default value is used).

bin_dir

root ctx.bin_dir

The root corresponding to bin directory.

build_file_path

string ctx.build_file_path

Returns path to the BUILD file for this rule, relative to the source root.

configuration

configuration ctx.configuration

Returns the default configuration. See the configuration type for more details.

coverage_instrumented

bool ctx.coverage_instrumented(target=None)

Returns whether code coverage instrumentation should be generated when performing compilation actions for this rule or, if target is provided, the rule specified by that Target. (If a non-rule Target is provided, this returns False.) This differs from coverage_enabled in the configuration, which notes whether coverage data collection is enabled for the entire run, but not whether a specific target should be instrumented.

Parameters

Parameter Description
target

Target

A Target specifying a rule. If not provided, defaults to the current rule.

created_actions

SkylarkValue ctx.created_actions()

For rules with _skylark_testable set to True, this returns an Actions provider representing all actions created so far for the current rule. For all other rules, returns None. Note that the provider is not updated when subsequent actions are created, so you will have to call this function again if you wish to inspect them.

This is intended to help write tests for rule-implementation helper functions, which may take in a ctx object and create actions on it.

default_provider

provider ctx.default_provider

Deprecated. Use DefaultInfo instead.

empty_action

None ctx.empty_action(mnemonic, inputs=[])

Creates an empty action that neither executes a command nor produces any output, but that is useful for inserting 'extra actions'.

Parameters

Parameter Description
mnemonic

string

a one-word description of the action, e.g. CppCompile or GoLink.

inputs

sequence of Files

list of the input files of the action.

executable

struct ctx.executable

A struct containing executable files defined in label type attributes marked as executable=True. The struct fields correspond to the attribute names. Each value in the struct is either 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 executable=True, no corresponding struct field is generated.

expand_location

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

Expands all $(location ...) templates in the given string by replacing $(location //x) with the path of the output file of target //x. Expansion only works for labels that point to direct dependencies of this rule or that are explicitly listed in the optional argument targets.

$(location ...) will cause an error if the referenced target has multiple outputs. In this case, please use $(locations ...) since it produces a space-separated list of output paths. It can be safely used for a single output file, too.

Parameters

Parameter Description
input

string

string to be expanded.

targets

sequence of Targets

list of targets for additional lookup information.

expand_make_variables

string ctx.expand_make_variables()

Returns a string after expanding all references to "Make variables". The variables must have the following format: $(VAR_NAME). Also, $$VAR_NAME expands to $VAR_NAME. Parameters:
  • The name of the attribute (string). It's only used for error reporting.
  • The expression to expand (string). It can contain references to "Make variables".
  • A mapping of additional substitutions (dict of string : string).
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.

features

List ctx.features

Returns the set of features that are enabled for this rule.

file

struct ctx.file

A struct containing files defined in label type attributes marked as single_file=True. 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 single_file=True, no corresponding struct field is generated. It is a shortcut for:
list(ctx.attr.<ATTR>.files)[0]

file_action

None ctx.file_action(output, content, executable=False)

Creates a file write action.

Parameters

Parameter Description
output

File

the output file.

content

string

the contents of the file.

executable

bool

whether the output file should be executable (default is False).

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. If an optional attribute is not specified in the rule, an empty list is generated. It is a shortcut for:
[f for t in ctx.attr.<ATTR> for f in t.files]

fragments

fragments ctx.fragments

Allows access to configuration fragments in target configuration.

genfiles_dir

root ctx.genfiles_dir

The root corresponding to genfiles directory.

host_configuration

configuration ctx.host_configuration

Returns the host configuration. See the configuration type for more details.

host_fragments

fragments ctx.host_fragments

Allows access to configuration fragments in host configuration.

label

Label ctx.label

The label of this rule.

new_file(filename)

File ctx.new_file(filename)

Creates a file object with the given filename, in the current package. Does not actually create a file on the file system, just declares that some action will do so. You must create an action that generates the file. If the file should be visible to other rules, declare a rule output instead when possible. Doing so enables Bazel to associate a label with the file that rules can refer to (allowing finer dependency control) instead of referencing the whole rule.

Parameters

Parameter Description
filename

string

The path of the new file, relative to the current package.

new_file(sibling_file, basename)

File ctx.new_file(sibling_file, basename)

Creates a new file object in the same directory as the original file. Does not actually create a file on the file system, just declares that some action will do so. You must create an action that generates the file. If the file should be visible to other rules, declare a rule output instead when possible. Doing so enables Bazel to associate a label with the file that rules can refer to (allowing finer dependency control) instead of referencing the whole rule.

Parameters

Parameter Description
sibling_file

File

A file that lives in the same directory as the newly created file.

basename

string

The base name of the newly created file.

outputs

struct ctx.outputs

A struct containing all the output files. The struct is generated the following way:
  • If the rule is marked as executable=True the struct has an "executable" field with the rules default executable file value.
  • For every entry in the rule's outputs dict an attr is generated with the same name and the corresponding file value.
  • For every output type attribute a struct attribute is generated with the same name and the corresponding file value or None, if no value is specified in the rule.
  • For every output list type attribute a struct attribute is generated with the same name and corresponding list of files value (an empty list if no value is specified in the rule).

resolve_command

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

(Experimental) Returns a tuple (inputs, command, input_manifests) of the list of resolved inputs, the argv list for the resolved command, and the runfiles metadatarequired to run the command, all of them suitable for passing as the same-named arguments of the ctx.action method.

Parameters

Parameter Description
command

string

command to resolve.

attribute

string

name of the associated attribute for which to issue an error, or None.

expand_locations

bool

shall we expand $(location) variables? See ctx.expand_location() for more details.

make_variables

dict

make variables to expand, or None.

tools

sequence of Targets

list of tools (list of targets).

label_dict

dict

dictionary of resolved labels and the corresponding list of Files (a dict of Label : list of Files)

execution_requirements

dict

information for scheduling the action to resolve this command. See tags for useful keys.

rule

rule_attributes ctx.rule

Returns rule attributes descriptor for the rule that aspect is applied to. Only available in aspect implementation functions.

runfiles

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

Creates a runfiles object.

Parameters

Parameter Description
files

sequence of Files

The list of files to be added to the runfiles.

transitive_files

depset of Files

The (transitive) set of files to be added to the runfiles.

collect_data

bool

Whether to collect the data runfiles from the dependencies in srcs, data and deps attributes.

collect_default

bool

Whether to collect the default runfiles from the dependencies in srcs, data and deps attributes.

dict

The map of symlinks to be added to the runfiles, prefixed by workspace name.

dict

The map of symlinks to be added to the runfiles.

split_attr

struct ctx.split_attr

A struct to access the values of attributes with split configurations. If the attribute is a label list, the value of split_attr is a dict of the keys of the split (as strings) to lists of the ConfiguredTargets in that branch of the split. If the attribute is a label, then the value of split_attr is a dict of the keys of the split (as strings) to single ConfiguredTargets. Attributes with split configurations still appear in the attr struct, but their values will be single lists with all the branches of the split merged together.

template_action

Action ctx.template_action(template, output, substitutions, executable=False)

Creates a template expansion action.

Parameters

Parameter Description
template

File

the template file, which is a UTF-8 encoded text file.

output

File

the output file, which is a UTF-8 encoded text file.

substitutions

dict

substitutions to make when expanding the template.

executable

bool

whether the output file should be executable (default is False).

var

dict ctx.var

Dictionary (String to String) of configuration variables.

workspace_name

string ctx.workspace_name

Returns the workspace name as defined in the WORKSPACE file.