in src/main/java/com/google/devtools/build/lib/starlarkbuildapi/StarlarkRuleFunctionsApi.java [180:462]
Object provider(String doc, Object fields, Object init, StarlarkThread thread)
throws EvalException;
@StarlarkMethod(
name = "rule",
doc =
"Creates a new rule, which can be called from a BUILD file or a macro to create targets."
+ "<p>Rules must be assigned to global variables in a .bzl file; the name of the "
+ "global variable is the rule's name."
+ "<p>Test rules are required to have a name ending in <code>_test</code>, while all "
+ "other rules must not have this suffix. (This restriction applies only to rules, "
+ "not to their targets.)",
parameters = {
@Param(
name = "implementation",
named = true,
doc =
"the Starlark function implementing this rule, must have exactly one parameter: "
+ "<a href=\"ctx.html\">ctx</a>. The function is called during the analysis "
+ "phase for each instance of the rule. It can access the attributes "
+ "provided by the user. It must create actions to generate all the declared "
+ "outputs."),
@Param(
name = "test",
named = true,
defaultValue = "False",
doc =
"Whether this rule is a test rule, that is, whether it may be the subject of a "
+ "<code>blaze test</code> command. All test rules are automatically "
+ "considered <a href='#rule.executable'>executable</a>; it is unnecessary "
+ "(and discouraged) to explicitly set <code>executable = True</code> for a "
+ "test rule. See the "
+ "<a href='../rules.$DOC_EXT#executable-rules-and-test-rules'>Rules page</a> "
+ "for more information."),
@Param(
name = "attrs",
allowedTypes = {
@ParamType(type = Dict.class),
@ParamType(type = NoneType.class),
},
named = true,
defaultValue = "None",
doc =
"dictionary to declare all the attributes of the rule. It maps from an attribute "
+ "name to an attribute object (see <a href=\"attr.html\">attr</a> module). "
+ "Attributes starting with <code>_</code> are private, and can be used to "
+ "add an implicit dependency on a label. The attribute <code>name</code> is "
+ "implicitly added and must not be specified. Attributes "
+ "<code>visibility</code>, <code>deprecation</code>, <code>tags</code>, "
+ "<code>testonly</code>, and <code>features</code> are implicitly added and "
+ "cannot be overridden. Most rules need only a handful of attributes. To "
+ "limit memory usage, the rule function imposes a cap on the size of attrs."),
// TODO(bazel-team): need to give the types of these builtin attributes
@Param(
name = "outputs",
allowedTypes = {
@ParamType(type = Dict.class),
@ParamType(type = NoneType.class),
@ParamType(type = StarlarkFunction.class) // a function defined in Starlark
},
named = true,
defaultValue = "None",
valueWhenDisabled = "None",
disableWithFlag = BuildLanguageOptions.INCOMPATIBLE_NO_RULE_OUTPUTS_PARAM,
doc =
"This parameter has been deprecated. Migrate rules to use"
+ " <code>OutputGroupInfo</code> or <code>attr.output</code> instead. <p>A"
+ " schema for defining predeclared outputs. Unlike <a"
+ " href='attr.html#output'><code>output</code></a> and <a"
+ " href='attr.html#output_list'><code>output_list</code></a> attributes, the"
+ " user does not specify the labels for these files. See the <a"
+ " href='../rules.$DOC_EXT#files'>Rules page</a> for more on predeclared"
+ " outputs.<p>The value of this argument is either a dictionary or a callback"
+ " function that produces a dictionary. The callback works similar to"
+ " computed dependency attributes: The function's parameter names are matched"
+ " against the rule's attributes, so for example if you pass <code>outputs ="
+ " _my_func</code> with the definition <code>def _my_func(srcs, deps):"
+ " ...</code>, the function has access to the attributes <code>srcs</code>"
+ " and <code>deps</code>. Whether the dictionary is specified directly or via"
+ " a function, it is interpreted as follows.<p>Each entry in the dictionary"
+ " creates a predeclared output where the key is an identifier and the value"
+ " is a string template that determines the output's label. In the rule's"
+ " implementation function, the identifier becomes the field name used to"
+ " access the output's <a href='File.html'><code>File</code></a> in <a"
+ " href='ctx.html#outputs'><code>ctx.outputs</code></a>. The output's label"
+ " has the same package as the rule, and the part after the package is"
+ " produced by substituting each placeholder of the form"
+ " <code>\"%{ATTR}\"</code> with a string formed from the value of the"
+ " attribute <code>ATTR</code>:<ul><li>String-typed attributes are"
+ " substituted verbatim.<li>Label-typed attributes become the part of the"
+ " label after the package, minus the file extension. For example, the label"
+ " <code>\"//pkg:a/b.c\"</code> becomes <code>\"a/b\"</code>.<li>Output-typed"
+ " attributes become the part of the label after the package, including the"
+ " file extension (for the above example, <code>\"a/b.c\"</code>).<li>All"
+ " list-typed attributes (for example, <code>attr.label_list</code>) used in"
+ " placeholders are required to have <i>exactly one element</i>. Their"
+ " conversion is the same as their non-list version"
+ " (<code>attr.label</code>).<li>Other attribute types may not appear in"
+ " placeholders.<li>The special non-attribute placeholders"
+ " <code>%{dirname}</code> and <code>%{basename}</code> expand to those parts"
+ " of the rule's label, excluding its package. For example, in"
+ " <code>\"//pkg:a/b.c\"</code>, the dirname is <code>a</code> and the"
+ " basename is <code>b.c</code>.</ul><p>In practice, the most common"
+ " substitution placeholder is <code>\"%{name}\"</code>. For example, for a"
+ " target named \"foo\", the outputs dict <code>{\"bin\":"
+ " \"%{name}.exe\"}</code> predeclares an output named <code>foo.exe</code>"
+ " that is accessible in the implementation function as"
+ " <code>ctx.outputs.bin</code>."),
@Param(
name = "executable",
named = true,
defaultValue = "False",
doc =
"Whether this rule is considered executable, that is, whether it may be the "
+ "subject of a <code>blaze run</code> command. See the "
+ "<a href='../rules.$DOC_EXT#executable-rules-and-test-rules'>Rules page</a> "
+ "for more information."),
@Param(
name = "output_to_genfiles",
named = true,
defaultValue = "False",
doc =
"If true, the files will be generated in the genfiles directory instead of the "
+ "bin directory. Unless you need it for compatibility with existing rules "
+ "(e.g. when generating header files for C++), do not set this flag."),
@Param(
name = "fragments",
allowedTypes = {@ParamType(type = Sequence.class, generic1 = String.class)},
named = true,
defaultValue = "[]",
doc =
"List of names of configuration fragments that the rule requires "
+ "in target configuration."),
@Param(
name = "host_fragments",
allowedTypes = {@ParamType(type = Sequence.class, generic1 = String.class)},
named = true,
defaultValue = "[]",
doc =
"List of names of configuration fragments that the rule requires "
+ "in host configuration."),
@Param(
name = "_skylark_testable",
named = true,
defaultValue = "False",
doc =
"<i>(Experimental)</i><br/><br/>"
+ "If true, this rule will expose its actions for inspection by rules that "
+ "depend on it via an <a href=\"globals.html#Actions\">Actions</a> "
+ "provider. The provider is also available to the rule itself by calling "
+ "<a href=\"ctx.html#created_actions\">ctx.created_actions()</a>."
+ "<br/><br/>"
+ "This should only be used for testing the analysis-time behavior of "
+ "Starlark rules. This flag may be removed in the future."),
@Param(
name = TOOLCHAINS_PARAM,
allowedTypes = {@ParamType(type = Sequence.class, generic1 = String.class)},
named = true,
defaultValue = "[]",
doc =
"If set, the set of toolchains this rule requires. Toolchains will be "
+ "found by checking the current platform, and provided to the rule "
+ "implementation via <code>ctx.toolchain</code>."),
@Param(
name = "incompatible_use_toolchain_transition",
defaultValue = "False",
named = true,
doc =
"If set, this rule will use the toolchain transition for toolchain dependencies."
+ " This is ignored if the --incompatible_use_toolchain_transition flag is"
+ " set."),
@Param(
name = "doc",
named = true,
defaultValue = "''",
doc =
"A description of the rule that can be extracted by documentation generating "
+ "tools."),
@Param(
name = "provides",
named = true,
positional = false,
defaultValue = "[]",
doc = PROVIDES_DOC),
@Param(
name = EXEC_COMPATIBLE_WITH_PARAM,
allowedTypes = {@ParamType(type = Sequence.class, generic1 = String.class)},
named = true,
positional = false,
defaultValue = "[]",
doc =
"A list of constraints on the execution platform that apply to all targets of "
+ "this rule type."),
@Param(
name = "analysis_test",
named = true,
positional = false,
defaultValue = "False",
doc =
"If true, then this rule is treated as an analysis test. <p>Note: Analysis test"
+ " rules are primarily defined using infrastructure provided in core Starlark"
+ " libraries. See <a href=\"../testing.html#for-testing-rules\">Testing</a>"
+ " for guidance. <p>If a rule is defined as an analysis test rule, it becomes"
+ " allowed to use configuration transitions defined using <a"
+ " href=\"#analysis_test_transition\">analysis_test_transition</a> on its"
+ " attributes, but opts into some restrictions: <ul><li>Targets of this rule"
+ " are limited in the number of transitive dependencies they may have."
+ " <li>The rule is considered a test rule (as if <code>test=True</code> were"
+ " set). This supercedes the value of <code>test</code></li> <li>The rule"
+ " implementation function may not register actions."
+ " Instead, it must register a pass/fail result via providing <a"
+ " href='AnalysisTestResultInfo.html'>AnalysisTestResultInfo</a>.</li></ul>"),
@Param(
name = "build_setting",
allowedTypes = {
@ParamType(type = BuildSettingApi.class),
@ParamType(type = NoneType.class),
},
defaultValue = "None",
named = true,
positional = false,
doc =
"If set, describes what kind of "
+ "<a href = '../config.$DOC_EXT#user-defined-build-settings'><code>build "
+ "setting</code></a> this rule is. See the "
+ "<a href='config.html'><code>config</code></a> module. If this is "
+ "set, a mandatory attribute named \"build_setting_default\" is automatically "
+ "added to this rule, with a type corresponding to the value passed in here."),
@Param(
name = "cfg",
defaultValue = "None",
named = true,
positional = false,
doc =
"If set, points to the configuration transition the rule will "
+ "apply to its own configuration before analysis."),
@Param(
name = "exec_groups",
allowedTypes = {
@ParamType(type = Dict.class),
@ParamType(type = NoneType.class),
},
named = true,
defaultValue = "None",
positional = false,
doc =
"Dict of execution group name (string) to <a"
+ " href='globals.html#exec_group'><code>exec_group</code>s</a>. If set,"
+ " allows rules to run actions on multiple execution platforms within a"
+ " single target. See <a href='../../exec-groups.html'>execution groups"
+ " documentation</a> for more info."),
@Param(
name = "compile_one_filetype",
defaultValue = "None",
allowedTypes = {
@ParamType(type = Sequence.class, generic1 = String.class),
@ParamType(type = NoneType.class),
},
named = true,
positional = false,
doc =
"Used by --compile_one_dependency: if multiple rules consume the specified file, "
+ "should we choose this rule over others."),
@Param(
name = "name",
named = true,
defaultValue = "None",
positional = false,
allowedTypes = {@ParamType(type = String.class), @ParamType(type = NoneType.class)},
doc =
"The name of this rule, as understood by Bazel and reported in contexts such as"
+ " logging, <code>native.existing_rule(...)[kind]</code>, and <code>bazel"
+ " query</code>. Usually this is the same as the Starlark identifier that gets"
+ " bound to this rule; for instance a rule called <code>foo_library</code>"
+ " would typically be declared as <code>foo_library = rule(...)</code> and"
+ " instantiated in a BUILD file as <code>foo_library(...)</code>.<p>If this"
+ " parameter is omitted, the rule's name is set to the name of the first"
+ " Starlark global variable to be bound to this rule within its declaring .bzl"
+ " module. Thus, <code>foo_library = rule(...)</code> need not specify this"
+ " parameter if the name is <code>foo_library</code>.<p>Specifying an explicit"
+ " name for a rule does not change where you are allowed to instantiate the"
+ " rule."),
},