| // Copyright 2018 The Bazel Authors. All rights reserved. |
| // |
| // Licensed under the Apache License, Version 2.0 (the "License"); |
| // you may not use this file except in compliance with the License. |
| // You may obtain a copy of the License at |
| // |
| // http://www.apache.org/licenses/LICENSE-2.0 |
| // |
| // Unless required by applicable law or agreed to in writing, software |
| // distributed under the License is distributed on an "AS IS" BASIS, |
| // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| // See the License for the specific language governing permissions and |
| // limitations under the License. |
| |
| package com.google.devtools.build.lib.starlarkbuildapi; |
| |
| import com.google.common.collect.ImmutableList; |
| import com.google.devtools.build.docgen.annot.DocCategory; |
| import com.google.devtools.build.lib.cmdline.Label; |
| import com.google.devtools.build.lib.collect.nestedset.Depset; |
| import com.google.devtools.build.lib.collect.nestedset.Depset.TypeException; |
| import com.google.devtools.build.lib.starlarkbuildapi.core.StructApi; |
| import com.google.devtools.build.lib.starlarkbuildapi.core.TransitiveInfoCollectionApi; |
| import com.google.devtools.build.lib.starlarkbuildapi.platform.ConstraintValueInfoApi; |
| import com.google.devtools.build.lib.starlarkbuildapi.platform.ExecGroupCollectionApi; |
| import com.google.devtools.build.lib.starlarkbuildapi.platform.ToolchainContextApi; |
| import javax.annotation.Nullable; |
| import net.starlark.java.annot.Param; |
| import net.starlark.java.annot.ParamType; |
| import net.starlark.java.annot.StarlarkBuiltin; |
| import net.starlark.java.annot.StarlarkMethod; |
| import net.starlark.java.eval.Dict; |
| import net.starlark.java.eval.EvalException; |
| import net.starlark.java.eval.NoneType; |
| import net.starlark.java.eval.Sequence; |
| import net.starlark.java.eval.StarlarkThread; |
| import net.starlark.java.eval.StarlarkValue; |
| import net.starlark.java.eval.Structure; |
| import net.starlark.java.eval.Tuple; |
| |
| /** Interface for a context object given to rule implementation functions. */ |
| @StarlarkBuiltin( |
| name = "ctx", |
| category = DocCategory.BUILTIN, |
| doc = |
| "A context object that is passed to the implementation function for a rule or aspect. It" |
| + " provides access to the information and methods needed to analyze the current" |
| + " target.<p>In particular, it lets the implementation function access the current" |
| + " target's label, attributes, configuration, and the providers of its dependencies." |
| + " It has methods for declaring output files and the actions that produce" |
| + " them.<p>Context objects essentially live for the duration of the call to the" |
| + " implementation function. It is not useful to access these objects outside of their" |
| + " associated function. See the <a" |
| + " href='https://bazel.build/extending/rules#implementation_function'>Rules page</a>" |
| + " for more information.") |
| public interface StarlarkRuleContextApi<ConstraintValueT extends ConstraintValueInfoApi> |
| extends StarlarkValue { |
| |
| String EXECUTABLE_DOC = |
| "A <code>struct</code> containing executable files defined in <a" |
| + " href='../toplevel/attr.html#label'>label type attributes</a> marked as <a" |
| + " href='../toplevel/attr.html#label.executable'><code>executable=True</code></a>. The" |
| + " struct fields correspond to the attribute names. Each value in the struct is either a" |
| + " <a href='../builtins/File.html'><code>File</code></a> or <code>None</code>. If an" |
| + " optional attribute is not specified in the rule then the corresponding struct value" |
| + " is <code>None</code>. If a label type is not marked as <code>executable=True</code>," |
| + " no corresponding struct field is generated. <a " |
| + "href=\"https://github.com/bazelbuild/examples/blob/main/rules/actions_run/execute.bzl\">See" |
| + " example of use</a>."; |
| String FILES_DOC = |
| "A <code>struct</code> containing files defined in <a" |
| + " href='../toplevel/attr.html#label'>label</a> or <a" |
| + " href='../toplevel/attr.html#label_list'>label list</a> type attributes. The struct" |
| + " fields correspond to the attribute names. The struct values are <code>list</code> of" |
| + " <a href='../builtins/File.html'><code>File</code></a>s. It is a shortcut for:<pre" |
| + " class=language-python>[f for t in ctx.attr.<ATTR> for f in t.files]</pre> In" |
| + " other words, use <code>files</code> to access the <a" |
| + " href=\"https://bazel.build/extending/rules#requesting_output_files\"> default" |
| + " outputs</a> of a dependency. <a" |
| + " href=\"https://github.com/bazelbuild/examples/blob/main/rules/depsets/foo.bzl\">See" |
| + " example of use</a>."; |
| String FILE_DOC = |
| "A <code>struct</code> containing files defined in <a" |
| + " href='../toplevel/attr.html#label'>label type attributes</a> marked as <a" |
| + " href='../toplevel/attr.html#label.allow_single_file'><code>allow_single_file</code></a>." |
| + " The struct fields correspond to the attribute names. The struct value is always a <a" |
| + " href='../builtins/File.html'><code>File</code></a> or <code>None</code>. If an" |
| + " optional attribute is not specified in the rule then the corresponding struct value" |
| + " is <code>None</code>. If a label type is not marked as" |
| + " <code>allow_single_file</code>, no corresponding struct field is generated. It is a" |
| + " shortcut for:<pre class=language-python>list(ctx.attr.<ATTR>.files)[0]</pre>In" |
| + " other words, use <code>file</code> to access the (singular) <a" |
| + " href=\"https://bazel.build/extending/rules#requesting_output_files\">default" |
| + " output</a> of a dependency. <a" |
| + " href=\"https://github.com/bazelbuild/examples/blob/main/rules/expand_template/hello.bzl\">See" |
| + " example of use</a>."; |
| String ATTR_DOC = |
| "A struct to access the values of the <a" |
| + " href='https://bazel.build/extending/rules#attributes'>attributes</a>. The values are" |
| + " provided by the user (if not, a default value is used). The attributes of the struct" |
| + " and the types of their values correspond to the keys and values of the <a" |
| + " href='../globals/bzl.html#rule.attrs'><code>attrs</code> dict</a> provided to the <a" |
| + " href='../globals/bzl.html#rule'><code>rule</code> function</a>. <a " |
| + "href=\"https://github.com/bazelbuild/examples/blob/main/rules/attributes/printer.bzl\">See" |
| + " example of use</a>."; |
| String SPLIT_ATTR_DOC = |
| "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."; |
| String OUTPUTS_DOC = |
| "A pseudo-struct containing all the predeclared output files, represented by <a" |
| + " href='../builtins/File.html'><code>File</code></a> objects. See the <a" |
| + " href='https://bazel.build/extending/rules#files'>Rules page</a> for more information" |
| + " and examples.<p>This field does not exist on aspect contexts, since aspects do not" |
| + " have predeclared outputs.<p>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.<ul><li>" |
| + " If the rule declares an <a" |
| + " href='../globals/bzl.html#rule.outputs'><code>outputs</code></a> dict, then for every" |
| + " entry in the dict, there is a field whose name is the key and whose value is the" |
| + " corresponding <code>File</code>.<li>For every attribute of type <a" |
| + " href='../toplevel/attr.html#output'><code>attr.output</code></a> 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" |
| + " <code>File</code>; otherwise the field value is <code>None</code>.<li>For every" |
| + " attribute of type <a" |
| + " href='../toplevel/attr.html#output_list'><code>attr.output_list</code></a> that the" |
| + " rule declares, there is a field whose name is the attribute's name. The field value" |
| + " is a list of <code>File</code> 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.<li><b>(Deprecated)</b> If the rule is marked <a" |
| + " href='../globals/bzl.html#rule.executable'><code>executable</code></a> or <a" |
| + " href='../globals/bzl.html#rule.test'><code>test</code></a>, there is a field named" |
| + " <code>\"executable\"</code>, which is the default executable. It is recommended that" |
| + " instead of using this, you pass another file (either predeclared or not) to the" |
| + " <code>executable</code> arg of <a" |
| + " href='../providers/DefaultInfo.html'><code>DefaultInfo</code></a>.</ul>"; |
| |
| @StarlarkMethod( |
| name = "actions", |
| structField = true, |
| doc = "Contains methods for declaring output files and the actions that produce them.") |
| StarlarkActionFactoryApi actions(); |
| |
| @StarlarkMethod( |
| name = "super", |
| doc = "Experimental: Calls parent's implementation function and returns its providers", |
| useStarlarkThread = true) |
| Object callParent(StarlarkThread thread) throws EvalException, InterruptedException; |
| |
| @StarlarkMethod( |
| name = "created_actions", |
| doc = |
| "For rules with <a" |
| + " href=\"../globals/bzl.html#rule._skylark_testable\">_skylark_testable</a> set to" |
| + " <code>True</code>, this returns an <code>Actions</code> provider representing all" |
| + " actions created so far for the current rule. For all other rules, returns" |
| + " <code>None</code>. 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. <br/><br/>This is intended to help write tests for rule-implementation" |
| + " helper functions, which may take in a <code>ctx</code> object and create actions" |
| + " on it.") |
| StarlarkValue createdActions() throws EvalException; |
| |
| @StarlarkMethod(name = "attr", structField = true, doc = ATTR_DOC) |
| StructApi getAttr() throws EvalException; |
| |
| @StarlarkMethod(name = "split_attr", structField = true, doc = SPLIT_ATTR_DOC) |
| StructApi getSplitAttr() throws EvalException; |
| |
| @StarlarkMethod(name = "executable", structField = true, doc = EXECUTABLE_DOC) |
| StructApi getExecutable() throws EvalException; |
| |
| @StarlarkMethod(name = "file", structField = true, doc = FILE_DOC) |
| StructApi getFile() throws EvalException; |
| |
| @StarlarkMethod(name = "files", structField = true, doc = FILES_DOC) |
| StructApi getFiles() throws EvalException; |
| |
| @StarlarkMethod( |
| name = "workspace_name", |
| structField = true, |
| doc = |
| "The name of the workspace, which is effectively the execution root name and runfiles" |
| + " prefix for the main repo. If <code>--enable_bzlmod</code> is on, this is the" |
| + " fixed string <code>_main</code>. Otherwise, this is the workspace name as defined" |
| + " in the WORKSPACE file.") |
| String getWorkspaceName() throws EvalException; |
| |
| @StarlarkMethod( |
| name = "label", |
| structField = true, |
| doc = "The label of the target currently being analyzed.") |
| Label getLabel() throws EvalException; |
| |
| @StarlarkMethod( |
| name = "fragments", |
| structField = true, |
| doc = "Allows access to configuration fragments in target configuration.") |
| FragmentCollectionApi getFragments() throws EvalException; |
| |
| @StarlarkMethod( |
| name = "configuration", |
| structField = true, |
| doc = |
| "The default configuration. See the <a href=\"../builtins/configuration.html\">" |
| + "configuration</a> type for more details.") |
| BuildConfigurationApi getConfiguration() throws EvalException; |
| |
| @StarlarkMethod( |
| name = "build_setting_value", |
| structField = true, |
| doc = |
| "Value of the build setting represented by the current target. If this isn't the context" |
| + " for an instance of a rule that sets the <a href=\"" |
| + "https://bazel.build/extending/config#rule-parameter\"><code>build_setting</code>" |
| + "</a> attribute, reading this is an error.") |
| Object getBuildSettingValue() throws EvalException; |
| |
| @StarlarkMethod( |
| name = "coverage_instrumented", |
| doc = |
| "Returns whether code coverage instrumentation should be generated when performing" |
| + " compilation actions for this rule or, if <code>target</code> is provided, the" |
| + " rule specified by that Target. (If a non-rule or a Starlark rule Target is" |
| + " provided, this returns False.) Checks if the sources of the current rule (if no" |
| + " Target is provided) or the sources of Target should be instrumented based on the" |
| + " --instrumentation_filter and --instrument_test_targets config settings. This" |
| + " differs from <code>coverage_enabled</code> in the <a" |
| + " href=\"../builtins/configuration.html\">configuration</a>, which notes whether" |
| + " coverage data collection is enabled for the entire run, but not whether a" |
| + " specific target should be instrumented.", |
| parameters = { |
| @Param( |
| name = "target", |
| allowedTypes = { |
| @ParamType(type = TransitiveInfoCollectionApi.class), |
| @ParamType(type = NoneType.class), |
| }, |
| defaultValue = "None", |
| named = true, |
| doc = "A Target specifying a rule. If not provided, defaults to the current rule.") |
| }) |
| boolean instrumentCoverage(Object targetUnchecked) throws EvalException; |
| |
| @StarlarkMethod( |
| name = "features", |
| structField = true, |
| doc = |
| "The set of features that are explicitly enabled by the user for this rule. " |
| + "<a href=\"https://github.com/bazelbuild/examples/blob/main/rules/" |
| + "features/rule.bzl\">See example of use</a>.") |
| ImmutableList<String> getFeatures() throws EvalException; |
| |
| @StarlarkMethod( |
| name = "disabled_features", |
| structField = true, |
| doc = "The set of features that are explicitly disabled by the user for this rule.") |
| ImmutableList<String> getDisabledFeatures() throws EvalException; |
| |
| @StarlarkMethod( |
| name = "bin_dir", |
| structField = true, |
| doc = "The root corresponding to bin directory.") |
| FileRootApi getBinDirectory() throws EvalException; |
| |
| @StarlarkMethod( |
| name = "genfiles_dir", |
| structField = true, |
| doc = "The root corresponding to genfiles directory.") |
| FileRootApi getGenfilesDirectory() throws EvalException; |
| |
| @StarlarkMethod(name = "outputs", structField = true, doc = OUTPUTS_DOC) |
| Structure outputs() throws EvalException; |
| |
| @StarlarkMethod( |
| name = "rule", |
| structField = true, |
| doc = |
| "Rule attributes descriptor for the rule that the aspect is applied to." |
| + " Only available in aspect implementation functions.") |
| StarlarkAttributesCollectionApi rule() throws EvalException; |
| |
| @StarlarkMethod( |
| name = "aspect_ids", |
| structField = true, |
| doc = |
| "A list of ids for all aspects applied to the target." |
| + " Only available in aspect implementation functions.") |
| ImmutableList<String> aspectIds() throws EvalException; |
| |
| @StarlarkMethod( |
| name = "var", |
| structField = true, |
| doc = "Dictionary (String to String) of configuration variables.") |
| Dict<String, String> var() throws EvalException, InterruptedException; |
| |
| @StarlarkMethod( |
| name = "toolchains", |
| structField = true, |
| doc = "Toolchains for the default exec group of this rule.") |
| ToolchainContextApi toolchains() throws EvalException; |
| |
| @StarlarkMethod( |
| name = "target_platform_has_constraint", |
| doc = "Returns true if the given constraint value is part of the current target platform.", |
| parameters = { |
| @Param( |
| name = "constraintValue", |
| positional = true, |
| named = false, |
| doc = "The constraint value to check the target platform against.") |
| }) |
| boolean targetPlatformHasConstraint(ConstraintValueT constraintValue); |
| |
| @StarlarkMethod( |
| name = "exec_groups", |
| structField = true, |
| doc = |
| "A collection of the execution groups available for this rule," |
| + " indexed by their name. Access with <code>ctx.exec_groups[name_of_group]</code>.") |
| ExecGroupCollectionApi execGroups() throws EvalException; |
| |
| @StarlarkMethod( |
| name = "tokenize", |
| doc = "Splits a shell command into a list of tokens.", |
| // TODO(cparsons): Look into flipping this to true. |
| documented = false, |
| parameters = { |
| @Param( |
| name = "option", |
| positional = true, |
| named = false, |
| doc = "The string to split."), |
| }) |
| Sequence<String> tokenize(String optionString) throws EvalException; |
| |
| @StarlarkMethod( |
| name = "check_placeholders", |
| documented = false, |
| parameters = { |
| @Param(name = "template", positional = true, named = false, doc = "The template."), |
| @Param( |
| name = "allowed_placeholders", |
| positional = true, |
| named = false, |
| allowedTypes = { |
| @ParamType(type = Sequence.class, generic1 = String.class), |
| }, |
| doc = "The allowed placeholders."), |
| }) |
| boolean checkPlaceholders(String template, Sequence<?> allowedPlaceholders) // <String> |
| throws EvalException; |
| |
| @StarlarkMethod( |
| name = "expand_make_variables", |
| doc = |
| "<b>Deprecated.</b> Use <a href=\"../builtins/ctx.html#var\">ctx.var</a> to access the" |
| + " variables instead.<br>Returns a string after expanding all references to \"Make" |
| + " variables\". The variables must have the following format:" |
| + " <code>$(VAR_NAME)</code>. Also, <code>$$VAR_NAME</code> expands to" |
| + " <code>$VAR_NAME</code>. Examples:<pre class=language-python>\n" |
| + "ctx.expand_make_variables(\"cmd\", \"$(MY_VAR)\", {\"MY_VAR\": \"Hi\"}) # ==" |
| + " \"Hi\"\n" |
| + "ctx.expand_make_variables(\"cmd\", \"$$PWD\", {}) # == \"$PWD\"\n" |
| + "</pre>Additional variables may come from other places, such as configurations." |
| + " Note that this function is experimental.", |
| parameters = { |
| @Param( |
| name = "attribute_name", |
| positional = true, |
| named = false, |
| doc = "The attribute name. Used for error reporting."), |
| @Param( |
| name = "command", |
| positional = true, |
| named = false, |
| doc = |
| "The expression to expand. It can contain references to " + "\"Make variables\"."), |
| @Param( |
| name = "additional_substitutions", |
| positional = true, |
| named = false, |
| doc = "Additional substitutions to make beyond the default make variables."), |
| }) |
| String expandMakeVariables( |
| String attributeName, |
| String command, |
| final Dict<?, ?> additionalSubstitutions) // <String, String> |
| throws EvalException, InterruptedException; |
| |
| @StarlarkMethod( |
| name = "info_file", |
| structField = true, |
| documented = true, |
| doc = |
| "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.") |
| FileApi getStableWorkspaceStatus() throws InterruptedException, EvalException; |
| |
| @StarlarkMethod( |
| name = "version_file", |
| structField = true, |
| documented = true, |
| doc = |
| "The file that is used to hold the volatile workspace status for the " |
| + "current build request. See documentation for --workspace_status_command " |
| + "for more information.") |
| FileApi getVolatileWorkspaceStatus() throws InterruptedException, EvalException; |
| |
| @StarlarkMethod( |
| name = "build_file_path", |
| structField = true, |
| documented = true, |
| doc = |
| "Deprecated: Use <code>ctx.label.package + '/BUILD'</code>. " |
| + "The path to the BUILD file for this rule, relative to the source root.") |
| String getBuildFileRelativePath() throws EvalException; |
| |
| @StarlarkMethod( |
| name = "expand_location", |
| doc = |
| "Expands all <code>$(location ...)</code> templates in the given string by replacing " |
| + "<code>$(location //x)</code> 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 <code>targets</code>. " |
| + "<br/><br/>" |
| // |
| + "<code>$(location ...)</code> will cause an error if the referenced target has " |
| + "multiple outputs. In this case, please use <code>$(locations ...)</code> since it " |
| + "produces a space-separated list of output paths. It can be safely used for a " |
| + "single output file, too." |
| + "<br/><br/>" |
| // |
| + "This function is useful to let the user specify a command in a BUILD file (like" |
| + " for <code>genrule</code>). In other cases, it is often better to manipulate" |
| + " labels directly.", |
| parameters = { |
| @Param(name = "input", doc = "String to be expanded."), |
| @Param( |
| name = "targets", |
| allowedTypes = { |
| @ParamType(type = Sequence.class, generic1 = TransitiveInfoCollectionApi.class) |
| }, |
| defaultValue = "[]", |
| named = true, |
| doc = "List of targets for additional lookup information."), |
| @Param( |
| name = "short_paths", |
| named = true, |
| positional = false, |
| defaultValue = "False", |
| documented = false), |
| }, |
| allowReturnNones = true, |
| useStarlarkThread = true) |
| @Nullable |
| String expandLocation( |
| String input, Sequence<?> targets, boolean shortPaths, StarlarkThread thread) |
| throws EvalException; |
| |
| @StarlarkMethod( |
| name = "runfiles", |
| doc = "Creates a runfiles object.", |
| parameters = { |
| @Param( |
| name = "files", |
| allowedTypes = {@ParamType(type = Sequence.class, generic1 = FileApi.class)}, |
| named = true, |
| defaultValue = "[]", |
| doc = "The list of files to be added to the runfiles."), |
| // TODO(bazel-team): If we have a memory efficient support for lazy list containing |
| // NestedSets we can remove this and just use files = [file] + list(set) |
| // Also, allow empty set for init |
| @Param( |
| name = "transitive_files", |
| allowedTypes = { |
| @ParamType(type = Depset.class, generic1 = FileApi.class), |
| @ParamType(type = NoneType.class), |
| }, |
| defaultValue = "None", |
| named = true, |
| doc = |
| "The (transitive) set of files to be added to the runfiles. The depset should " |
| + "use the <code>default</code> order (which, as the name implies, is the " |
| + "default)."), |
| @Param( |
| name = "collect_data", |
| defaultValue = "False", |
| named = true, |
| doc = |
| "<b>Use of this parameter is not recommended. See <a" |
| + " href=\"https://bazel.build/extending/rules#runfiles\">runfiles" |
| + " guide</a></b>. <p>Whether to collect the data runfiles from the" |
| + " dependencies in srcs, data and deps attributes."), |
| @Param( |
| name = "collect_default", |
| defaultValue = "False", |
| named = true, |
| doc = |
| "<b>Use of this parameter is not recommended. See <a" |
| + " href=\"https://bazel.build/extending/rules#runfiles\">runfiles" |
| + " guide</a></b>. <p>Whether to collect the default runfiles from the" |
| + " dependencies in srcs, data and deps attributes."), |
| @Param( |
| name = "symlinks", |
| defaultValue = "{}", |
| named = true, |
| allowedTypes = { |
| @ParamType(type = Dict.class), |
| @ParamType(type = Depset.class, generic1 = SymlinkEntryApi.class) |
| }, |
| doc = |
| "Either a SymlinkEntry depset or the map of symlinks to be added to the runfiles." |
| + " Symlinks are always added under the main workspace's runfiles directory" |
| + " (e.g. <code><runfiles_root>/_main/<symlink_path></code>, <b>not</b>" |
| + " the directory corresponding to the current target's repository. See <a" |
| + " href=\"https://bazel.build/extending/rules#runfiles_symlinks\">Runfiles" |
| + " symlinks</a> in the rules guide."), |
| @Param( |
| name = "root_symlinks", |
| defaultValue = "{}", |
| named = true, |
| allowedTypes = { |
| @ParamType(type = Dict.class), |
| @ParamType(type = Depset.class, generic1 = SymlinkEntryApi.class) |
| }, |
| doc = |
| "Either a SymlinkEntry depset or a map of symlinks to be added to the runfiles. See" |
| + " <a href=\"https://bazel.build/extending/rules#runfiles_symlinks\">Runfiles" |
| + " symlinks</a> in the rules guide."), |
| @Param( |
| name = "skip_conflict_checking", |
| defaultValue = "False", |
| named = true, |
| positional = false, |
| documented = false) |
| }, |
| useStarlarkThread = true) |
| RunfilesApi runfiles( |
| Sequence<?> files, |
| Object transitiveFiles, |
| Boolean collectData, |
| Boolean collectDefault, |
| Object symlinks, |
| Object rootSymlinks, |
| boolean skipConflictChecking, |
| StarlarkThread thread) |
| throws EvalException, TypeException; |
| |
| @StarlarkMethod( |
| name = "resolve_command", |
| doc = |
| "<i>(Experimental)</i> Returns a tuple <code>(inputs, command, empty list)</code>" |
| + " of the list of resolved inputs and the argv list for the resolved command" |
| + " both of them suitable for passing as the same-named arguments of the " |
| + " <code>ctx.action</code> method.<br/><b>Note for Windows users</b>: this method" |
| + " requires Bash (MSYS2). Consider using <code>resolve_tools()</code> instead (if" |
| + " that fits your needs). The empty list is returned as the third member of the" |
| + " tuple for backwards compatibility.", |
| parameters = { |
| @Param( |
| name = "command", |
| defaultValue = "''", |
| named = true, |
| positional = false, |
| doc = "Command to resolve."), |
| @Param( |
| name = "attribute", |
| allowedTypes = { |
| @ParamType(type = String.class), |
| @ParamType(type = NoneType.class), |
| }, |
| defaultValue = "None", |
| named = true, |
| positional = false, |
| doc = "Name of the associated attribute for which to issue an error, or None."), |
| @Param( |
| name = "expand_locations", |
| defaultValue = "False", |
| named = true, |
| positional = false, |
| doc = |
| "Shall we expand $(location) variables? See <a" |
| + " href=\"#expand_location\">ctx.expand_location()</a> for more details."), |
| @Param( |
| name = "make_variables", |
| allowedTypes = { |
| @ParamType(type = Dict.class), // <String, String> |
| @ParamType(type = NoneType.class), |
| }, |
| defaultValue = "None", |
| named = true, |
| positional = false, |
| doc = "Make variables to expand, or None."), |
| @Param( |
| name = "tools", |
| defaultValue = "[]", |
| allowedTypes = { |
| @ParamType(type = Sequence.class, generic1 = TransitiveInfoCollectionApi.class), |
| }, |
| named = true, |
| positional = false, |
| doc = "List of tools (list of targets)."), |
| @Param( |
| name = "label_dict", |
| defaultValue = "{}", |
| named = true, |
| positional = false, |
| doc = |
| "Dictionary of resolved labels and the corresponding list of Files " |
| + "(a dict of Label : list of Files)."), |
| @Param( |
| name = "execution_requirements", |
| defaultValue = "{}", |
| named = true, |
| positional = false, |
| doc = |
| "Information for scheduling the action to resolve this command. See " |
| + "<a href=\"${link common-definitions#common.tags}\">tags</a> " |
| + "for useful keys."), |
| }, |
| useStarlarkThread = true) |
| Tuple resolveCommand( |
| String command, |
| Object attributeUnchecked, |
| Boolean expandLocations, |
| Object makeVariablesUnchecked, |
| Sequence<?> tools, |
| Dict<?, ?> labelDictUnchecked, |
| Dict<?, ?> executionRequirementsUnchecked, |
| StarlarkThread thread) |
| throws EvalException, InterruptedException; |
| |
| @StarlarkMethod( |
| name = "resolve_tools", |
| doc = |
| "Returns a tuple <code>(inputs, empty list)</code> of the depset of resolved inputs" |
| + " required to run the tools, suitable for passing as the same-named argument of the" |
| + " <code>ctx.actions.run</code> and <code>ctx.actions.run_shell</code> methods." |
| + " <br/><br/>In contrast to <code>ctx.resolve_command</code>, this method does not" |
| + " require that Bash be installed on the machine, so it's suitable for rules built" |
| + " on Windows. The empty list is returned as part of the tuple for backward" |
| + " compatibility.", |
| parameters = { |
| @Param( |
| name = "tools", |
| defaultValue = "[]", |
| allowedTypes = { |
| @ParamType(type = Sequence.class, generic1 = TransitiveInfoCollectionApi.class) |
| }, |
| named = true, |
| positional = false, |
| doc = "List of tools (list of targets)."), |
| }) |
| Tuple resolveTools(Sequence<?> tools) throws EvalException; |
| } |
