From 74fa9d49cd43d277f9f3738cc1380790eb44ba12 Mon Sep 17 00:00:00 2001 From: Sam Rawlins Date: Thu, 7 Jun 2018 07:25:49 -0700 Subject: [PATCH] Fix a few generated docs. In particular, * fix sentences with no space after the period, like [here]([] * switch backticks to ``, like [here]([] * link `ctx.var` [here]([] * Add periods to the end of paragraphs, like [here]([] * Format a list [here]([] Closes #5337. PiperOrigin-RevId: 199631585 --- .../skylarkbuildapi/CommandLineArgsApi.java | 29 +- .../SkylarkActionFactoryApi.java | 679 +++++++++--------- .../SkylarkRuleContextApi.java | 447 ++++++------ .../devtools/build/lib/syntax/Runtime.java | 24 +- 4 files changed, 571 insertions(+), 608 deletions(-) diff --git a/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/CommandLineArgsApi.java b/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/CommandLineArgsApi.java index 6d6ba657a88611..8bb807041d95a4 100644 --- a/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/CommandLineArgsApi.java +++ b/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/CommandLineArgsApi.java @@ -502,19 +502,20 @@ public Runtime.NoneType addJoined( public void useParamsFile(String paramFileArg, Boolean useAlways) throws EvalException; @SkylarkCallable( - name = "set_param_file_format", - doc = "Sets the format of the param file when written to disk", - parameters = { - @Param( - name = "format", - type = String.class, - named = true, - doc = - "The format of the param file. Must be one of:
" - + "\"shell\": All arguments are shell quoted and separated by whitespace
" - + "\"multiline\": All arguments are unquoted and separated by newline characters" - + "The format defaults to \"shell\" if not called.") - } - ) + name = "set_param_file_format", + doc = "Sets the format of the param file when written to disk", + parameters = { + @Param( + name = "format", + type = String.class, + named = true, + doc = + "The format of the param file. Must be one of:" + + "The format defaults to \"shell\" if not called.") + }) public void setParamFileFormat(String format) throws EvalException; } diff --git a/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/SkylarkActionFactoryApi.java b/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/SkylarkActionFactoryApi.java index 25a3218bc621c0..1d03df9edfb771 100644 --- a/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/SkylarkActionFactoryApi.java +++ b/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/SkylarkActionFactoryApi.java @@ -38,43 +38,42 @@ public interface SkylarkActionFactoryApi extends SkylarkValue { @SkylarkCallable( - name = "declare_file", - doc = - "Declares that the rule or aspect creates a file with the given filename. " - + "If sibling is not specified, the file name is relative to the package" - + "directory, otherwise the file is in the same directory as sibling." - + "Files cannot be created outside of the current package." - + "

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 " - + "File object to the action's construction function." - + "

Note that predeclared output files do not " - + "need to be (and cannot be) declared using this function. You can obtain their " - + "File objects from ctx.outputs" - + " instead. " - + "See example of use", - 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" - ) - } - ) + name = "declare_file", + doc = + "Declares that the rule or aspect creates a file with the given filename. " + + "If sibling is not specified, the file name is relative to the " + + "package " + + "directory, otherwise the file is in the same directory as sibling. " + + "Files cannot be created outside of the current package." + + "

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 File object to the action's construction function." + + "

Note that predeclared output files do " + + "not " + + "need to be (and cannot be) declared using this function. You can obtain their " + + "File objects from " + + "ctx.outputs instead. " + + "See example of use.", + 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( @@ -161,137 +160,126 @@ public interface SkylarkActionFactoryApi extends SkylarkValue { public void write(FileApi output, Object content, Boolean isExecutable) throws EvalException; @SkylarkCallable( - name = "run", - doc = - "Creates an action that runs an executable. " - + "See example of use", - 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 " - + "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, 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 " - + "tags " - + "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 - ) + name = "run", + doc = + "Creates an action that runs an executable. " + + "See example of use.", + 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 " + + "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, 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 " + + "tags " + + "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, @@ -308,147 +296,140 @@ public void run( throws EvalException; @SkylarkCallable( - name = "run_shell", - doc = - "Creates an action that runs a shell command. " - + "See example of use", - 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 " - + "actions.args() objects.
" - + "Blaze passes the elements in this attribute as arguments to the command." - + "The command can access these arguments as $1, $2, 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.

" - + "Passing a sequence of strings to this attribute is deprecated and Blaze may " - + "stop accepting such values in the future.

