| // 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.skylarkbuildapi; |
| |
| import com.google.common.collect.ImmutableList; |
| import com.google.devtools.build.lib.cmdline.Label; |
| import com.google.devtools.build.lib.skylarkbuildapi.core.ProviderApi; |
| import com.google.devtools.build.lib.skylarkbuildapi.core.StructApi; |
| import com.google.devtools.build.lib.skylarkbuildapi.core.TransitiveInfoCollectionApi; |
| import com.google.devtools.build.lib.skylarkbuildapi.platform.ConstraintValueInfoApi; |
| import com.google.devtools.build.lib.skylarkbuildapi.platform.ToolchainContextApi; |
| import com.google.devtools.build.lib.skylarkinterface.Param; |
| import com.google.devtools.build.lib.skylarkinterface.ParamType; |
| import com.google.devtools.build.lib.skylarkinterface.SkylarkCallable; |
| import com.google.devtools.build.lib.skylarkinterface.SkylarkModule; |
| import com.google.devtools.build.lib.skylarkinterface.SkylarkModuleCategory; |
| import com.google.devtools.build.lib.syntax.ClassObject; |
| import com.google.devtools.build.lib.syntax.Depset; |
| import com.google.devtools.build.lib.syntax.Dict; |
| import com.google.devtools.build.lib.syntax.EvalException; |
| import com.google.devtools.build.lib.syntax.NoneType; |
| import com.google.devtools.build.lib.syntax.Sequence; |
| import com.google.devtools.build.lib.syntax.StarlarkSemantics.FlagIdentifier; |
| import com.google.devtools.build.lib.syntax.StarlarkThread; |
| import com.google.devtools.build.lib.syntax.StarlarkValue; |
| import com.google.devtools.build.lib.syntax.Tuple; |
| import javax.annotation.Nullable; |
| |
| /** Interface for a context object given to rule implementation functions. */ |
| @SkylarkModule( |
| name = "ctx", |
| category = SkylarkModuleCategory.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='../rules.$DOC_EXT#implementation-function'>Rules page</a> for more " |
| + "information.") |
| public interface SkylarkRuleContextApi<ConstraintValueT extends ConstraintValueInfoApi> |
| extends StarlarkValue { |
| |
| String DOC_NEW_FILE_TAIL = |
| "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 Blaze" |
| + " to associate a label with the file that rules can refer to (allowing finer" |
| + " dependency control) instead of referencing the whole rule."; |
| String EXECUTABLE_DOC = |
| "A <code>struct</code> containing executable files defined in <a " |
| + "href='attr.html#label'>label type attributes</a> marked as <a " |
| + "href='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='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/master/rules/actions_run/" |
| + "execute.bzl\">See example of use</a>."; |
| String FILES_DOC = |
| "A <code>struct</code> containing files defined in <a href='attr.html#label'>label</a>" |
| + " or <a href='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='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=\"../rules.$DOC_EXT#requesting-output-files\">default outputs</a> of a" |
| + " dependency. <a" |
| + " href=\"https://github.com/bazelbuild/examples/blob/master/rules/depsets/foo.bzl\">See" |
| + " example of use</a>."; |
| String FILE_DOC = |
| "A <code>struct</code> containing files defined in <a href='attr.html#label'>label type" |
| + " attributes</a> marked as <a" |
| + " href='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='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=\"../rules.$DOC_EXT#requesting-output-files\">default output</a> of a" |
| + " dependency. <a" |
| + " href=\"https://github.com/bazelbuild/examples/blob/master/rules/expand_template/hello.bzl\">See" |
| + " example of use</a>."; |
| String ATTR_DOC = |
| "A struct to access the values of the <a href='../rules.$DOC_EXT#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.html#rule.attrs'><code>attrs</code> dict</a> provided to the <a " |
| + "href='globals.html#rule'><code>rule</code> function</a>. <a " |
| + "href=\"https://github.com/bazelbuild/examples/blob/master/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='File.html'><code>File</code></a> objects. See the " |
| + "<a href='../rules.$DOC_EXT#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.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='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='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.html#rule.executable'>" |
| + "<code>executable</code></a> or <a href='globals.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='DefaultInfo.html'><code>DefaultInfo</code></a>." |
| + "</ul>"; |
| |
| @SkylarkCallable( |
| name = "default_provider", |
| structField = true, |
| doc = "Deprecated. Use <a href=\"DefaultInfo.html\">DefaultInfo</a> instead.") |
| ProviderApi getDefaultProvider(); |
| |
| @SkylarkCallable( |
| name = "actions", |
| structField = true, |
| doc = "Contains methods for declaring output files and the actions that produce them.") |
| SkylarkActionFactoryApi actions(); |
| |
| @SkylarkCallable( |
| name = "created_actions", |
| doc = |
| "For rules with <a href=\"globals.html#rule._skylark_testable\">_skylark_testable</a>" |
| + " set to <code>True</code>, this returns an <a" |
| + " href=\"globals.html#Actions\">Actions</a> 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; |
| |
| @SkylarkCallable(name = "attr", structField = true, doc = ATTR_DOC) |
| StructApi getAttr() throws EvalException; |
| |
| @SkylarkCallable(name = "split_attr", structField = true, doc = SPLIT_ATTR_DOC) |
| StructApi getSplitAttr() throws EvalException; |
| |
| @SkylarkCallable(name = "executable", structField = true, doc = EXECUTABLE_DOC) |
| StructApi getExecutable() throws EvalException; |
| |
| @SkylarkCallable(name = "file", structField = true, doc = FILE_DOC) |
| StructApi getFile() throws EvalException; |
| |
| @SkylarkCallable(name = "files", structField = true, doc = FILES_DOC) |
| StructApi getFiles() throws EvalException; |
| |
| @SkylarkCallable( |
| name = "workspace_name", |
| structField = true, |
| doc = "Returns the workspace name as defined in the WORKSPACE file.") |
| String getWorkspaceName() throws EvalException; |
| |
| @SkylarkCallable( |
| name = "label", |
| structField = true, |
| doc = "The label of the target currently being analyzed.") |
| Label getLabel() throws EvalException; |
| |
| @SkylarkCallable( |
| name = "fragments", |
| structField = true, |
| doc = "Allows access to configuration fragments in target configuration.") |
| FragmentCollectionApi getFragments() throws EvalException; |
| |
| @SkylarkCallable( |
| name = "host_fragments", |
| structField = true, |
| doc = "Allows access to configuration fragments in host configuration.") |
| FragmentCollectionApi getHostFragments() throws EvalException; |
| |
| @SkylarkCallable( |
| name = "configuration", |
| structField = true, |
| doc = |
| "Returns the default configuration. See the <a href=\"configuration.html\">" |
| + "configuration</a> type for more details.") |
| BuildConfigurationApi getConfiguration() throws EvalException; |
| |
| @SkylarkCallable( |
| name = "host_configuration", |
| structField = true, |
| doc = |
| "Returns the host configuration. See the <a href=\"configuration.html\">" |
| + "configuration</a> type for more details.") |
| BuildConfigurationApi getHostConfiguration() throws EvalException; |
| |
| @SkylarkCallable( |
| name = "build_setting_value", |
| structField = true, |
| enableOnlyWithFlag = FlagIdentifier.EXPERIMENTAL_BUILD_SETTING_API, |
| doc = |
| "<b>Experimental. This field is experimental and subject to change at any time. Do not " |
| + "depend on it.</b> <p>Returns the value of the build setting that is represented " |
| + "by the current target. It is an error to access this field for rules that do not " |
| + "set the <code>build_setting</code> attribute in their rule definition.") |
| Object getBuildSettingValue() throws EvalException; |
| |
| @SkylarkCallable( |
| 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=\"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", |
| type = TransitiveInfoCollectionApi.class, |
| defaultValue = "None", |
| noneable = true, |
| named = true, |
| doc = "A Target specifying a rule. If not provided, defaults to the current rule.") |
| }) |
| boolean instrumentCoverage(Object targetUnchecked) throws EvalException; |
| |
| @SkylarkCallable( |
| name = "features", |
| structField = true, |
| doc = "Returns the set of features that are explicitly enabled by the user for this rule.") |
| ImmutableList<String> getFeatures() throws EvalException; |
| |
| @SkylarkCallable( |
| name = "disabled_features", |
| structField = true, |
| doc = "Returns the set of features that are explicitly disabled by the user for this rule.") |
| ImmutableList<String> getDisabledFeatures() throws EvalException; |
| |
| @SkylarkCallable( |
| name = "bin_dir", |
| structField = true, |
| doc = "The root corresponding to bin directory.") |
| FileRootApi getBinDirectory() throws EvalException; |
| |
| @SkylarkCallable( |
| name = "genfiles_dir", |
| structField = true, |
| doc = "The root corresponding to genfiles directory.") |
| FileRootApi getGenfilesDirectory() throws EvalException; |
| |
| @SkylarkCallable(name = "outputs", structField = true, doc = OUTPUTS_DOC) |
| ClassObject outputs() throws EvalException; |
| |
| @SkylarkCallable( |
| name = "rule", |
| structField = true, |
| doc = |
| "Returns rule attributes descriptor for the rule that aspect is applied to." |
| + " Only available in aspect implementation functions.") |
| SkylarkAttributesCollectionApi rule() throws EvalException; |
| |
| @SkylarkCallable( |
| name = "aspect_ids", |
| structField = true, |
| doc = |
| "Returns a list ids for all aspects applied to the target." |
| + " Only available in aspect implementation functions.") |
| ImmutableList<String> aspectIds() throws EvalException; |
| |
| @SkylarkCallable( |
| name = "var", |
| structField = true, |
| doc = "Dictionary (String to String) of configuration variables.") |
| Dict<String, String> var() throws EvalException; |
| |
| @SkylarkCallable( |
| name = "toolchains", |
| structField = true, |
| doc = "Toolchains required for this rule.") |
| ToolchainContextApi toolchains() throws EvalException; |
| |
| @SkylarkCallable( |
| 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, |
| type = ConstraintValueInfoApi.class, |
| doc = "The constraint value to check the target platform against.") |
| }) |
| boolean targetPlatformHasConstraint(ConstraintValueT constraintValue); |
| |
| @SkylarkCallable( |
| 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, |
| type = String.class, |
| doc = "The string to split."), |
| }) |
| Sequence<String> tokenize(String optionString) throws EvalException; |
| |
| @SkylarkCallable( |
| name = "expand", |
| doc = |
| "Expands all references to labels embedded within a string for all files using a mapping " |
| + "from definition labels (i.e. the label in the output type attribute) to files. " |
| + "Deprecated.", |
| // TODO(cparsons): Look into flipping this to true. |
| documented = false, |
| parameters = { |
| @Param( |
| name = "expression", |
| positional = true, |
| named = false, |
| type = String.class, |
| doc = "The string expression to expand."), |
| @Param( |
| name = "files", |
| positional = true, |
| named = false, |
| type = Sequence.class, |
| doc = "The list of files."), |
| @Param( |
| name = "label_resolver", |
| positional = true, |
| named = false, |
| type = Label.class, |
| doc = "The label resolver."), |
| }) |
| String expand( |
| @Nullable String expression, |
| Sequence<?> artifacts, // <FileT> |
| Label labelResolver) |
| throws EvalException; |
| |
| @SkylarkCallable( |
| name = "new_file", |
| doc = |
| "DEPRECATED. Use <a href=\"actions.html#declare_file\">ctx.actions.declare_file</a>. <br>" |
| + "Creates a file object. There are four possible signatures to this method:<br><ul>" |
| + "" |
| + "<li>new_file(filename): Creates a file object with the given filename in the " |
| + "current package.</li>" |
| + "" |
| + "<li>new_file(file_root, filename): Creates a file object with the given " |
| + "filename under the given file root.</li>" |
| + "" |
| + "<li>new_file(sibling_file, filename): Creates a file object in the same " |
| + "directory as the given sibling file.</li>" |
| + "" |
| + "<li>new_file(file_root, sibling_file, suffix): Creates a file object with same " |
| + "base name of the sibling_file but with different given suffix, under the given " |
| + "file root.</li></ul> <br>" |
| + DOC_NEW_FILE_TAIL, |
| parameters = { |
| @Param( |
| name = "var1", |
| allowedTypes = { |
| @ParamType(type = String.class), |
| @ParamType(type = FileRootApi.class), |
| @ParamType(type = FileApi.class), |
| }, |
| doc = ""), |
| @Param( |
| name = "var2", |
| allowedTypes = { |
| @ParamType(type = String.class), |
| @ParamType(type = FileApi.class), |
| }, |
| defaultValue = "unbound", |
| doc = ""), |
| @Param( |
| name = "var3", |
| allowedTypes = { |
| @ParamType(type = String.class), |
| }, |
| defaultValue = "unbound", |
| doc = "") |
| }) |
| FileApi newFile(Object var1, Object var2, Object var3) throws EvalException; |
| |
| @SkylarkCallable( |
| name = "experimental_new_directory", |
| documented = false, |
| parameters = { |
| @Param(name = "name", type = String.class), |
| @Param( |
| name = "sibling", |
| type = FileApi.class, |
| defaultValue = "None", |
| noneable = true, |
| named = true) |
| }) |
| FileApi newDirectory(String name, Object siblingArtifactUnchecked) throws EvalException; |
| |
| @SkylarkCallable( |
| name = "check_placeholders", |
| documented = false, |
| parameters = { |
| @Param( |
| name = "template", |
| positional = true, |
| named = false, |
| type = String.class, |
| doc = "The template."), |
| @Param( |
| name = "allowed_placeholders", |
| positional = true, |
| named = false, |
| type = Sequence.class, |
| doc = "The allowed placeholders."), |
| }) |
| boolean checkPlaceholders(String template, Sequence<?> allowedPlaceholders) // <String> |
| throws EvalException; |
| |
| @SkylarkCallable( |
| name = "expand_make_variables", |
| doc = |
| "<b>Deprecated.</b> Use <a href=\"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, |
| type = String.class, |
| doc = "The attribute name. Used for error reporting."), |
| @Param( |
| name = "command", |
| positional = true, |
| named = false, |
| type = String.class, |
| doc = |
| "The expression to expand. It can contain references to " + "\"Make variables\"."), |
| @Param( |
| name = "additional_substitutions", |
| positional = true, |
| named = false, |
| type = Dict.class, |
| doc = "Additional substitutions to make beyond the default make variables."), |
| }) |
| String expandMakeVariables( |
| String attributeName, |
| String command, |
| final Dict<?, ?> additionalSubstitutions) // <String, String> |
| throws EvalException; |
| |
| @SkylarkCallable( |
| name = "info_file", |
| structField = true, |
| documented = false, |
| doc = |
| "Returns the file that is used to hold the non-volatile workspace status for the " |
| + "current build request.") |
| FileApi getStableWorkspaceStatus() throws InterruptedException, EvalException; |
| |
| @SkylarkCallable( |
| name = "version_file", |
| structField = true, |
| documented = false, |
| doc = |
| "Returns the file that is used to hold the volatile workspace status for the " |
| + "current build request.") |
| FileApi getVolatileWorkspaceStatus() throws InterruptedException, EvalException; |
| |
| @SkylarkCallable( |
| name = "build_file_path", |
| structField = true, |
| documented = true, |
| doc = "Returns path to the BUILD file for this rule, relative to the source root.") |
| String getBuildFileRelativePath() throws EvalException; |
| |
| @SkylarkCallable( |
| name = "action", |
| doc = |
| "DEPRECATED. Use <a href=\"actions.html#run\">ctx.actions.run()</a> or" |
| + " <a href=\"actions.html#run_shell\">ctx.actions.run_shell()</a>. <br>" |
| + "Creates an action that runs an executable or a shell command." |
| + " You must specify either <code>command</code> or <code>executable</code>.\n" |
| + "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 = { |
| @Param( |
| name = "outputs", |
| type = Sequence.class, |
| generic1 = FileApi.class, |
| named = true, |
| positional = false, |
| doc = "List of the output files of the action."), |
| @Param( |
| name = "inputs", |
| allowedTypes = { |
| @ParamType(type = Sequence.class), |
| @ParamType(type = Depset.class), |
| }, |
| generic1 = FileApi.class, |
| defaultValue = "[]", |
| named = true, |
| positional = false, |
| doc = "List of the input files of the action."), |
| @Param( |
| name = "executable", |
| type = Object.class, |
| allowedTypes = { |
| @ParamType(type = FileApi.class), |
| @ParamType(type = String.class), |
| @ParamType(type = NoneType.class), |
| }, |
| noneable = true, |
| defaultValue = "None", |
| named = true, |
| positional = false, |
| doc = "The executable file to be called by the action."), |
| @Param( |
| name = "tools", |
| allowedTypes = { |
| @ParamType(type = Sequence.class), |
| @ParamType(type = Depset.class), |
| }, |
| generic1 = FileApi.class, |
| defaultValue = "unbound", |
| named = true, |
| positional = false, |
| doc = |
| "List of the any tools needed by the action. Tools are inputs with additional " |
| + "runfiles that are automatically made available to the action."), |
| @Param( |
| name = "arguments", |
| allowedTypes = { |
| @ParamType(type = Sequence.class), |
| }, |
| defaultValue = "[]", |
| named = true, |
| positional = false, |
| doc = |
| "Command line arguments of the action. Must be a list of strings or actions.args() " |
| + "objects."), |
| @Param( |
| name = "mnemonic", |
| type = String.class, |
| noneable = true, |
| defaultValue = "None", |
| named = true, |
| positional = false, |
| doc = "A one-word description of the action, e.g. CppCompile or GoLink."), |
| @Param( |
| name = "command", |
| type = Object.class, |
| allowedTypes = { |
| @ParamType(type = String.class), |
| @ParamType(type = Sequence.class, generic1 = String.class), |
| @ParamType(type = NoneType.class), |
| }, |
| noneable = true, |
| defaultValue = "None", |
| named = true, |
| positional = false, |
| doc = |
| "Shell command to execute. It is usually preferable to " |
| + "use <code>executable</code> instead. " |
| + "Arguments are available with <code>$1</code>, <code>$2</code>, etc."), |
| @Param( |
| name = "progress_message", |
| type = String.class, |
| noneable = true, |
| defaultValue = "None", |
| named = true, |
| positional = false, |
| doc = |
| "Progress message to show to the user during the build, " |
| + "e.g. \"Compiling foo.cc to create foo.o\"."), |
| @Param( |
| name = "use_default_shell_env", |
| type = Boolean.class, |
| defaultValue = "False", |
| named = true, |
| positional = false, |
| doc = "Whether the action should use the built in shell environment or not."), |
| @Param( |
| name = "env", |
| type = Dict.class, |
| noneable = true, |
| defaultValue = "None", |
| named = true, |
| positional = false, |
| doc = "Sets the dictionary of environment variables."), |
| @Param( |
| name = "execution_requirements", |
| type = Dict.class, |
| noneable = true, |
| defaultValue = "None", |
| named = true, |
| positional = false, |
| doc = |
| "Information for scheduling the action. See " |
| + "<a href=\"$BE_ROOT/common-definitions.html#common.tags\">tags</a> " |
| + "for useful keys."), |
| @Param( |
| // TODO(bazel-team): The name here isn't accurate anymore. This is technically |
| // experimental, |
| // so folks shouldn't be too attached, but consider renaming to be more accurate/opaque. |
| name = "input_manifests", |
| type = Sequence.class, |
| noneable = true, |
| defaultValue = "None", |
| named = true, |
| positional = false, |
| doc = |
| "(Experimental) sets the input runfiles metadata; " |
| + "they are typically generated by resolve_command.") |
| }, |
| allowReturnNones = true, |
| useStarlarkThread = true) |
| NoneType action( |
| Sequence<?> outputs, |
| Object inputs, |
| Object executableUnchecked, |
| Object toolsUnchecked, |
| Object arguments, |
| Object mnemonicUnchecked, |
| Object commandUnchecked, |
| Object progressMessage, |
| Boolean useDefaultShellEnv, |
| Object envUnchecked, |
| Object executionRequirementsUnchecked, |
| Object inputManifestsUnchecked, |
| StarlarkThread thread) |
| throws EvalException; |
| |
| @SkylarkCallable( |
| 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", type = String.class, doc = "String to be expanded."), |
| @Param( |
| name = "targets", |
| type = Sequence.class, |
| generic1 = TransitiveInfoCollectionApi.class, |
| defaultValue = "[]", |
| named = true, |
| doc = "List of targets for additional lookup information."), |
| }, |
| allowReturnNones = true, |
| useStarlarkThread = true) |
| String expandLocation(String input, Sequence<?> targets, StarlarkThread thread) |
| throws EvalException; |
| |
| @SkylarkCallable( |
| name = "file_action", |
| doc = |
| "DEPRECATED. Use <a href =\"actions.html#write\">ctx.actions.write</a> instead. <br>" |
| + "Creates a file write action.", |
| parameters = { |
| @Param(name = "output", type = FileApi.class, named = true, doc = "The output file."), |
| @Param( |
| name = "content", |
| type = String.class, |
| named = true, |
| doc = "The contents of the file."), |
| @Param( |
| name = "executable", |
| type = Boolean.class, |
| defaultValue = "False", |
| named = true, |
| doc = "Whether the output file should be executable (default is False).") |
| }, |
| allowReturnNones = true, |
| useStarlarkThread = true) |
| NoneType fileAction(FileApi output, String content, Boolean executable, StarlarkThread thread) |
| throws EvalException; |
| |
| @SkylarkCallable( |
| name = "empty_action", |
| doc = |
| "DEPRECATED. Use <a href=\"actions.html#do_nothing\">ctx.actions.do_nothing</a> instead." |
| + " <br>" |
| + "Creates an empty action that neither executes a command nor produces any " |
| + "output, but that is useful for inserting 'extra actions'.", |
| parameters = { |
| @Param( |
| name = "mnemonic", |
| type = String.class, |
| named = true, |
| positional = false, |
| doc = "A one-word description of the action, e.g. CppCompile or GoLink."), |
| @Param( |
| name = "inputs", |
| allowedTypes = { |
| @ParamType(type = Sequence.class), |
| @ParamType(type = Depset.class), |
| }, |
| generic1 = FileApi.class, |
| named = true, |
| positional = false, |
| defaultValue = "[]", |
| doc = "List of the input files of the action."), |
| }, |
| allowReturnNones = true, |
| useStarlarkThread = true) |
| NoneType emptyAction(String mnemonic, Object inputs, StarlarkThread thread) throws EvalException; |
| |
| @SkylarkCallable( |
| name = "template_action", |
| doc = |
| "DEPRECATED. " |
| + "Use <a href=\"actions.html#expand_template\">ctx.actions.expand_template()</a> " |
| + "instead. <br>Creates a template expansion action.", |
| parameters = { |
| @Param( |
| name = "template", |
| type = FileApi.class, |
| named = true, |
| positional = false, |
| doc = "The template file, which is a UTF-8 encoded text file."), |
| @Param( |
| name = "output", |
| type = FileApi.class, |
| named = true, |
| positional = false, |
| doc = "The output file, which is a UTF-8 encoded text file."), |
| @Param( |
| name = "substitutions", |
| type = Dict.class, |
| named = true, |
| positional = false, |
| doc = "Substitutions to make when expanding the template."), |
| @Param( |
| name = "executable", |
| type = Boolean.class, |
| defaultValue = "False", |
| named = true, |
| positional = false, |
| doc = "Whether the output file should be executable (default is False).") |
| }, |
| allowReturnNones = true, |
| useStarlarkThread = true) |
| NoneType templateAction( |
| FileApi template, |
| FileApi output, |
| Dict<?, ?> substitutionsUnchecked, |
| Boolean executable, |
| StarlarkThread thread) |
| throws EvalException; |
| |
| @SkylarkCallable( |
| name = "runfiles", |
| doc = "Creates a runfiles object.", |
| parameters = { |
| @Param( |
| name = "files", |
| 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", |
| type = Depset.class, |
| generic1 = FileApi.class, |
| noneable = true, |
| 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", |
| type = Boolean.class, |
| defaultValue = "False", |
| named = true, |
| doc = |
| "<b>Use of this parameter is not recommended. See " |
| + "<a href=\"../rules.html#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", |
| type = Boolean.class, |
| defaultValue = "False", |
| named = true, |
| doc = |
| "<b>Use of this parameter is not recommended. See " |
| + "<a href=\"../rules.html#runfiles\">runfiles guide</a></b>. " |
| + "<p>Whether to collect the default " |
| + "runfiles from the dependencies in srcs, data and deps attributes."), |
| @Param( |
| name = "symlinks", |
| type = Dict.class, |
| defaultValue = "{}", |
| named = true, |
| doc = "The map of symlinks to be added to the runfiles, prefixed by workspace name."), |
| @Param( |
| name = "root_symlinks", |
| type = Dict.class, |
| defaultValue = "{}", |
| named = true, |
| doc = "The map of symlinks to be added to the runfiles.") |
| }) |
| RunfilesApi runfiles( |
| Sequence<?> files, |
| Object transitiveFiles, |
| Boolean collectData, |
| Boolean collectDefault, |
| Dict<?, ?> symlinks, |
| Dict<?, ?> rootSymlinks) |
| throws EvalException; |
| |
| @SkylarkCallable( |
| name = "resolve_command", |
| // TODO(bazel-team): The naming here isn't entirely accurate (input_manifests is no longer |
| // manifests), but this is experimental/should be opaque to the end user. |
| doc = |
| "<i>(Experimental)</i> Returns a tuple <code>(inputs, command, input_manifests)</code>" |
| + " of the list of resolved inputs, the argv list for the resolved command, and the" |
| + " runfiles metadata required to run the command, all 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).", |
| parameters = { |
| @Param( |
| name = "command", |
| type = String.class, // string |
| defaultValue = "''", |
| named = true, |
| positional = false, |
| doc = "Command to resolve."), |
| @Param( |
| name = "attribute", |
| type = String.class, // string |
| defaultValue = "None", |
| noneable = true, |
| named = true, |
| positional = false, |
| doc = "Name of the associated attribute for which to issue an error, or None."), |
| @Param( |
| name = "expand_locations", |
| type = Boolean.class, |
| 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", |
| type = Dict.class, // dict(string, string) |
| noneable = true, |
| defaultValue = "None", |
| named = true, |
| positional = false, |
| doc = "Make variables to expand, or None."), |
| @Param( |
| name = "tools", |
| defaultValue = "[]", |
| type = Sequence.class, |
| generic1 = TransitiveInfoCollectionApi.class, |
| named = true, |
| positional = false, |
| doc = "List of tools (list of targets)."), |
| @Param( |
| name = "label_dict", |
| type = Dict.class, |
| 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", |
| type = Dict.class, |
| defaultValue = "{}", |
| named = true, |
| positional = false, |
| doc = |
| "Information for scheduling the action to resolve this command. See " |
| + "<a href=\"$BE_ROOT/common-definitions.html#common.tags\">tags</a> " |
| + "for useful keys."), |
| }, |
| useStarlarkThread = true) |
| Tuple<Object> resolveCommand( |
| String command, |
| Object attributeUnchecked, |
| Boolean expandLocations, |
| Object makeVariablesUnchecked, |
| Sequence<?> tools, |
| Dict<?, ?> labelDictUnchecked, |
| Dict<?, ?> executionRequirementsUnchecked, |
| StarlarkThread thread) |
| throws EvalException; |
| |
| @SkylarkCallable( |
| name = "resolve_tools", |
| doc = |
| "Returns a tuple <code>(inputs, input_manifests)</code> of the depset of resolved inputs" |
| + " and the runfiles metadata required to run the tools, both of them suitable for" |
| + " passing as the same-named arguments of the <code>ctx.actions.run</code> method." |
| + "<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.", |
| parameters = { |
| @Param( |
| name = "tools", |
| defaultValue = "[]", |
| type = Sequence.class, |
| generic1 = TransitiveInfoCollectionApi.class, |
| named = true, |
| positional = false, |
| doc = "List of tools (list of targets)."), |
| }) |
| Tuple<Object> resolveTools(Sequence<?> tools) throws EvalException; |
| } |
