| // 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.devtools.build.docgen.annot.DocCategory; |
| import com.google.devtools.build.lib.collect.nestedset.Depset; |
| import com.google.devtools.build.lib.packages.semantics.BuildLanguageOptions; |
| import java.io.IOException; |
| import javax.annotation.Nullable; |
| 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.Sequence; |
| import net.starlark.java.eval.StarlarkSemantics; |
| import net.starlark.java.eval.StarlarkValue; |
| |
| /** Interface for actions in Starlark. */ |
| @StarlarkBuiltin( |
| name = "Action", |
| category = DocCategory.BUILTIN, |
| doc = |
| "An action created during rule analysis.<p>This object is visible for the purpose of" |
| + " testing, and may be obtained from an <code>Actions</code> provider. It is normally" |
| + " not necessary to access <code>Action</code> objects or their fields within a rule's" |
| + " implementation function. You may instead want to see the <a" |
| + " href='https://bazel.build/extending/rules#actions'>Rules page</a> for a general" |
| + " discussion of how to use actions when defining custom rules, or the <a" |
| + " href='../builtins/actions.html'>API reference</a> for creating actions.<p>Some" |
| + " fields of this object are only applicable for certain kinds of actions. Fields that" |
| + " are inapplicable are set to <code>None</code>.") |
| public interface ActionApi extends StarlarkValue { |
| |
| @StarlarkMethod(name = "mnemonic", structField = true, doc = "The mnemonic for this action.") |
| String getMnemonic(); |
| |
| @StarlarkMethod( |
| name = "inputs", |
| doc = "A set of the input files of this action.", |
| structField = true) |
| Depset getStarlarkInputs(); |
| |
| @StarlarkMethod( |
| name = "outputs", |
| doc = "A set of the output files of this action.", |
| structField = true) |
| Depset getStarlarkOutputs(); |
| |
| @StarlarkMethod( |
| name = "argv", |
| doc = |
| "For actions created by <a href=\"../builtins/actions.html#run\">ctx.actions.run()</a> or" |
| + " <a href=\"../builtins/actions.html#run_shell\">ctx.actions.run_shell()</a> an" |
| + " immutable list of the arguments for the command line to be executed. Note that" |
| + " for shell actions the first two arguments will be the shell path and" |
| + " <code>\"-c\"</code>.", |
| structField = true, |
| allowReturnNones = true) |
| @Nullable |
| Sequence<String> getStarlarkArgv() throws EvalException, InterruptedException; |
| |
| @StarlarkMethod( |
| name = "args", |
| doc = |
| "A list of frozen <a href=\"../builtins/Args.html\">Args</a> objects containing" |
| + " information about the action arguments. These objects contain accurate argument" |
| + " information, including arguments involving expanded action output directories." |
| + " However, <a href=\"../builtins/Args.html\">Args</a> objects are not readable in" |
| + " the analysis phase. For a less accurate account of arguments which is available" |
| + " in the analysis phase, see <a href=\"#argv\">argv</a>. <p>Note that some types of" |
| + " actions do not yet support exposure of this field. For such action types, this is" |
| + " <code>None</code>.", |
| structField = true, |
| allowReturnNones = true) |
| @Nullable |
| Sequence<CommandLineArgsApi> getStarlarkArgs() throws EvalException, InterruptedException; |
| |
| /** |
| * If the action writes a file whose content is known at analysis time, returns that content; |
| * returns null otherwise. |
| * |
| * <p>The content might be unknown if, for instance, the action expands an {@code Args} object |
| * that includes a directory ({@link TreeArtifact}) with {@code expand_directories=False}. |
| * |
| * @throws EvalException if there is a Starlark evaluation error, e.g. in an {@code Args} object's |
| * call to a {@code map_each} callback. |
| * @throws IOException if there is a non-Starlark error in expanding an {@code Args} object. |
| */ |
| @StarlarkMethod( |
| name = "content", |
| doc = |
| "For actions created by <a" |
| + " href=\"../builtins/actions.html#write\">ctx.actions.write()</a> or <a" |
| + " href=\"../builtins/actions.html#expand_template\">ctx.actions.expand_template()</a>," |
| + " the contents of the file to be written, if those contents can be computed during " |
| + " the analysis phase. The value is <code>None</code> if the contents cannot be" |
| + " determined until the execution phase, such as when a directory in an <a" |
| + " href=\"../builtins/Args.html\">Args</a> object needs to be expanded.", |
| structField = true, |
| allowReturnNones = true) |
| @Nullable |
| String getStarlarkContent() throws IOException, EvalException, InterruptedException; |
| |
| @StarlarkMethod( |
| name = "substitutions", |
| doc = |
| "For actions created by <a" |
| + " href=\"../builtins/actions.html#expand_template\">ctx.actions.expand_template()</a>," |
| + " an immutable dict holding the substitution mapping.", |
| structField = true, |
| allowReturnNones = true) |
| @Nullable |
| Dict<String, String> getStarlarkSubstitutions() throws EvalException; |
| |
| @StarlarkMethod( |
| name = "env", |
| structField = true, |
| useStarlarkSemantics = true, |
| doc = |
| "The 'fixed' environment variables for this action. This includes only environment" |
| + " settings which are explicitly set by the action definition, and thus omits" |
| + " settings which are only pre-set in the execution environment.") |
| Dict<String, String> getEnv(StarlarkSemantics semantics) throws EvalException; |
| |
| @StarlarkMethod( |
| name = "execution_info", |
| structField = true, |
| doc = |
| "The execution requirements for this action, set for this action specifically. This is a" |
| + " dictionary that maps strings specifying execution info to arbitrary strings." |
| + " This is in order to match the structure of execution info in other parts of the" |
| + " code base; all relevant info is in the keyset. Returns None if this action does" |
| + " not expose execution requirements.", |
| allowReturnNones = true, |
| enableOnlyWithFlag = BuildLanguageOptions.EXPERIMENTAL_GOOGLE_LEGACY_API) |
| @Nullable |
| public Dict<String, String> getExecutionInfoDict(); |
| } |