| // 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.devtools.build.lib.events.Location; |
| 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.skylarkinterface.SkylarkValue; |
| import com.google.devtools.build.lib.syntax.Environment; |
| import com.google.devtools.build.lib.syntax.EvalException; |
| import com.google.devtools.build.lib.syntax.Runtime; |
| import com.google.devtools.build.lib.syntax.SkylarkDict; |
| import com.google.devtools.build.lib.syntax.SkylarkList; |
| import com.google.devtools.build.lib.syntax.SkylarkNestedSet; |
| |
| /** Module providing functions to create actions. */ |
| @SkylarkModule( |
| name = "actions", |
| category = SkylarkModuleCategory.BUILTIN, |
| doc = |
| "Module providing functions to create actions. " |
| + "Access this module using <a href=\"ctx.html#actions\"><code>ctx.actions</code></a>.") |
| public interface SkylarkActionFactoryApi extends SkylarkValue { |
| |
| @SkylarkCallable( |
| name = "declare_file", |
| doc = |
| "Declares that the rule or aspect creates a file with the given filename. " |
| + "If <code>sibling</code> is not specified, the file name is relative to the package" |
| + "directory, otherwise the file is in the same directory as <code>sibling</code>." |
| + "Files cannot be created outside of the current package." |
| + "<p>Remember that in addition to declaring a file, you must separately create an " |
| + "action that emits the file. Creating that action will require passing the returned " |
| + "<code>File</code> object to the action's construction function." |
| + "<p>Note that <a href='../rules.$DOC_EXT#files'>predeclared output files</a> do not " |
| + "need to be (and cannot be) declared using this function. You can obtain their " |
| + "<code>File</code> objects from <a href=\"ctx.html#outputs\"><code>ctx.outputs</code>" |
| + "</a> instead. " |
| + "<a href=\"https://github.com/bazelbuild/examples/tree/master/rules/" |
| + "computed_dependencies/hash.bzl\">See example of use</a>", |
| parameters = { |
| @Param( |
| name = "filename", |
| type = String.class, |
| doc = |
| "If no 'sibling' provided, path of the new file, relative " |
| + "to the current package. Otherwise a base name for a file " |
| + "('sibling' determines a directory)." |
| ), |
| @Param( |
| name = "sibling", |
| doc = |
| "A file that lives in the same directory as the newly created file. " |
| + "The file must be in the current package.", |
| type = FileApi.class, |
| noneable = true, |
| positional = false, |
| named = true, |
| defaultValue = "None" |
| ) |
| } |
| ) |
| public FileApi declareFile(String filename, Object sibling) throws EvalException; |
| |
| @SkylarkCallable( |
| name = "declare_directory", |
| doc = |
| "Declares that rule or aspect create a directory with the given name, in the " |
| + "current package. You must create an action that generates the directory.", |
| parameters = { |
| @Param( |
| name = "filename", |
| type = String.class, |
| doc = |
| "If no 'sibling' provided, path of the new directory, relative " |
| + "to the current package. Otherwise a base name for a file " |
| + "('sibling' defines a directory)."), |
| @Param( |
| name = "sibling", |
| doc = "A file that lives in the same directory as the newly declared directory.", |
| type = FileApi.class, |
| noneable = true, |
| positional = false, |
| named = true, |
| defaultValue = "None") |
| }) |
| public FileApi declareDirectory(String filename, Object sibling) throws EvalException; |
| |
| @SkylarkCallable( |
| name = "do_nothing", |
| doc = |
| "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, for example, CppCompile or GoLink."), |
| @Param( |
| name = "inputs", |
| allowedTypes = { |
| @ParamType(type = SkylarkList.class), |
| @ParamType(type = SkylarkNestedSet.class), |
| }, |
| generic1 = FileApi.class, |
| named = true, |
| positional = false, |
| defaultValue = "[]", |
| doc = "List of the input files of the action."), |
| }) |
| public void doNothing(String mnemonic, Object inputs) throws EvalException; |
| |
| @SkylarkCallable( |
| name = "write", |
| doc = |
| "Creates a file write action. When the action is executed, it will write the given content " |
| + "to a file. This is used to generate files using information available in the " |
| + "analysis phase. If the file is large and with a lot of static content, consider " |
| + "using <a href=\"#expand_template\"><code>expand_template</code></a>.", |
| parameters = { |
| @Param(name = "output", type = FileApi.class, doc = "The output file.", named = true), |
| @Param( |
| name = "content", |
| type = Object.class, |
| allowedTypes = { |
| @ParamType(type = String.class), |
| @ParamType(type = CommandLineArgsApi.class) |
| }, |
| doc = |
| "the contents of the file. " |
| + "May be a either a string or an " |
| + "<a href=\"actions.html#args\"><code>actions.args()</code></a> object.", |
| named = true |
| ), |
| @Param( |
| name = "is_executable", |
| type = Boolean.class, |
| defaultValue = "False", |
| doc = "Whether the output file should be executable.", |
| named = true |
| ) |
| } |
| ) |
| public void write(FileApi output, Object content, Boolean isExecutable) throws EvalException; |
| |
| @SkylarkCallable( |
| name = "run", |
| doc = |
| "Creates an action that runs an executable. " |
| + "<a href=\"https://github.com/bazelbuild/examples/tree/master/rules/" |
| + "actions_run/execute.bzl\">See example of use</a>", |
| parameters = { |
| @Param( |
| name = "outputs", |
| type = SkylarkList.class, |
| generic1 = FileApi.class, |
| named = true, |
| positional = false, |
| doc = "List of the output files of the action." |
| ), |
| @Param( |
| name = "inputs", |
| allowedTypes = { |
| @ParamType(type = SkylarkList.class), |
| @ParamType(type = SkylarkNestedSet.class), |
| }, |
| generic1 = FileApi.class, |
| defaultValue = "[]", |
| named = true, |
| positional = false, |
| doc = "List or depset of the input files of the action." |
| ), |
| @Param( |
| name = "executable", |
| type = Object.class, |
| allowedTypes = { |
| @ParamType(type = FileApi.class), |
| @ParamType(type = String.class), |
| }, |
| named = true, |
| positional = false, |
| doc = "The executable file to be called by the action." |
| ), |
| @Param( |
| name = "tools", |
| allowedTypes = { |
| @ParamType(type = SkylarkList.class), |
| @ParamType(type = SkylarkNestedSet.class), |
| }, |
| generic1 = FileApi.class, |
| defaultValue = "unbound", |
| named = true, |
| positional = false, |
| doc = |
| "List or depset of any tools needed by the action. Tools are inputs with additional " |
| + "runfiles that are automatically made available to the action." |
| ), |
| @Param( |
| name = "arguments", |
| type = Object.class, |
| allowedTypes = { |
| @ParamType(type = SkylarkList.class), |
| }, |
| defaultValue = "[]", |
| named = true, |
| positional = false, |
| doc = |
| "Command line arguments of the action. " |
| + "Must be a list of strings or " |
| + "<a href=\"actions.html#args\"><code>actions.args()</code></a> objects." |
| ), |
| @Param( |
| name = "mnemonic", |
| type = String.class, |
| noneable = true, |
| defaultValue = "None", |
| named = true, |
| positional = false, |
| doc = "A one-word description of the action, for example, CppCompile or GoLink." |
| ), |
| @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, " |
| + "for example, \"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 = SkylarkDict.class, |
| noneable = true, |
| defaultValue = "None", |
| named = true, |
| positional = false, |
| doc = "Sets the dictionary of environment variables." |
| ), |
| @Param( |
| name = "execution_requirements", |
| type = SkylarkDict.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 = SkylarkList.class, |
| noneable = true, |
| defaultValue = "None", |
| named = true, |
| positional = false, |
| doc = |
| "(Experimental) sets the input runfiles metadata; " |
| + "they are typically generated by resolve_command." |
| ) |
| }, |
| useLocation = true |
| ) |
| public void run( |
| SkylarkList outputs, |
| Object inputs, |
| Object executableUnchecked, |
| Object toolsUnchecked, |
| Object arguments, |
| Object mnemonicUnchecked, |
| Object progressMessage, |
| Boolean useDefaultShellEnv, |
| Object envUnchecked, |
| Object executionRequirementsUnchecked, |
| Object inputManifestsUnchecked, |
| Location location) |
| throws EvalException; |
| |
| @SkylarkCallable( |
| name = "run_shell", |
| doc = |
| "Creates an action that runs a shell command. " |
| + "<a href=\"https://github.com/bazelbuild/examples/tree/master/rules/" |
| + "shell_command/size.bzl\">See example of use</a>", |
| parameters = { |
| @Param( |
| name = "outputs", |
| type = SkylarkList.class, |
| generic1 = FileApi.class, |
| named = true, |
| positional = false, |
| doc = "List of the output files of the action." |
| ), |
| @Param( |
| name = "inputs", |
| allowedTypes = { |
| @ParamType(type = SkylarkList.class), |
| @ParamType(type = SkylarkNestedSet.class), |
| }, |
| generic1 = FileApi.class, |
| defaultValue = "[]", |
| named = true, |
| positional = false, |
| doc = "List or depset of the input files of the action." |
| ), |
| @Param( |
| name = "tools", |
| allowedTypes = { |
| @ParamType(type = SkylarkList.class), |
| @ParamType(type = SkylarkNestedSet.class), |
| }, |
| generic1 = FileApi.class, |
| defaultValue = "unbound", |
| named = true, |
| positional = false, |
| doc = |
| "List or depset of 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 = SkylarkList.class), |
| }, |
| defaultValue = "[]", |
| named = true, |
| positional = false, |
| doc = |
| "Command line arguments of the action. " |
| + "Must be a list of strings or " |
| + "<a href=\"actions.html#args\"><code>actions.args()</code></a> objects.<br>" |
| + "Blaze passes the elements in this attribute as arguments to the command." |
| + "The command can access these arguments as <code>$1</code>, <code>$2</code>, etc." |
| ), |
| @Param( |
| name = "mnemonic", |
| type = String.class, |
| noneable = true, |
| defaultValue = "None", |
| named = true, |
| positional = false, |
| doc = "A one-word description of the action, for example, CppCompile or GoLink." |
| ), |
| @Param( |
| name = "command", |
| type = Object.class, |
| allowedTypes = { |
| @ParamType(type = String.class), |
| @ParamType(type = SkylarkList.class, generic1 = String.class), |
| @ParamType(type = Runtime.NoneType.class), |
| }, |
| named = true, |
| positional = false, |
| doc = |
| "Shell command to execute.<br><br>" |
| + "<b>Passing a sequence of strings to this attribute is deprecated and Blaze may " |
| + "stop accepting such values in the future.</b><br><br>" |
| + "The command can access the elements of the <code>arguments</code> object via " |
| + "<code>$1</code>, <code>$2</code>, etc.<br>" |
| + "When this argument is a string, it must be a valid shell command. For example: " |
| + "\"<code>echo foo > $1</code>\". Blaze uses the same shell to execute the " |
| + "command as it does for genrules." |
| ), |
| @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, " |
| + "for example, \"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 = SkylarkDict.class, |
| noneable = true, |
| defaultValue = "None", |
| named = true, |
| positional = false, |
| doc = "Sets the dictionary of environment variables." |
| ), |
| @Param( |
| name = "execution_requirements", |
| type = SkylarkDict.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 = SkylarkList.class, |
| noneable = true, |
| defaultValue = "None", |
| named = true, |
| positional = false, |
| doc = |
| "(Experimental) sets the input runfiles metadata; " |
| + "they are typically generated by resolve_command." |
| ) |
| }, |
| useLocation = true |
| ) |
| public void runShell( |
| SkylarkList outputs, |
| Object inputs, |
| Object toolsUnchecked, |
| Object arguments, |
| Object mnemonicUnchecked, |
| Object commandUnchecked, |
| Object progressMessage, |
| Boolean useDefaultShellEnv, |
| Object envUnchecked, |
| Object executionRequirementsUnchecked, |
| Object inputManifestsUnchecked, |
| Location location) |
| throws EvalException; |
| |
| @SkylarkCallable( |
| name = "expand_template", |
| doc = |
| "Creates a template expansion action. When the action is executed, it will " |
| + "generate a file based on a template. Parts of the template will be replaced " |
| + "using the <code>substitutions</code> dictionary. Whenever a key of the " |
| + "dictionary appears in the template, it is replaced with the associated value. " |
| + "There is no special syntax for the keys. You may, for example, use curly braces " |
| + "to avoid conflicts (for example, <code>{KEY}</code>). " |
| + "<a href=\"https://github.com/bazelbuild/examples/blob/master/rules/expand_template/hello.bzl\">" |
| + "See example of use</a>", |
| 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 = SkylarkDict.class, |
| named = true, |
| positional = false, |
| doc = "Substitutions to make when expanding the template." |
| ), |
| @Param( |
| name = "is_executable", |
| type = Boolean.class, |
| defaultValue = "False", |
| named = true, |
| positional = false, |
| doc = "Whether the output file should be executable." |
| ) |
| } |
| ) |
| public void expandTemplate( |
| FileApi template, |
| FileApi output, |
| SkylarkDict<?, ?> substitutionsUnchecked, |
| Boolean executable) |
| throws EvalException; |
| |
| @SkylarkCallable( |
| name = "args", |
| doc = "Returns an Args object that can be used to build memory-efficient command lines.", |
| useEnvironment = true |
| ) |
| public CommandLineArgsApi args(Environment env); |
| } |