diff options
author | brandjon <brandjon@google.com> | 2018-08-15 13:55:29 -0700 |
---|---|---|
committer | Copybara-Service <copybara-piper@google.com> | 2018-08-15 13:57:17 -0700 |
commit | e2f61b197a1375b04222aa99a6bbcb290a19e36c (patch) | |
tree | 1b4c9a05683d880a664b7998eca7c1c4fbe24e66 /src/main/java/com/google/devtools/build | |
parent | d3501d8325e7ea054f06cd218fb3d182ca0ead13 (diff) |
Clarify docs for ctx.actions.run_shell()'s command/arguments
- Clarified incompatibility between giving args and giving list of strings for command.
- Added more detail about how $i expansion is done.
- Removed incorrect indication that None is allowed for "command".
RELNOTES: None
PiperOrigin-RevId: 208877037
Diffstat (limited to 'src/main/java/com/google/devtools/build')
-rw-r--r-- | src/main/java/com/google/devtools/build/lib/skylarkbuildapi/SkylarkActionFactoryApi.java | 48 |
1 files changed, 31 insertions, 17 deletions
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 282890de33..51879b72f3 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 @@ -23,7 +23,6 @@ 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; @@ -343,12 +342,17 @@ public interface SkylarkActionFactoryApi extends SkylarkValue { 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." + "Command line arguments of the action. Must be a list of strings or " + + "<a href=\"actions.html#args\"><code>actions.args()</code></a> objects." + + "" + + "<p>Bazel 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."), + + "etc. Args objects are flattened before indexing. It is generally not useful " + + "to have an Args object of unknown size in this list, since that means all " + + "strings in or after that Args object will be at unpredictable indices." + + "" + + "<p>In the case where <code>command</code> is a list of strings, this " + + "parameter may not be used."), @Param( name = "mnemonic", type = String.class, @@ -363,21 +367,31 @@ public interface SkylarkActionFactoryApi extends SkylarkValue { 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> If a sequence of strings " - + "is passed, then <code>arguments</code> must not be used.<br><br> " - + "The command string 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."), + "Shell command to execute. This may either be a string (preferred) or a sequence " + + "of strings <b>(deprecated)</b>." + + "" + + "<p>If <code>command</code> is a string, then it is executed as if by " + + "<code>sh -c <command> \"\" <arguments></code> -- that is, the " + + "elements in <code>arguments</code> are made available to the command as " + + "<code>$1</code>, <code>$2</code>, etc. If <code>arguments</code> contains " + + "any <a href=\"actions.html#args\"><code>actions.args()</code></a> objects, " + + "their contents are appended one by one to the command line, so " + + "<code>$</code><i>i</i> can refer to individual strings within an Args " + + "object. Note that it is not useful to pass an Args object of unknown size " + + "as part of <code>arguments</code>, since then the strings would not be at " + + "known indices." + + "" + + "<p><b>(Deprecated)</b> If <code>command</code> is a sequence of strings, " + + "the first item is the executable to run and the remaining items are its " + + "arguments. If this form is used, the <code>arguments</code> parameter must " + + "not be supplied." + + "" + + "<p>Bazel uses the same shell to execute the command as it does for " + + "genrules."), @Param( name = "progress_message", type = String.class, |