" - + "The command can access the elements of the arguments object via " - + "$1, $2, etc.
" - + "When this argument is a string, it must be a valid shell command. For example: " - + "\"echo foo > $1\". 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 " - + "tags " - + "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 - ) + name = "run_shell", + doc = + "Creates an action that runs a shell command. " + + "See example of use.", + 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 " + + "actions.args() objects.
" + + "Blaze passes the elements in this attribute as arguments to the command." + + "The command can access these arguments as $1, $2, " + + "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.

" + + "Passing a sequence of strings to this attribute is deprecated and Blaze" + + "may " + + "stop accepting such values in the future.

" + + "The command can access the elements of the arguments object " + + "via " + + "$1, $2, etc.
" + + "When this argument is a string, it must be a valid shell command. For " + + "example: " + + "\"echo foo > $1\". 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 " + + "tags " + + "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, @@ -465,48 +446,44 @@ public void runShell( 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 substitutions 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, {KEY}). " - + "" - + "See example of use", - 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." - ) - } - ) + 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 substitutions 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, {KEY}). " + + "" + + "See example of use.", + 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, diff --git a/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/SkylarkRuleContextApi.java b/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/SkylarkRuleContextApi.java index 2350429680f2ff..7c1be4caf3f9d0 100644 --- a/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/SkylarkRuleContextApi.java +++ b/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/SkylarkRuleContextApi.java @@ -371,23 +371,26 @@ public boolean checkPlaceholders(String template, SkylarkList allowedPla throws EvalException; @SkylarkCallable( - doc = "Deprecated. Use ctx.var to access the variables instead.
" - + "Returns a string after expanding all references to \"Make variables\". The variables " - + "must have the following format: $(VAR_NAME). Also, $$VAR_NAME" - + " expands to $VAR_NAME. Parameters:" - + "
  • The name of the attribute (string). It's only used for error " - + "reporting.
    • \n" - + "
  • The expression to expand (string). It can contain references to " - + "\"Make variables\".
    • \n" - + "
  • A mapping of additional substitutions (dict of string : " - + "string).
\n" - + "Examples:" - + "
\n"
-        + "ctx.expand_make_variables(\"cmd\", \"$(MY_VAR)\", {\"MY_VAR\": \"Hi\"})  # == \"Hi\"\n"
-        + "ctx.expand_make_variables(\"cmd\", \"$$PWD\", {})  # == \"$PWD\"\n"
-        + "
" - + "Additional variables may come from other places, such as configurations. Note that " - + "this function is experimental.") + doc = + "Deprecated. Use ctx.var to access the variables " + + "instead.
Returns a string after expanding all references to \"Make " + + "variables\". The " + + "variables must have the following format: $(VAR_NAME). Also, " + + "$$VAR_NAME expands to $VAR_NAME. Parameters:" + + "
  • The name of the attribute (string). It's only used for error " + + "reporting.
    • \n" + + "
  • The expression to expand (string). It can contain references to " + + "\"Make variables\".
    • \n" + + "
  • A mapping of additional substitutions (dict of " + + "string : string).
\n" + + "Examples:" + + "
\n"
+              + "ctx.expand_make_variables(\"cmd\", \"$(MY_VAR)\", {\"MY_VAR\": \"Hi\"})  "
+              + "# == \"Hi\"\n"
+              + "ctx.expand_make_variables(\"cmd\", \"$$PWD\", {})  # == \"$PWD\"\n"
+              + "
" + + "Additional variables may come from other places, such as configurations. Note " + + "that this function is experimental.") public String expandMakeVariables( String attributeName, String command, final Map additionalSubstitutions) throws EvalException; @@ -421,160 +424,148 @@ public String expandMakeVariables( public String getBuildFileRelativePath() throws EvalException; @SkylarkCallable( - name = "action", - doc = - "DEPRECATED. Use ctx.actions.run() or" - + " ctx.actions.run_shell().
" - + "Creates an action that runs an executable or a shell command." - + " You must specify either command or executable.\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 = 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 of the input files of the action." - ), - @Param( - name = "executable", - type = Object.class, - allowedTypes = { - @ParamType(type = FileApi.class), - @ParamType(type = String.class), - @ParamType(type = Runtime.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 = SkylarkList.class), - @ParamType(type = SkylarkNestedSet.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 = SkylarkList.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 = SkylarkList.class, generic1 = String.class), - @ParamType(type = Runtime.NoneType.class), - }, - noneable = true, - defaultValue = "None", - named = true, - positional = false, - doc = - "Shell command to execute. It is usually preferable to " - + "use executable instead. " - + "Arguments are available with $1, $2, 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 = 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 " - + "tags " - + "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." - ) - }, - allowReturnNones = true, - useLocation = true, - useEnvironment = true - ) + name = "action", + doc = + "DEPRECATED. Use ctx.actions.run() or" + + " ctx.actions.run_shell().
" + + "Creates an action that runs an executable or a shell command." + + " You must specify either command or executable.\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 = 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 of the input files of the action."), + @Param( + name = "executable", + type = Object.class, + allowedTypes = { + @ParamType(type = FileApi.class), + @ParamType(type = String.class), + @ParamType(type = Runtime.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 = SkylarkList.class), + @ParamType(type = SkylarkNestedSet.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 = SkylarkList.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 = SkylarkList.class, generic1 = String.class), + @ParamType(type = Runtime.NoneType.class), + }, + noneable = true, + defaultValue = "None", + named = true, + positional = false, + doc = + "Shell command to execute. It is usually preferable to " + + "use executable instead. " + + "Arguments are available with $1, $2, 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 = 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 " + + "tags " + + "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.") + }, + allowReturnNones = true, + useLocation = true, + useEnvironment = true) public Runtime.NoneType action( SkylarkList outputs, Object inputs, @@ -737,66 +728,60 @@ public Runtime.NoneType templateAction( throws EvalException; @SkylarkCallable( - name = "runfiles", - doc = "Creates a runfiles object.", - parameters = { - @Param( - name = "files", - type = SkylarkList.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 = SkylarkNestedSet.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 `default` order (which, as the name implies, is the default)." - ), - @Param( - name = "collect_data", - type = Boolean.class, - defaultValue = "False", - named = true, - doc = - "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 = - "Whether to collect the default " - + "runfiles from the dependencies in srcs, data and deps attributes." - ), - @Param( - name = "symlinks", - type = SkylarkDict.class, - defaultValue = "{}", - named = true, - doc = "The map of symlinks to be added to the runfiles, prefixed by workspace name." - ), - @Param( - name = "root_symlinks", - type = SkylarkDict.class, - defaultValue = "{}", - named = true, - doc = "The map of symlinks to be added to the runfiles." - ) - }, - useLocation = true - ) + name = "runfiles", + doc = "Creates a runfiles object.", + parameters = { + @Param( + name = "files", + type = SkylarkList.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 = SkylarkNestedSet.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 default order (which, as the name implies, is the " + + "default)."), + @Param( + name = "collect_data", + type = Boolean.class, + defaultValue = "False", + named = true, + doc = + "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 = + "Whether to collect the default " + + "runfiles from the dependencies in srcs, data and deps attributes."), + @Param( + name = "symlinks", + type = SkylarkDict.class, + defaultValue = "{}", + named = true, + doc = "The map of symlinks to be added to the runfiles, prefixed by workspace name."), + @Param( + name = "root_symlinks", + type = SkylarkDict.class, + defaultValue = "{}", + named = true, + doc = "The map of symlinks to be added to the runfiles.") + }, + useLocation = true) public RunfilesApi runfiles( SkylarkList files, Object transitiveFiles, diff --git a/src/main/java/com/google/devtools/build/lib/syntax/Runtime.java b/src/main/java/com/google/devtools/build/lib/syntax/Runtime.java index 9774ec5bb9ea3a..48129f4955e775 100644 --- a/src/main/java/com/google/devtools/build/lib/syntax/Runtime.java +++ b/src/main/java/com/google/devtools/build/lib/syntax/Runtime.java @@ -124,18 +124,18 @@ public void repr(SkylarkPrinter printer) { public static final String PKG_NAME = "PACKAGE_NAME"; @SkylarkSignature( - name = "REPOSITORY_NAME", - returnType = String.class, - doc = - "Deprecated. Use repository_name() " - + "instead. The name of the repository the rule or build extension is called from. " - + "For example, in packages that are called into existence by the WORKSPACE stanza " - + "local_repository(name='local', path=...) it will be set to " - + "@local. In packages in the main repository, it will be set to " - + "@. It can only be accessed in functions (transitively) called from " - + "BUILD files, i.e. it follows the same restrictions as " - + "PACKAGE_NAME" - ) + name = "REPOSITORY_NAME", + returnType = String.class, + doc = + "Deprecated. Use repository_name() " + + "instead. The name of the repository the rule or build extension is called " + + "from. " + + "For example, in packages that are called into existence by the WORKSPACE stanza " + + "local_repository(name='local', path=...) it will be set to " + + "@local. In packages in the main repository, it will be set to " + + "@. It can only be accessed in functions (transitively) called from " + + "BUILD files, i.e. it follows the same restrictions as " + + "PACKAGE_NAME.") public static final String REPOSITORY_NAME = "REPOSITORY_NAME"; /** Adds bindings for False/True/None constants to the given map builder. */