diff options
26 files changed, 847 insertions, 647 deletions
diff --git a/src/main/java/com/google/devtools/build/lib/actions/Artifact.java b/src/main/java/com/google/devtools/build/lib/actions/Artifact.java index c2eedab62c..5575e747b1 100644 --- a/src/main/java/com/google/devtools/build/lib/actions/Artifact.java +++ b/src/main/java/com/google/devtools/build/lib/actions/Artifact.java @@ -357,12 +357,15 @@ public class Artifact } /** - * Returns true iff this is a source Artifact as determined by its path and - * root relationships. Note that this will report all Artifacts in the output - * tree, including in the include symlink tree, as non-source. + * Returns true iff this is a source Artifact as determined by its path and root relationships. + * Note that this will report all Artifacts in the output tree, including in the include symlink + * tree, as non-source. */ - @SkylarkCallable(name = "is_source", structField = true, - doc = "Returns true if this is a source file, i.e. it is not generated") + @SkylarkCallable( + name = "is_source", + structField = true, + doc = "Returns true if this is a source file, i.e. it is not generated." + ) public final boolean isSourceArtifact() { return execPath == rootRelativePath; } diff --git a/src/main/java/com/google/devtools/build/lib/analysis/FilesToRunProvider.java b/src/main/java/com/google/devtools/build/lib/analysis/FilesToRunProvider.java index 8077a59d35..3a755ff500 100644 --- a/src/main/java/com/google/devtools/build/lib/analysis/FilesToRunProvider.java +++ b/src/main/java/com/google/devtools/build/lib/analysis/FilesToRunProvider.java @@ -22,7 +22,6 @@ import com.google.devtools.build.lib.concurrent.ThreadSafety.Immutable; 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 javax.annotation.Nullable; /** Returns information about executables produced by a target and the files needed to run it. */ @@ -67,12 +66,10 @@ public final class FilesToRunProvider implements TransitiveInfoProvider { return runfilesSupport; } - /** - * Returns the Executable or null if it does not exist. - */ + /** Returns the Executable or null if it does not exist. */ @SkylarkCallable( name = "executable", - doc = "The main executable or None if it does not exist", + doc = "The main executable or None if it does not exist.", structField = true, allowReturnNones = true ) @@ -87,7 +84,7 @@ public final class FilesToRunProvider implements TransitiveInfoProvider { */ @SkylarkCallable( name = "runfiles_manifest", - doc = "The runfiles manifest or None if it does not exist", + doc = "The runfiles manifest or None if it does not exist.", structField = true, allowReturnNones = true ) diff --git a/src/main/java/com/google/devtools/build/lib/analysis/Runfiles.java b/src/main/java/com/google/devtools/build/lib/analysis/Runfiles.java index 25fc4ca865..8f171a3a76 100644 --- a/src/main/java/com/google/devtools/build/lib/analysis/Runfiles.java +++ b/src/main/java/com/google/devtools/build/lib/analysis/Runfiles.java @@ -330,12 +330,12 @@ public final class Runfiles { } /** - * Returns the collection of runfiles as artifacts, including both unconditional artifacts - * and pruning manifest candidates. + * Returns the collection of runfiles as artifacts, including both unconditional artifacts and + * pruning manifest candidates. */ @SkylarkCallable( name = "files", - doc = "Returns the set of runfiles as files", + doc = "Returns the set of runfiles as files.", structField = true ) public NestedSet<Artifact> getArtifacts() { @@ -355,10 +355,8 @@ public final class Runfiles { return Iterables.filter(getArtifacts(), Artifact.MIDDLEMAN_FILTER); } - /** - * Returns the symlinks. - */ - @SkylarkCallable(name = "symlinks", doc = "Returns the set of symlinks", structField = true) + /** Returns the symlinks. */ + @SkylarkCallable(name = "symlinks", doc = "Returns the set of symlinks.", structField = true) public NestedSet<SymlinkEntry> getSymlinks() { return symlinks; } @@ -1118,13 +1116,12 @@ public final class Runfiles { } } - /** - * Provides a Skylark-visible way to merge two Runfiles objects. - */ + /** Provides a Skylark-visible way to merge two Runfiles objects. */ @SkylarkCallable( name = "merge", - doc = "Returns a new runfiles object that includes all the contents of this one and the " - + "argument." + doc = + "Returns a new runfiles object that includes all the contents of this one and the " + + "argument." ) public Runfiles merge(Runfiles other) { Runfiles.Builder builder = new Runfiles.Builder(suffix, false); diff --git a/src/main/java/com/google/devtools/build/lib/bazel/repository/skylark/SkylarkPath.java b/src/main/java/com/google/devtools/build/lib/bazel/repository/skylark/SkylarkPath.java index f07fbafbb9..3491b8cdab 100644 --- a/src/main/java/com/google/devtools/build/lib/bazel/repository/skylark/SkylarkPath.java +++ b/src/main/java/com/google/devtools/build/lib/bazel/repository/skylark/SkylarkPath.java @@ -20,7 +20,6 @@ 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.vfs.Path; - import java.io.IOException; import java.util.List; @@ -34,7 +33,7 @@ import java.util.List; @SkylarkModule( name = "path", category = SkylarkModuleCategory.NONE, - doc = "A structure representing a file to be used inside a repository" + doc = "A structure representing a file to be used inside a repository." ) final class SkylarkPath { private final Path path; diff --git a/src/main/java/com/google/devtools/build/lib/bazel/repository/skylark/SkylarkRepositoryContext.java b/src/main/java/com/google/devtools/build/lib/bazel/repository/skylark/SkylarkRepositoryContext.java index b9ec69fa61..e41f4b32ce 100644 --- a/src/main/java/com/google/devtools/build/lib/bazel/repository/skylark/SkylarkRepositoryContext.java +++ b/src/main/java/com/google/devtools/build/lib/bazel/repository/skylark/SkylarkRepositoryContext.java @@ -356,7 +356,7 @@ public class SkylarkRepositoryContext { @SkylarkCallable( name = "os", structField = true, - doc = "A struct to access information from the system " + doc = "A struct to access information from the system." ) public SkylarkOS getOS() { return osObject; diff --git a/src/main/java/com/google/devtools/build/lib/packages/PackageFactory.java b/src/main/java/com/google/devtools/build/lib/packages/PackageFactory.java index 72ecf59d0f..33da991636 100644 --- a/src/main/java/com/google/devtools/build/lib/packages/PackageFactory.java +++ b/src/main/java/com/google/devtools/build/lib/packages/PackageFactory.java @@ -505,7 +505,7 @@ public final class PackageFactory { name = "glob", objectType = Object.class, returnType = SkylarkList.class, - doc = "Returns a list of files that match glob search pattern", + doc = "Returns a list of files that match glob search pattern.", parameters = { @Param( name = "include", @@ -613,30 +613,34 @@ public final class PackageFactory { } /** - * Returns a function value implementing the "mocksubinclude" function, - * emitted by the PythonPreprocessor. We annotate the - * package with additional dependencies. (A 'real' subinclude will never be - * seen by the parser, because the presence of "subinclude" triggers - * preprocessing.) + * Returns a function value implementing the "mocksubinclude" function, emitted by the + * PythonPreprocessor. We annotate the package with additional dependencies. (A 'real' subinclude + * will never be seen by the parser, because the presence of "subinclude" triggers preprocessing.) */ - @SkylarkSignature(name = "mocksubinclude", returnType = Runtime.NoneType.class, - doc = "implement the mocksubinclude function emitted by the PythonPreprocessor", - parameters = { - @Param(name = "label", type = Object.class, - doc = "a label designator."), - @Param(name = "path", type = String.class, - doc = "a path.")}, - documented = false, useLocation = true) + @SkylarkSignature( + name = "mocksubinclude", + returnType = Runtime.NoneType.class, + doc = "implement the mocksubinclude function emitted by the PythonPreprocessor.", + parameters = { + @Param(name = "label", type = Object.class, doc = "a label designator."), + @Param(name = "path", type = String.class, doc = "a path.") + }, + documented = false, + useLocation = true + ) private static final BuiltinFunction.Factory newMockSubincludeFunction = new BuiltinFunction.Factory("mocksubinclude") { public BuiltinFunction create(final PackageContext context) { return new BuiltinFunction("mocksubinclude", this) { - public Runtime.NoneType invoke(Object labelO, String pathString, - Location loc) throws ConversionException { - Label label = BuildType.LABEL.convert(labelO, "'mocksubinclude' argument", - context.pkgBuilder.getBuildFileLabel()); - Path path = pathString.isEmpty() - ? null : context.pkgBuilder.getFilename().getRelative(pathString); + public Runtime.NoneType invoke(Object labelO, String pathString, Location loc) + throws ConversionException { + Label label = + BuildType.LABEL.convert( + labelO, "'mocksubinclude' argument", context.pkgBuilder.getBuildFileLabel()); + Path path = + pathString.isEmpty() + ? null + : context.pkgBuilder.getFilename().getRelative(pathString); // A subinclude within a package counts as a file declaration. if (label.getPackageIdentifier().equals(context.pkgBuilder.getPackageIdentifier())) { if (loc == null) { @@ -708,32 +712,52 @@ public final class PackageFactory { } }; - /** - * Returns a function-value implementing "exports_files" in the specified - * package context. - */ - @SkylarkSignature(name = "exports_files", returnType = Runtime.NoneType.class, - doc = "Declare a set of files as exported", - parameters = { - @Param(name = "srcs", type = SkylarkList.class, generic1 = String.class, - doc = "A list of strings, the names of the files to export."), - // TODO(blaze-team): make it possible to express a list of label designators, - // i.e. a java List or Skylark list of Label or String. - @Param(name = "visibility", type = SkylarkList.class, noneable = true, - defaultValue = "None", - doc = "A list of Labels specifying the visibility of the exported files " - + "(defaults to public)"), - @Param(name = "licenses", type = SkylarkList.class, generic1 = String.class, - noneable = true, defaultValue = "None", - doc = "A list of strings specifying the licenses used in the exported code.")}, - documented = false, useAst = true, useEnvironment = true) + /** Returns a function-value implementing "exports_files" in the specified package context. */ + @SkylarkSignature( + name = "exports_files", + returnType = Runtime.NoneType.class, + doc = "Declare a set of files as exported", + parameters = { + @Param( + name = "srcs", + type = SkylarkList.class, + generic1 = String.class, + doc = "A list of strings, the names of the files to export." + ), + // TODO(blaze-team): make it possible to express a list of label designators, + // i.e. a java List or Skylark list of Label or String. + @Param( + name = "visibility", + type = SkylarkList.class, + noneable = true, + defaultValue = "None", + doc = + "A list of Labels specifying the visibility of the exported files " + + "(defaults to public)." + ), + @Param( + name = "licenses", + type = SkylarkList.class, + generic1 = String.class, + noneable = true, + defaultValue = "None", + doc = "A list of strings specifying the licenses used in the exported code." + ) + }, + documented = false, + useAst = true, + useEnvironment = true + ) private static final BuiltinFunction.Factory newExportsFilesFunction = new BuiltinFunction.Factory("exports_files") { - public BuiltinFunction create () { + public BuiltinFunction create() { return new BuiltinFunction("exports_files", this) { public Runtime.NoneType invoke( - SkylarkList srcs, Object visibility, Object licenses, - FuncallExpression ast, Environment env) + SkylarkList srcs, + Object visibility, + Object licenses, + FuncallExpression ast, + Environment env) throws EvalException, ConversionException { return callExportsFiles(srcs, visibility, licenses, ast, env); } @@ -856,29 +880,53 @@ public final class PackageFactory { } }; - @SkylarkSignature(name = "package_group", returnType = Runtime.NoneType.class, - doc = "Declare a set of files as exported", - parameters = { - @Param(name = "name", type = String.class, named = true, positional = false, - doc = "The name of the rule."), - @Param(name = "packages", type = SkylarkList.class, generic1 = String.class, - defaultValue = "[]", - named = true, - positional = false, - doc = "A list of Strings specifying the packages grouped."), - // java list or list of label designators: Label or String - @Param(name = "includes", type = SkylarkList.class, generic1 = Object.class, - defaultValue = "[]", - named = true, - positional = false, - doc = "A list of Label specifiers for the files to include.")}, - documented = false, useAst = true, useEnvironment = true) + @SkylarkSignature( + name = "package_group", + returnType = Runtime.NoneType.class, + doc = "Declare a set of files as exported.", + parameters = { + @Param( + name = "name", + type = String.class, + named = true, + positional = false, + doc = "The name of the rule." + ), + @Param( + name = "packages", + type = SkylarkList.class, + generic1 = String.class, + defaultValue = "[]", + named = true, + positional = false, + doc = "A list of Strings specifying the packages grouped." + ), + // java list or list of label designators: Label or String + @Param( + name = "includes", + type = SkylarkList.class, + generic1 = Object.class, + defaultValue = "[]", + named = true, + positional = false, + doc = "A list of Label specifiers for the files to include." + ) + }, + documented = false, + useAst = true, + useEnvironment = true + ) private static final BuiltinFunction.Factory newPackageGroupFunction = new BuiltinFunction.Factory("package_group") { public BuiltinFunction create() { return new BuiltinFunction("package_group", this) { - public Runtime.NoneType invoke(String name, SkylarkList packages, SkylarkList includes, - FuncallExpression ast, Environment env) throws EvalException, ConversionException { + public Runtime.NoneType invoke( + String name, + SkylarkList packages, + SkylarkList includes, + FuncallExpression ast, + Environment env) + throws EvalException, ConversionException { return callPackageFunction(name, packages, includes, ast, env); } }; diff --git a/src/main/java/com/google/devtools/build/lib/rules/SkylarkAttr.java b/src/main/java/com/google/devtools/build/lib/rules/SkylarkAttr.java index 46610f40d1..fe4547ec9b 100644 --- a/src/main/java/com/google/devtools/build/lib/rules/SkylarkAttr.java +++ b/src/main/java/com/google/devtools/build/lib/rules/SkylarkAttr.java @@ -706,7 +706,7 @@ public final class SkylarkAttr { @SkylarkSignature( name = "int_list", - doc = "Creates an attribute which is a <a href=\"list.html\">list</a> of ints", + doc = "Creates an attribute which is a <a href=\"list.html\">list</a> of ints.", objectType = SkylarkAttr.class, returnType = Descriptor.class, parameters = { diff --git a/src/main/java/com/google/devtools/build/lib/rules/SkylarkCommandLine.java b/src/main/java/com/google/devtools/build/lib/rules/SkylarkCommandLine.java index 7fd5fe4dc4..6267493cd5 100644 --- a/src/main/java/com/google/devtools/build/lib/rules/SkylarkCommandLine.java +++ b/src/main/java/com/google/devtools/build/lib/rules/SkylarkCommandLine.java @@ -37,21 +37,31 @@ import com.google.devtools.build.lib.syntax.SkylarkSignatureProcessor; ) public class SkylarkCommandLine { - @SkylarkSignature(name = "join_paths", objectType = SkylarkCommandLine.class, - returnType = String.class, - doc = "Creates a single command line argument joining the paths of a set " - + "of files on the separator string.", - parameters = { - @Param(name = "separator", type = String.class, doc = "the separator string to join on"), - @Param(name = "files", type = SkylarkNestedSet.class, generic1 = Artifact.class, - doc = "the files to concatenate")}) - private static BuiltinFunction joinPaths = new BuiltinFunction("join_paths") { - public String invoke(String separator, SkylarkNestedSet files) { - NestedSet<Artifact> artifacts = files.getSet(Artifact.class); - // TODO(bazel-team): lazy evaluate - return Artifact.joinExecPaths(separator, artifacts); + @SkylarkSignature( + name = "join_paths", + objectType = SkylarkCommandLine.class, + returnType = String.class, + doc = + "Creates a single command line argument joining the paths of a set " + + "of files on the separator string.", + parameters = { + @Param(name = "separator", type = String.class, doc = "the separator string to join on."), + @Param( + name = "files", + type = SkylarkNestedSet.class, + generic1 = Artifact.class, + doc = "the files to concatenate." + ) } - }; + ) + private static BuiltinFunction joinPaths = + new BuiltinFunction("join_paths") { + public String invoke(String separator, SkylarkNestedSet files) { + NestedSet<Artifact> artifacts = files.getSet(Artifact.class); + // TODO(bazel-team): lazy evaluate + return Artifact.joinExecPaths(separator, artifacts); + } + }; // TODO(bazel-team): this method should support sets of objects and substitute all struct fields. @SkylarkSignature(name = "template", diff --git a/src/main/java/com/google/devtools/build/lib/rules/SkylarkRuleClassFunctions.java b/src/main/java/com/google/devtools/build/lib/rules/SkylarkRuleClassFunctions.java index 49c5d89c64..77341359a3 100644 --- a/src/main/java/com/google/devtools/build/lib/rules/SkylarkRuleClassFunctions.java +++ b/src/main/java/com/google/devtools/build/lib/rules/SkylarkRuleClassFunctions.java @@ -194,15 +194,18 @@ public class SkylarkRuleClassFunctions { .build(); } - @SkylarkSignature(name = "struct", returnType = SkylarkClassObject.class, doc = - "Creates an immutable struct using the keyword arguments as attributes. It is used to group " - + "multiple values together. Example:<br>" - + "<pre class=\"language-python\">s = struct(x = 2, y = 3)\n" - + "return s.x + getattr(s, \"y\") # returns 5</pre>", - extraKeywords = @Param(name = "kwargs", doc = "the struct attributes"), - useLocation = true) - private static final SkylarkClassObjectConstructor struct = - SkylarkClassObjectConstructor.STRUCT; + @SkylarkSignature( + name = "struct", + returnType = SkylarkClassObject.class, + doc = + "Creates an immutable struct using the keyword arguments as attributes. It is used to " + + "group multiple values together. Example:<br>" + + "<pre class=\"language-python\">s = struct(x = 2, y = 3)\n" + + "return s.x + getattr(s, \"y\") # returns 5</pre>", + extraKeywords = @Param(name = "kwargs", doc = "the struct attributes."), + useLocation = true + ) + private static final SkylarkClassObjectConstructor struct = SkylarkClassObjectConstructor.STRUCT; // TODO(bazel-team): Move to a "testing" namespace module. Normally we'd pass an objectType // to @SkylarkSignature to do this, but that doesn't work here because we're exposing an already- @@ -738,47 +741,54 @@ public class SkylarkRuleClassFunctions { } } - @SkylarkSignature(name = "Label", doc = "Creates a Label referring to a BUILD target. Use " - + "this function only when you want to give a default value for the label attributes. " - + "The argument must refer to an absolute label. " - + "Example: <br><pre class=language-python>Label(\"//tools:default\")</pre>", - returnType = Label.class, - objectType = Label.class, - parameters = {@Param(name = "label_string", type = String.class, - doc = "the label string"), - @Param( - name = "relative_to_caller_repository", - type = Boolean.class, - defaultValue = "False", - named = true, - positional = false, - doc = "whether the label should be resolved relative to the label of the file this " - + "function is called from.")}, - useLocation = true, - useEnvironment = true) - private static final BuiltinFunction label = new BuiltinFunction("Label") { - @SuppressWarnings({"unchecked", "unused"}) - public Label invoke( - String labelString, Boolean relativeToCallerRepository, Location loc, Environment env) - throws EvalException { - Label parentLabel = null; - if (relativeToCallerRepository) { - parentLabel = env.getCallerLabel(); - } else { - parentLabel = env.getGlobals().label(); - } - try { - if (parentLabel != null) { - LabelValidator.parseAbsoluteLabel(labelString); - labelString = parentLabel.getRelative(labelString) - .getUnambiguousCanonicalForm(); + @SkylarkSignature( + name = "Label", + doc = + "Creates a Label referring to a BUILD target. Use " + + "this function only when you want to give a default value for the label attributes. " + + "The argument must refer to an absolute label. " + + "Example: <br><pre class=language-python>Label(\"//tools:default\")</pre>", + returnType = Label.class, + objectType = Label.class, + parameters = { + @Param(name = "label_string", type = String.class, doc = "the label string."), + @Param( + name = "relative_to_caller_repository", + type = Boolean.class, + defaultValue = "False", + named = true, + positional = false, + doc = + "whether the label should be resolved relative to the label of the file this " + + "function is called from." + ) + }, + useLocation = true, + useEnvironment = true + ) + private static final BuiltinFunction label = + new BuiltinFunction("Label") { + @SuppressWarnings({"unchecked", "unused"}) + public Label invoke( + String labelString, Boolean relativeToCallerRepository, Location loc, Environment env) + throws EvalException { + Label parentLabel = null; + if (relativeToCallerRepository) { + parentLabel = env.getCallerLabel(); + } else { + parentLabel = env.getGlobals().label(); + } + try { + if (parentLabel != null) { + LabelValidator.parseAbsoluteLabel(labelString); + labelString = parentLabel.getRelative(labelString).getUnambiguousCanonicalForm(); + } + return labelCache.get(labelString); + } catch (LabelValidator.BadLabelException | LabelSyntaxException | ExecutionException e) { + throw new EvalException(loc, "Illegal absolute label syntax: " + labelString); + } } - return labelCache.get(labelString); - } catch (LabelValidator.BadLabelException | LabelSyntaxException | ExecutionException e) { - throw new EvalException(loc, "Illegal absolute label syntax: " + labelString); - } - } - }; + }; // We want the Label ctor to show up under the Label documentation, but to be a "global // function." Thus, we create a global Label object here, which just points to the Skylark @@ -787,20 +797,30 @@ public class SkylarkRuleClassFunctions { documented = false) private static final BuiltinFunction globalLabel = label; - @SkylarkSignature(name = "FileType", - doc = "Deprecated. Creates a file filter from a list of strings. For example, to match " - + "files ending with .cc or .cpp, use: " - + "<pre class=language-python>FileType([\".cc\", \".cpp\"])</pre>", - returnType = SkylarkFileType.class, - objectType = SkylarkFileType.class, - parameters = { - @Param(name = "types", type = SkylarkList.class, generic1 = String.class, - defaultValue = "[]", doc = "a list of the accepted file extensions")}) - private static final BuiltinFunction fileType = new BuiltinFunction("FileType") { - public SkylarkFileType invoke(SkylarkList types) throws EvalException { - return SkylarkFileType.of(types.getContents(String.class, "types")); + @SkylarkSignature( + name = "FileType", + doc = + "Deprecated. Creates a file filter from a list of strings. For example, to match " + + "files ending with .cc or .cpp, use: " + + "<pre class=language-python>FileType([\".cc\", \".cpp\"])</pre>", + returnType = SkylarkFileType.class, + objectType = SkylarkFileType.class, + parameters = { + @Param( + name = "types", + type = SkylarkList.class, + generic1 = String.class, + defaultValue = "[]", + doc = "a list of the accepted file extensions." + ) } - }; + ) + private static final BuiltinFunction fileType = + new BuiltinFunction("FileType") { + public SkylarkFileType invoke(SkylarkList types) throws EvalException { + return SkylarkFileType.of(types.getContents(String.class, "types")); + } + }; // We want the FileType ctor to show up under the FileType documentation, but to be a "global // function." Thus, we create a global FileType object here, which just points to the Skylark @@ -809,89 +829,103 @@ public class SkylarkRuleClassFunctions { documented = false) private static final BuiltinFunction globalFileType = fileType; - @SkylarkSignature(name = "to_proto", - doc = "Creates a text message from the struct parameter. This method only works if all " - + "struct elements (recursively) are strings, ints, booleans, other structs or a " - + "list of these types. Quotes and new lines in strings are escaped. " - + "Keys are iterated in the sorted order. " - + "Examples:<br><pre class=language-python>" - + "struct(key=123).to_proto()\n# key: 123\n\n" - + "struct(key=True).to_proto()\n# key: true\n\n" - + "struct(key=[1, 2, 3]).to_proto()\n# key: 1\n# key: 2\n# key: 3\n\n" - + "struct(key='text').to_proto()\n# key: \"text\"\n\n" - + "struct(key=struct(inner_key='text')).to_proto()\n" - + "# key {\n# inner_key: \"text\"\n# }\n\n" - + "struct(key=[struct(inner_key=1), struct(inner_key=2)]).to_proto()\n" - + "# key {\n# inner_key: 1\n# }\n# key {\n# inner_key: 2\n# }\n\n" - + "struct(key=struct(inner_key=struct(inner_inner_key='text'))).to_proto()\n" - + "# key {\n# inner_key {\n# inner_inner_key: \"text\"\n# }\n# }\n</pre>", - objectType = SkylarkClassObject.class, returnType = String.class, - parameters = { - // TODO(bazel-team): shouldn't we accept any ClassObject? - @Param(name = "self", type = SkylarkClassObject.class, - doc = "this struct")}, - useLocation = true) - private static final BuiltinFunction toProto = new BuiltinFunction("to_proto") { - public String invoke(SkylarkClassObject self, Location loc) throws EvalException { - StringBuilder sb = new StringBuilder(); - printProtoTextMessage(self, sb, 0, loc); - return sb.toString(); - } + @SkylarkSignature( + name = "to_proto", + doc = + "Creates a text message from the struct parameter. This method only works if all " + + "struct elements (recursively) are strings, ints, booleans, other structs or a " + + "list of these types. Quotes and new lines in strings are escaped. " + + "Keys are iterated in the sorted order. " + + "Examples:<br><pre class=language-python>" + + "struct(key=123).to_proto()\n# key: 123\n\n" + + "struct(key=True).to_proto()\n# key: true\n\n" + + "struct(key=[1, 2, 3]).to_proto()\n# key: 1\n# key: 2\n# key: 3\n\n" + + "struct(key='text').to_proto()\n# key: \"text\"\n\n" + + "struct(key=struct(inner_key='text')).to_proto()\n" + + "# key {\n# inner_key: \"text\"\n# }\n\n" + + "struct(key=[struct(inner_key=1), struct(inner_key=2)]).to_proto()\n" + + "# key {\n# inner_key: 1\n# }\n# key {\n# inner_key: 2\n# }\n\n" + + "struct(key=struct(inner_key=struct(inner_inner_key='text'))).to_proto()\n" + + "# key {\n# inner_key {\n# inner_inner_key: \"text\"\n# }\n# }\n</pre>", + objectType = SkylarkClassObject.class, + returnType = String.class, + parameters = { + // TODO(bazel-team): shouldn't we accept any ClassObject? + @Param(name = "self", type = SkylarkClassObject.class, doc = "this struct.") + }, + useLocation = true + ) + private static final BuiltinFunction toProto = + new BuiltinFunction("to_proto") { + public String invoke(SkylarkClassObject self, Location loc) throws EvalException { + StringBuilder sb = new StringBuilder(); + printProtoTextMessage(self, sb, 0, loc); + return sb.toString(); + } - private void printProtoTextMessage( - ClassObject object, StringBuilder sb, int indent, Location loc) throws EvalException { - // For determinism sort the keys alphabetically - List<String> keys = new ArrayList<>(object.getKeys()); - Collections.sort(keys); - for (String key : keys) { - printProtoTextMessage(key, object.getValue(key), sb, indent, loc); - } - } + private void printProtoTextMessage( + ClassObject object, StringBuilder sb, int indent, Location loc) throws EvalException { + // For determinism sort the keys alphabetically + List<String> keys = new ArrayList<>(object.getKeys()); + Collections.sort(keys); + for (String key : keys) { + printProtoTextMessage(key, object.getValue(key), sb, indent, loc); + } + } - private void printProtoTextMessage(String key, Object value, StringBuilder sb, - int indent, Location loc, String container) throws EvalException { - if (value instanceof ClassObject) { - print(sb, key + " {", indent); - printProtoTextMessage((ClassObject) value, sb, indent + 1, loc); - print(sb, "}", indent); - } else if (value instanceof String) { - print(sb, - key + ": \"" + escapeDoubleQuotesAndBackslashesAndNewlines((String) value) + "\"", - indent); - } else if (value instanceof Integer) { - print(sb, key + ": " + value, indent); - } else if (value instanceof Boolean) { - // We're relying on the fact that Java converts Booleans to Strings in the same way - // as the protocol buffers do. - print(sb, key + ": " + value, indent); - } else { - throw new EvalException(loc, - "Invalid text format, expected a struct, a string, a bool, or an int but got a " - + EvalUtils.getDataTypeName(value) + " for " + container + " '" + key + "'"); - } - } + private void printProtoTextMessage( + String key, Object value, StringBuilder sb, int indent, Location loc, String container) + throws EvalException { + if (value instanceof ClassObject) { + print(sb, key + " {", indent); + printProtoTextMessage((ClassObject) value, sb, indent + 1, loc); + print(sb, "}", indent); + } else if (value instanceof String) { + print( + sb, + key + ": \"" + escapeDoubleQuotesAndBackslashesAndNewlines((String) value) + "\"", + indent); + } else if (value instanceof Integer) { + print(sb, key + ": " + value, indent); + } else if (value instanceof Boolean) { + // We're relying on the fact that Java converts Booleans to Strings in the same way + // as the protocol buffers do. + print(sb, key + ": " + value, indent); + } else { + throw new EvalException( + loc, + "Invalid text format, expected a struct, a string, a bool, or an int but got a " + + EvalUtils.getDataTypeName(value) + + " for " + + container + + " '" + + key + + "'"); + } + } - private void printProtoTextMessage(String key, Object value, StringBuilder sb, - int indent, Location loc) throws EvalException { - if (value instanceof SkylarkList) { - for (Object item : ((SkylarkList) value)) { - // TODO(bazel-team): There should be some constraint on the fields of the structs - // in the same list but we ignore that for now. - printProtoTextMessage(key, item, sb, indent, loc, "list element in struct field"); + private void printProtoTextMessage( + String key, Object value, StringBuilder sb, int indent, Location loc) + throws EvalException { + if (value instanceof SkylarkList) { + for (Object item : ((SkylarkList) value)) { + // TODO(bazel-team): There should be some constraint on the fields of the structs + // in the same list but we ignore that for now. + printProtoTextMessage(key, item, sb, indent, loc, "list element in struct field"); + } + } else { + printProtoTextMessage(key, value, sb, indent, loc, "struct field"); + } } - } else { - printProtoTextMessage(key, value, sb, indent, loc, "struct field"); - } - } - private void print(StringBuilder sb, String text, int indent) { - for (int i = 0; i < indent; i++) { - sb.append(" "); + private void print(StringBuilder sb, String text, int indent) { + for (int i = 0; i < indent; i++) { + sb.append(" "); + } + sb.append(text); + sb.append("\n"); } - sb.append(text); - sb.append("\n"); - } - }; + }; /** * Escapes the given string for use in proto/JSON string. @@ -902,81 +936,92 @@ public class SkylarkRuleClassFunctions { return TextFormat.escapeDoubleQuotesAndBackslashes(string).replace("\n", "\\n"); } - @SkylarkSignature(name = "to_json", - doc = "Creates a JSON string from the struct parameter. This method only works if all " - + "struct elements (recursively) are strings, ints, booleans, other structs or a " - + "list of these types. Quotes and new lines in strings are escaped. " - + "Examples:<br><pre class=language-python>" - + "struct(key=123).to_json()\n# {\"key\":123}\n\n" - + "struct(key=True).to_json()\n# {\"key\":true}\n\n" - + "struct(key=[1, 2, 3]).to_json()\n# {\"key\":[1,2,3]}\n\n" - + "struct(key='text').to_json()\n# {\"key\":\"text\"}\n\n" - + "struct(key=struct(inner_key='text')).to_json()\n" - + "# {\"key\":{\"inner_key\":\"text\"}}\n\n" - + "struct(key=[struct(inner_key=1), struct(inner_key=2)]).to_json()\n" - + "# {\"key\":[{\"inner_key\":1},{\"inner_key\":2}]}\n\n" - + "struct(key=struct(inner_key=struct(inner_inner_key='text'))).to_json()\n" - + "# {\"key\":{\"inner_key\":{\"inner_inner_key\":\"text\"}}}\n</pre>", - objectType = SkylarkClassObject.class, returnType = String.class, - parameters = { - // TODO(bazel-team): shouldn't we accept any ClassObject? - @Param(name = "self", type = SkylarkClassObject.class, - doc = "this struct")}, - useLocation = true) - private static final BuiltinFunction toJson = new BuiltinFunction("to_json") { - public String invoke(SkylarkClassObject self, Location loc) throws EvalException { - StringBuilder sb = new StringBuilder(); - printJson(self, sb, loc, "struct field", null); - return sb.toString(); - } - - private void printJson(Object value, StringBuilder sb, Location loc, String container, - String key) throws EvalException { - if (value == Runtime.NONE) { - sb.append("null"); - } else if (value instanceof ClassObject) { - sb.append("{"); - - String join = ""; - for (String subKey : ((ClassObject) value).getKeys()) { - sb.append(join); - join = ","; - sb.append("\""); - sb.append(subKey); - sb.append("\":"); - printJson(((ClassObject) value).getValue(subKey), sb, loc, "struct field", subKey); - } - sb.append("}"); - } else if (value instanceof List) { - sb.append("["); - String join = ""; - for (Object item : ((List) value)) { - sb.append(join); - join = ","; - printJson(item, sb, loc, "list element in struct field", key); + @SkylarkSignature( + name = "to_json", + doc = + "Creates a JSON string from the struct parameter. This method only works if all " + + "struct elements (recursively) are strings, ints, booleans, other structs or a " + + "list of these types. Quotes and new lines in strings are escaped. " + + "Examples:<br><pre class=language-python>" + + "struct(key=123).to_json()\n# {\"key\":123}\n\n" + + "struct(key=True).to_json()\n# {\"key\":true}\n\n" + + "struct(key=[1, 2, 3]).to_json()\n# {\"key\":[1,2,3]}\n\n" + + "struct(key='text').to_json()\n# {\"key\":\"text\"}\n\n" + + "struct(key=struct(inner_key='text')).to_json()\n" + + "# {\"key\":{\"inner_key\":\"text\"}}\n\n" + + "struct(key=[struct(inner_key=1), struct(inner_key=2)]).to_json()\n" + + "# {\"key\":[{\"inner_key\":1},{\"inner_key\":2}]}\n\n" + + "struct(key=struct(inner_key=struct(inner_inner_key='text'))).to_json()\n" + + "# {\"key\":{\"inner_key\":{\"inner_inner_key\":\"text\"}}}\n</pre>", + objectType = SkylarkClassObject.class, + returnType = String.class, + parameters = { + // TODO(bazel-team): shouldn't we accept any ClassObject? + @Param(name = "self", type = SkylarkClassObject.class, doc = "this struct.") + }, + useLocation = true + ) + private static final BuiltinFunction toJson = + new BuiltinFunction("to_json") { + public String invoke(SkylarkClassObject self, Location loc) throws EvalException { + StringBuilder sb = new StringBuilder(); + printJson(self, sb, loc, "struct field", null); + return sb.toString(); } - sb.append("]"); - } else if (value instanceof String) { - sb.append("\""); - sb.append(jsonEscapeString((String) value)); - sb.append("\""); - } else if (value instanceof Integer || value instanceof Boolean) { - sb.append(value); - } else { - String errorMessage = "Invalid text format, expected a struct, a string, a bool, or an int " - + "but got a " + EvalUtils.getDataTypeName(value) + " for " + container; - if (key != null) { - errorMessage += " '" + key + "'"; + + private void printJson( + Object value, StringBuilder sb, Location loc, String container, String key) + throws EvalException { + if (value == Runtime.NONE) { + sb.append("null"); + } else if (value instanceof ClassObject) { + sb.append("{"); + + String join = ""; + for (String subKey : ((ClassObject) value).getKeys()) { + sb.append(join); + join = ","; + sb.append("\""); + sb.append(subKey); + sb.append("\":"); + printJson(((ClassObject) value).getValue(subKey), sb, loc, "struct field", subKey); + } + sb.append("}"); + } else if (value instanceof List) { + sb.append("["); + String join = ""; + for (Object item : ((List) value)) { + sb.append(join); + join = ","; + printJson(item, sb, loc, "list element in struct field", key); + } + sb.append("]"); + } else if (value instanceof String) { + sb.append("\""); + sb.append(jsonEscapeString((String) value)); + sb.append("\""); + } else if (value instanceof Integer || value instanceof Boolean) { + sb.append(value); + } else { + String errorMessage = + "Invalid text format, expected a struct, a string, a bool, or an int " + + "but got a " + + EvalUtils.getDataTypeName(value) + + " for " + + container; + if (key != null) { + errorMessage += " '" + key + "'"; + } + throw new EvalException(loc, errorMessage); + } } - throw new EvalException(loc, errorMessage); - } - } - private String jsonEscapeString(String string) { - return escapeDoubleQuotesAndBackslashesAndNewlines(string) - .replace("\r", "\\r").replace("\t", "\\t"); - } - }; + private String jsonEscapeString(String string) { + return escapeDoubleQuotesAndBackslashesAndNewlines(string) + .replace("\r", "\\r") + .replace("\t", "\\t"); + } + }; @SkylarkSignature(name = "output_group", documented = false, // TODO(dslomov): document. diff --git a/src/main/java/com/google/devtools/build/lib/rules/SkylarkRuleContext.java b/src/main/java/com/google/devtools/build/lib/rules/SkylarkRuleContext.java index 3ed2301b93..e9ce7c8e96 100644 --- a/src/main/java/com/google/devtools/build/lib/rules/SkylarkRuleContext.java +++ b/src/main/java/com/google/devtools/build/lib/rules/SkylarkRuleContext.java @@ -668,8 +668,10 @@ public final class SkylarkRuleContext { } - @SkylarkCallable(structField = true, - doc = "Dictionary (String to String) of configuration variables") + @SkylarkCallable( + structField = true, + doc = "Dictionary (String to String) of configuration variables." + ) public SkylarkDict<String, String> var() { return makeVariables; } @@ -835,8 +837,11 @@ public final class SkylarkRuleContext { return ruleContext.getAnalysisEnvironment().getVolatileWorkspaceStatusArtifact(); } - @SkylarkCallable(name = "build_file_path", structField = true, documented = true, - doc = "Returns path to the BUILD file for this rule, relative to the source root" + @SkylarkCallable( + name = "build_file_path", + structField = true, + documented = true, + doc = "Returns path to the BUILD file for this rule, relative to the source root." ) public String getBuildFileRelativePath() { Package pkg = ruleContext.getRule().getPackage(); diff --git a/src/main/java/com/google/devtools/build/lib/rules/SkylarkRuleImplementationFunctions.java b/src/main/java/com/google/devtools/build/lib/rules/SkylarkRuleImplementationFunctions.java index 3b42bc3ab2..f200cf5406 100644 --- a/src/main/java/com/google/devtools/build/lib/rules/SkylarkRuleImplementationFunctions.java +++ b/src/main/java/com/google/devtools/build/lib/rules/SkylarkRuleImplementationFunctions.java @@ -73,24 +73,19 @@ public class SkylarkRuleImplementationFunctions { // TODO(bazel-team): add all the remaining parameters // TODO(bazel-team): merge executable and arguments /** - * A Skylark built-in function to create and register a SpawnAction using a - * dictionary of parameters: - * action( - * inputs = [input1, input2, ...], - * outputs = [output1, output2, ...], - * executable = executable, - * arguments = [argument1, argument2, ...], - * mnemonic = 'Mnemonic', - * command = 'command', - * ) + * A Skylark built-in function to create and register a SpawnAction using a dictionary of + * parameters: action( inputs = [input1, input2, ...], outputs = [output1, output2, ...], + * executable = executable, arguments = [argument1, argument2, ...], mnemonic = 'Mnemonic', + * command = 'command', ) */ @SkylarkSignature( name = "action", - doc = "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.", + doc = + "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.", objectType = SkylarkRuleContext.class, returnType = Runtime.NoneType.class, parameters = { @@ -101,7 +96,7 @@ public class SkylarkRuleImplementationFunctions { generic1 = Artifact.class, named = true, positional = false, - doc = "list of the output files of the action" + doc = "list of the output files of the action." ), @Param( name = "inputs", @@ -110,20 +105,20 @@ public class SkylarkRuleImplementationFunctions { defaultValue = "[]", named = true, positional = false, - doc = "list of the input files of the action" + doc = "list of the input files of the action." ), @Param( name = "executable", type = Object.class, allowedTypes = { - @ParamType(type = Artifact.class), - @ParamType(type = PathFragment.class), - @ParamType(type = Runtime.NoneType.class), + @ParamType(type = Artifact.class), + @ParamType(type = PathFragment.class), + @ParamType(type = Runtime.NoneType.class), }, defaultValue = "None", named = true, positional = false, - doc = "the executable file to be called by the action" + doc = "the executable file to be called by the action." ), @Param( name = "arguments", @@ -132,7 +127,7 @@ public class SkylarkRuleImplementationFunctions { defaultValue = "[]", named = true, positional = false, - doc = "command line arguments of the action" + doc = "command line arguments of the action." ), @Param( name = "mnemonic", @@ -141,22 +136,23 @@ public class SkylarkRuleImplementationFunctions { defaultValue = "None", named = true, positional = false, - doc = "a one-word description of the action, e.g. CppCompile or GoLink" + 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), + @ParamType(type = String.class), + @ParamType(type = SkylarkList.class, generic1 = String.class), + @ParamType(type = Runtime.NoneType.class), }, 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." + 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", @@ -165,8 +161,9 @@ public class SkylarkRuleImplementationFunctions { 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\"" + 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", @@ -174,7 +171,7 @@ public class SkylarkRuleImplementationFunctions { defaultValue = "False", named = true, positional = false, - doc = "whether the action should use the built in shell environment or not" + doc = "whether the action should use the built in shell environment or not." ), @Param( name = "env", @@ -183,7 +180,7 @@ public class SkylarkRuleImplementationFunctions { defaultValue = "None", named = true, positional = false, - doc = "sets the dictionary of environment variables" + doc = "sets the dictionary of environment variables." ), @Param( name = "execution_requirements", @@ -192,8 +189,10 @@ public class SkylarkRuleImplementationFunctions { defaultValue = "None", named = true, positional = false, - doc = "information for scheduling the action. See " - + "<a href=\"/docs/be/common-definitions.html#common.tags\">tags</a> for useful keys." + doc = + "information for scheduling the action. See " + + "<a href=\"/docs/be/common-definitions.html#common.tags\">tags</a> " + + "for useful keys." ), @Param( name = "input_manifests", @@ -202,8 +201,9 @@ public class SkylarkRuleImplementationFunctions { defaultValue = "None", named = true, positional = false, - doc = "sets the map of input manifests files; " - + "they are typically generated by resolve_command" + doc = + "sets the map of input manifests files; " + + "they are typically generated by resolve_command." ) }, useLocation = true @@ -291,8 +291,8 @@ public class SkylarkRuleImplementationFunctions { } } - String mnemonic = mnemonicUnchecked == Runtime.NONE - ? "Generating" : (String) mnemonicUnchecked; + String mnemonic = + mnemonicUnchecked == Runtime.NONE ? "Generating" : (String) mnemonicUnchecked; builder.setMnemonic(mnemonic); if (envUnchecked != Runtime.NONE) { builder.setEnvironment( @@ -317,12 +317,12 @@ public class SkylarkRuleImplementationFunctions { } if (inputManifestsUnchecked != Runtime.NONE) { for (Map.Entry<PathFragment, Artifact> entry : - SkylarkDict.castSkylarkDictOrNoneToDict( - inputManifestsUnchecked, - PathFragment.class, - Artifact.class, - "input manifest file map") - .entrySet()) { + SkylarkDict.castSkylarkDictOrNoneToDict( + inputManifestsUnchecked, + PathFragment.class, + Artifact.class, + "input manifest file map") + .entrySet()) { builder.addInputManifest(entry.getValue(), entry.getKey()); } } @@ -332,38 +332,55 @@ public class SkylarkRuleImplementationFunctions { } }; - @SkylarkSignature(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.", - objectType = SkylarkRuleContext.class, returnType = String.class, - parameters = { - @Param(name = "self", type = SkylarkRuleContext.class, doc = "this context"), - @Param(name = "input", type = String.class, doc = "string to be expanded"), - @Param(name = "targets", type = SkylarkList.class, - generic1 = AbstractConfiguredTarget.class, defaultValue = "[]", - doc = "list of targets for additional lookup information"), - }, - useLocation = true, useEnvironment = true) - private static final BuiltinFunction expandLocation = new BuiltinFunction("expand_location") { - @SuppressWarnings("unused") - public String invoke(SkylarkRuleContext ctx, String input, SkylarkList targets, - Location loc, Environment env) throws EvalException { - try { - return new LocationExpander(ctx.getRuleContext(), - makeLabelMap(targets.getContents(AbstractConfiguredTarget.class, "targets")), false) - .expand(input); - } catch (IllegalStateException ise) { - throw new EvalException(loc, ise); - } - } - }; + @SkylarkSignature( + 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.", + objectType = SkylarkRuleContext.class, + returnType = String.class, + parameters = { + @Param(name = "self", type = SkylarkRuleContext.class, doc = "this context."), + @Param(name = "input", type = String.class, doc = "string to be expanded."), + @Param( + name = "targets", + type = SkylarkList.class, + generic1 = AbstractConfiguredTarget.class, + defaultValue = "[]", + doc = "list of targets for additional lookup information." + ), + }, + useLocation = true, + useEnvironment = true + ) + private static final BuiltinFunction expandLocation = + new BuiltinFunction("expand_location") { + @SuppressWarnings("unused") + public String invoke( + SkylarkRuleContext ctx, + String input, + SkylarkList targets, + Location loc, + Environment env) + throws EvalException { + try { + return new LocationExpander( + ctx.getRuleContext(), + makeLabelMap(targets.getContents(AbstractConfiguredTarget.class, "targets")), + false) + .expand(input); + } catch (IllegalStateException ise) { + throw new EvalException(loc, ise); + } + } + }; /** * Builds a map: Label -> List of files from the given labels @@ -390,14 +407,14 @@ public class SkylarkRuleImplementationFunctions { objectType = SkylarkRuleContext.class, returnType = Runtime.NoneType.class, parameters = { - @Param(name = "self", type = SkylarkRuleContext.class, doc = "this context"), - @Param(name = "output", type = Artifact.class, doc = "the output file"), - @Param(name = "content", type = String.class, doc = "the contents of the file"), + @Param(name = "self", type = SkylarkRuleContext.class, doc = "this context."), + @Param(name = "output", type = Artifact.class, doc = "the output file."), + @Param(name = "content", type = String.class, doc = "the contents of the file."), @Param( name = "executable", type = Boolean.class, defaultValue = "False", - doc = "whether the output file should be executable (default is False)" + doc = "whether the output file should be executable (default is False)." ) } ) @@ -413,91 +430,141 @@ public class SkylarkRuleImplementationFunctions { } }; - @SkylarkSignature(name = "empty_action", - doc = - "Creates an empty action that neither executes a command nor produces any " - + "output, but that is useful for inserting 'extra actions'.", - objectType = SkylarkRuleContext.class, returnType = Runtime.NoneType.class, - parameters = { - @Param(name = "self", type = SkylarkRuleContext.class, doc = "this context"), - @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", type = SkylarkList.class, generic1 = Artifact.class, - named = true, positional = false, - defaultValue = "[]", doc = "list of the input files of the action"), - }) - private static final BuiltinFunction createEmptyAction = new BuiltinFunction("empty_action") { - @SuppressWarnings("unused") - public Runtime.NoneType invoke(SkylarkRuleContext ctx, String mnemonic, SkylarkList inputs) - throws EvalException, ConversionException { - RuleContext ruleContext = ctx.getRuleContext(); - Action action = new PseudoAction<SpawnInfo>(generateUuid(ruleContext), - ruleContext.getActionOwner(), convertInputs(inputs), generateDummyOutputs(ruleContext), - mnemonic, SpawnInfo.spawnInfo, createEmptySpawnInfo()); - ruleContext.registerAction(action); - - return Runtime.NONE; + @SkylarkSignature( + name = "empty_action", + doc = + "Creates an empty action that neither executes a command nor produces any " + + "output, but that is useful for inserting 'extra actions'.", + objectType = SkylarkRuleContext.class, + returnType = Runtime.NoneType.class, + parameters = { + @Param(name = "self", type = SkylarkRuleContext.class, doc = "this context."), + @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", + type = SkylarkList.class, + generic1 = Artifact.class, + named = true, + positional = false, + defaultValue = "[]", + doc = "list of the input files of the action." + ), } + ) + private static final BuiltinFunction createEmptyAction = + new BuiltinFunction("empty_action") { + @SuppressWarnings("unused") + public Runtime.NoneType invoke(SkylarkRuleContext ctx, String mnemonic, SkylarkList inputs) + throws EvalException, ConversionException { + RuleContext ruleContext = ctx.getRuleContext(); + Action action = + new PseudoAction<SpawnInfo>( + generateUuid(ruleContext), + ruleContext.getActionOwner(), + convertInputs(inputs), + generateDummyOutputs(ruleContext), + mnemonic, + SpawnInfo.spawnInfo, + createEmptySpawnInfo()); + ruleContext.registerAction(action); - private NestedSet<Artifact> convertInputs(SkylarkList inputs) throws EvalException { - return NestedSetBuilder.<Artifact>compileOrder() - .addAll(inputs.getContents(Artifact.class, "inputs")).build(); - } + return Runtime.NONE; + } - protected UUID generateUuid(RuleContext ruleContext) { - return UUID.nameUUIDFromBytes( - String.format("empty action %s", ruleContext.getLabel()) - .getBytes(StandardCharsets.UTF_8)); - } + private NestedSet<Artifact> convertInputs(SkylarkList inputs) throws EvalException { + return NestedSetBuilder.<Artifact>compileOrder() + .addAll(inputs.getContents(Artifact.class, "inputs")) + .build(); + } - protected ImmutableList<Artifact> generateDummyOutputs(RuleContext ruleContext) { - return ImmutableList.of(PseudoAction.getDummyOutput(ruleContext)); - } + protected UUID generateUuid(RuleContext ruleContext) { + return UUID.nameUUIDFromBytes( + String.format("empty action %s", ruleContext.getLabel()) + .getBytes(StandardCharsets.UTF_8)); + } - protected SpawnInfo createEmptySpawnInfo() { - return SpawnInfo.newBuilder().build(); - } - }; + protected ImmutableList<Artifact> generateDummyOutputs(RuleContext ruleContext) { + return ImmutableList.of(PseudoAction.getDummyOutput(ruleContext)); + } - @SkylarkSignature(name = "template_action", - doc = "Creates a template expansion action.", - objectType = SkylarkRuleContext.class, - returnType = TemplateExpansionAction.class, - parameters = { - @Param(name = "self", type = SkylarkRuleContext.class, doc = "this context"), - @Param(name = "template", type = Artifact.class, - named = true, positional = false, - doc = "the template file, which is a UTF-8 encoded text file"), - @Param(name = "output", type = Artifact.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 = "executable", type = Boolean.class, defaultValue = "False", - named = true, positional = false, - doc = "whether the output file should be executable (default is False)")}) + protected SpawnInfo createEmptySpawnInfo() { + return SpawnInfo.newBuilder().build(); + } + }; + + @SkylarkSignature( + name = "template_action", + doc = "Creates a template expansion action.", + objectType = SkylarkRuleContext.class, + returnType = TemplateExpansionAction.class, + parameters = { + @Param(name = "self", type = SkylarkRuleContext.class, doc = "this context."), + @Param( + name = "template", + type = Artifact.class, + named = true, + positional = false, + doc = "the template file, which is a UTF-8 encoded text file." + ), + @Param( + name = "output", + type = Artifact.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 = "executable", + type = Boolean.class, + defaultValue = "False", + named = true, + positional = false, + doc = "whether the output file should be executable (default is False)." + ) + } + ) private static final BuiltinFunction createTemplateAction = new BuiltinFunction("template_action", Arrays.<Object>asList(false)) { - public TemplateExpansionAction invoke(SkylarkRuleContext ctx, Artifact template, - Artifact output, SkylarkDict<?, ?> substitutionsUnchecked, Boolean executable) + public TemplateExpansionAction invoke( + SkylarkRuleContext ctx, + Artifact template, + Artifact output, + SkylarkDict<?, ?> substitutionsUnchecked, + Boolean executable) throws EvalException, ConversionException { ImmutableList.Builder<Substitution> substitutionsBuilder = ImmutableList.builder(); - for (Map.Entry<String, String> substitution : substitutionsUnchecked.getContents( - String.class, String.class, "substitutions").entrySet()) { + for (Map.Entry<String, String> substitution : + substitutionsUnchecked + .getContents(String.class, String.class, "substitutions") + .entrySet()) { // ParserInputSource.create(Path) uses Latin1 when reading BUILD files, which might // contain UTF-8 encoded symbols as part of template substitution. // As a quick fix, the substitution values are corrected before being passed on. // In the long term, fixing ParserInputSource.create(Path) would be a better approach. - substitutionsBuilder.add(Substitution.of( - substitution.getKey(), convertLatin1ToUtf8(substitution.getValue()))); + substitutionsBuilder.add( + Substitution.of( + substitution.getKey(), convertLatin1ToUtf8(substitution.getValue()))); } - TemplateExpansionAction action = new TemplateExpansionAction( - ctx.getRuleContext().getActionOwner(), - template, - output, - substitutionsBuilder.build(), - executable); + TemplateExpansionAction action = + new TemplateExpansionAction( + ctx.getRuleContext().getActionOwner(), + template, + output, + substitutionsBuilder.build(), + executable); ctx.getRuleContext().registerAction(action); return action; } @@ -614,22 +681,24 @@ public class SkylarkRuleImplementationFunctions { @SkylarkSignature( name = "resolve_command", - doc = "Experimental." - + "Returns a tuple (inputs, command, input_manifests) of the list of resolved inputs, " - + "the argv list for the resolved command, and " - + "the dict mapping locations to runfiles required to run the command, " - + "all of them suitable for passing as the same-named arguments of the ctx.action method.", + doc = + "Experimental." + + "Returns a tuple (inputs, command, input_manifests) of the list of resolved inputs, " + + "the argv list for the resolved command, and " + + "the dict mapping locations to runfiles required to run the command, " + + "all of them suitable for passing as the same-named arguments of the ctx.action " + + "method.", objectType = SkylarkRuleContext.class, returnType = Tuple.class, parameters = { - @Param(name = "self", type = SkylarkRuleContext.class, doc = "this RuleContext"), + @Param(name = "self", type = SkylarkRuleContext.class, doc = "this RuleContext."), @Param( name = "command", type = String.class, // string defaultValue = "''", named = true, positional = false, - doc = "command to resolve" + doc = "command to resolve." ), @Param( name = "attribute", @@ -638,7 +707,7 @@ public class SkylarkRuleImplementationFunctions { noneable = true, named = true, positional = false, - doc = "name of the associated attribute for which to issue an error, or None" + doc = "name of the associated attribute for which to issue an error, or None." ), @Param( name = "expand_locations", @@ -646,8 +715,9 @@ public class SkylarkRuleImplementationFunctions { defaultValue = "False", named = true, positional = false, - doc = "shall we expand $(location) variables? " - + "See <a href=\"#expand_location\">ctx.expand_location()</a> for more details." + doc = + "shall we expand $(location) variables? " + + "See <a href=\"#expand_location\">ctx.expand_location()</a> for more details." ), @Param( name = "make_variables", @@ -656,7 +726,7 @@ public class SkylarkRuleImplementationFunctions { defaultValue = "None", named = true, positional = false, - doc = "make variables to expand, or None" + doc = "make variables to expand, or None." ), @Param( name = "tools", @@ -665,7 +735,7 @@ public class SkylarkRuleImplementationFunctions { generic1 = TransitiveInfoCollection.class, named = true, positional = false, - doc = "list of tools (list of targets)" + doc = "list of tools (list of targets)." ), @Param( name = "label_dict", @@ -675,7 +745,7 @@ public class SkylarkRuleImplementationFunctions { positional = false, doc = "dictionary of resolved labels and the corresponding list of Files " - + "(a dict of Label : list of Files)" + + "(a dict of Label : list of Files)" ), @Param( name = "execution_requirements", @@ -685,10 +755,12 @@ public class SkylarkRuleImplementationFunctions { positional = false, doc = "information for scheduling the action to resolve this command. See " - + "<a href=\"/docs/be/common-definitions.html#common.tags\">tags</a> for useful keys." + + "<a href=\"/docs/be/common-definitions.html#common.tags\">tags</a> " + + "for useful keys." ), }, - useLocation = true, useEnvironment = true + useLocation = true, + useEnvironment = true ) private static final BuiltinFunction resolveCommand = new BuiltinFunction("resolve_command") { @@ -708,30 +780,31 @@ public class SkylarkRuleImplementationFunctions { Label ruleLabel = ctx.getLabel(); Map<Label, Iterable<Artifact>> labelDict = checkLabelDict(labelDictUnchecked, loc); // The best way to fix this probably is to convert CommandHelper to Skylark. - CommandHelper helper = new CommandHelper( - ctx.getRuleContext(), - tools.getContents(TransitiveInfoCollection.class, "tools"), - ImmutableMap.copyOf(labelDict)); + CommandHelper helper = + new CommandHelper( + ctx.getRuleContext(), + tools.getContents(TransitiveInfoCollection.class, "tools"), + ImmutableMap.copyOf(labelDict)); String attribute = Type.STRING.convertOptional(attributeUnchecked, "attribute", ruleLabel); if (expandLocations) { - command = helper.resolveCommandAndExpandLabels( - command, attribute, false, false); + command = helper.resolveCommandAndExpandLabels(command, attribute, false, false); } if (!EvalUtils.isNullOrNone(makeVariablesUnchecked)) { - Map<String, String> makeVariables = Type.STRING_DICT.convert( - makeVariablesUnchecked, "make_variables", ruleLabel); + Map<String, String> makeVariables = + Type.STRING_DICT.convert(makeVariablesUnchecked, "make_variables", ruleLabel); command = ctx.expandMakeVariables(attribute, command, makeVariables); } List<Artifact> inputs = new ArrayList<>(); inputs.addAll(helper.getResolvedTools()); - ImmutableMap<String, String> executionRequirements = ImmutableMap.copyOf( - SkylarkDict.castSkylarkDictOrNoneToDict( - executionRequirementsUnchecked, - String.class, - String.class, - "execution_requirements")); + ImmutableMap<String, String> executionRequirements = + ImmutableMap.copyOf( + SkylarkDict.castSkylarkDictOrNoneToDict( + executionRequirementsUnchecked, + String.class, + String.class, + "execution_requirements")); List<String> argv = helper.buildCommandLine(command, inputs, SCRIPT_SUFFIX, executionRequirements); return Tuple.<Object>of( diff --git a/src/main/java/com/google/devtools/build/lib/rules/android/AndroidSkylarkApiProvider.java b/src/main/java/com/google/devtools/build/lib/rules/android/AndroidSkylarkApiProvider.java index 4caceeee3b..ed7ee96853 100644 --- a/src/main/java/com/google/devtools/build/lib/rules/android/AndroidSkylarkApiProvider.java +++ b/src/main/java/com/google/devtools/build/lib/rules/android/AndroidSkylarkApiProvider.java @@ -28,7 +28,6 @@ import com.google.devtools.build.lib.rules.java.JavaRuleOutputJarsProvider.Outpu 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 javax.annotation.Nullable; /** @@ -166,7 +165,7 @@ public class AndroidSkylarkApiProvider extends SkylarkApiProvider { @SkylarkModule( name = "AndroidSkylarkIdlInfo", category = SkylarkModuleCategory.NONE, - doc = "Provides access to information about Android rules" + doc = "Provides access to information about Android rules." ) public class IdlInfo { @SkylarkCallable( diff --git a/src/main/java/com/google/devtools/build/lib/rules/apple/AppleConfiguration.java b/src/main/java/com/google/devtools/build/lib/rules/apple/AppleConfiguration.java index 763db629b3..366a8f521a 100644 --- a/src/main/java/com/google/devtools/build/lib/rules/apple/AppleConfiguration.java +++ b/src/main/java/com/google/devtools/build/lib/rules/apple/AppleConfiguration.java @@ -42,7 +42,7 @@ import javax.annotation.Nullable; /** A configuration containing flags required for Apple platforms and tools. */ @SkylarkModule( name = "apple", - doc = "A configuration fragment for Apple platforms", + doc = "A configuration fragment for Apple platforms.", category = SkylarkModuleCategory.CONFIGURATION_FRAGMENT ) @Immutable @@ -535,7 +535,7 @@ public class AppleConfiguration extends BuildConfiguration.Fragment { /** Returns the identifier for an Xcode toolchain to use with tools. */ @SkylarkCallable( name = "xcode_toolchain", - doc = "Identifier for the custom Xcode toolchain to use in build or None if not specified", + doc = "Identifier for the custom Xcode toolchain to use in build or None if not specified.", allowReturnNones = true, structField = true ) diff --git a/src/main/java/com/google/devtools/build/lib/rules/cpp/CppConfiguration.java b/src/main/java/com/google/devtools/build/lib/rules/cpp/CppConfiguration.java index ff87b5ac09..fd205d8951 100644 --- a/src/main/java/com/google/devtools/build/lib/rules/cpp/CppConfiguration.java +++ b/src/main/java/com/google/devtools/build/lib/rules/cpp/CppConfiguration.java @@ -71,7 +71,7 @@ import java.util.Set; */ @SkylarkModule( name = "cpp", - doc = "A configuration fragment for C++", + doc = "A configuration fragment for C++.", category = SkylarkModuleCategory.CONFIGURATION_FRAGMENT ) @Immutable @@ -1795,23 +1795,28 @@ public class CppConfiguration extends BuildConfiguration.Fragment { } /** - * Returns the path to the GNU binutils 'objcopy' binary to use for this - * build. (Corresponds to $(OBJCOPY) in make-dbg.) Relative paths are - * relative to the execution root. + * Returns the path to the GNU binutils 'objcopy' binary to use for this build. (Corresponds to + * $(OBJCOPY) in make-dbg.) Relative paths are relative to the execution root. */ - @SkylarkCallable(name = "objcopy_executable", structField = true, - doc = "Path to GNU binutils 'objcopy' binary") + @SkylarkCallable( + name = "objcopy_executable", + structField = true, + doc = "Path to GNU binutils 'objcopy' binary." + ) public PathFragment getObjCopyExecutable() { return getToolPathFragment(CppConfiguration.Tool.OBJCOPY); } /** - * Returns the path to the GNU binutils 'gcc' binary that should be used - * by this build. This binary should support compilation of both C (*.c) - * and C++ (*.cc) files. Relative paths are relative to the execution root. + * Returns the path to the GNU binutils 'gcc' binary that should be used by this build. This + * binary should support compilation of both C (*.c) and C++ (*.cc) files. Relative paths are + * relative to the execution root. */ - @SkylarkCallable(name = "compiler_executable", structField = true, - doc = "Path to C/C++ compiler binary") + @SkylarkCallable( + name = "compiler_executable", + structField = true, + doc = "Path to C/C++ compiler binary." + ) public PathFragment getCppExecutable() { return getToolPathFragment(CppConfiguration.Tool.GCC); } @@ -1826,11 +1831,14 @@ public class CppConfiguration extends BuildConfiguration.Fragment { } /** - * Returns the path to the GNU binutils 'cpp' binary that should be used - * by this build. Relative paths are relative to the execution root. + * Returns the path to the GNU binutils 'cpp' binary that should be used by this build. Relative + * paths are relative to the execution root. */ - @SkylarkCallable(name = "preprocessor_executable", structField = true, - doc = "Path to C/C++ preprocessor binary") + @SkylarkCallable( + name = "preprocessor_executable", + structField = true, + doc = "Path to C/C++ preprocessor binary." + ) public PathFragment getCpreprocessorExecutable() { return getToolPathFragment(CppConfiguration.Tool.CPP); } @@ -1853,43 +1861,53 @@ public class CppConfiguration extends BuildConfiguration.Fragment { } /** - * Returns the path to the GNU binutils 'nm' executable that should be used - * by this build. Used only for testing. Relative paths are relative to the - * execution root. + * Returns the path to the GNU binutils 'nm' executable that should be used by this build. Used + * only for testing. Relative paths are relative to the execution root. */ - @SkylarkCallable(name = "nm_executable", structField = true, - doc = "Path to GNU binutils 'nm' binary") + @SkylarkCallable( + name = "nm_executable", + structField = true, + doc = "Path to GNU binutils 'nm' binary." + ) public PathFragment getNmExecutable() { return getToolPathFragment(CppConfiguration.Tool.NM); } /** - * Returns the path to the GNU binutils 'objdump' executable that should be - * used by this build. Used only for testing. Relative paths are relative to - * the execution root. + * Returns the path to the GNU binutils 'objdump' executable that should be used by this build. + * Used only for testing. Relative paths are relative to the execution root. */ - @SkylarkCallable(name = "objdump_executable", structField = true, - doc = "Path to GNU binutils 'objdump' binary") + @SkylarkCallable( + name = "objdump_executable", + structField = true, + doc = "Path to GNU binutils 'objdump' binary." + ) public PathFragment getObjdumpExecutable() { return getToolPathFragment(CppConfiguration.Tool.OBJDUMP); } /** - * Returns the path to the GNU binutils 'ar' binary to use for this build. - * Relative paths are relative to the execution root. + * Returns the path to the GNU binutils 'ar' binary to use for this build. Relative paths are + * relative to the execution root. */ - @SkylarkCallable(name = "ar_executable", structField = true, - doc = "Path to GNU binutils 'ar' binary") + @SkylarkCallable( + name = "ar_executable", + structField = true, + doc = "Path to GNU binutils 'ar' binary." + ) public PathFragment getArExecutable() { return getToolPathFragment(CppConfiguration.Tool.AR); } /** - * Returns the path to the GNU binutils 'strip' executable that should be used - * by this build. Relative paths are relative to the execution root. + * Returns the path to the GNU binutils 'strip' executable that should be used by this build. + * Relative paths are relative to the execution root. */ - @SkylarkCallable(name = "strip_executable", structField = true, - doc = "Path to GNU binutils 'strip' binary") + @SkylarkCallable( + name = "strip_executable", + structField = true, + doc = "Path to GNU binutils 'strip' binary." + ) public PathFragment getStripExecutable() { return getToolPathFragment(CppConfiguration.Tool.STRIP); } diff --git a/src/main/java/com/google/devtools/build/lib/rules/java/JavaCompilationInfoProvider.java b/src/main/java/com/google/devtools/build/lib/rules/java/JavaCompilationInfoProvider.java index 7a577eca27..8ff5d6fd58 100644 --- a/src/main/java/com/google/devtools/build/lib/rules/java/JavaCompilationInfoProvider.java +++ b/src/main/java/com/google/devtools/build/lib/rules/java/JavaCompilationInfoProvider.java @@ -29,7 +29,7 @@ import com.google.devtools.build.lib.skylarkinterface.SkylarkModuleCategory; @SkylarkModule( name = "java_compilation_info", category = SkylarkModuleCategory.NONE, - doc = "Provides access to compilation information for Java rules" + doc = "Provides access to compilation information for Java rules." ) @Immutable public class JavaCompilationInfoProvider implements TransitiveInfoProvider { @@ -73,7 +73,7 @@ public class JavaCompilationInfoProvider implements TransitiveInfoProvider { } } - @SkylarkCallable(name = "javac_options", structField = true, doc = "Options to java compiler") + @SkylarkCallable(name = "javac_options", structField = true, doc = "Options to java compiler.") public ImmutableList<String> getJavacOpts() { return javacOpts; } @@ -81,7 +81,7 @@ public class JavaCompilationInfoProvider implements TransitiveInfoProvider { @SkylarkCallable( name = "runtime_classpath", structField = true, - doc = "Run-time classpath for this Java target" + doc = "Run-time classpath for this Java target." ) public NestedSet<Artifact> getRuntimeClasspath() { return runtimeClasspath; @@ -90,7 +90,7 @@ public class JavaCompilationInfoProvider implements TransitiveInfoProvider { @SkylarkCallable( name = "compilation_classpath", structField = true, - doc = "Compilation classpath for this Java target" + doc = "Compilation classpath for this Java target." ) public NestedSet<Artifact> getCompilationClasspath() { return compilationClasspath; @@ -99,7 +99,7 @@ public class JavaCompilationInfoProvider implements TransitiveInfoProvider { @SkylarkCallable( name = "boot_classpath", structField = true, - doc = "Boot classpath for this Java target" + doc = "Boot classpath for this Java target." ) public ImmutableList<Artifact> getBootClasspath() { return bootClasspath; diff --git a/src/main/java/com/google/devtools/build/lib/rules/java/JavaConfiguration.java b/src/main/java/com/google/devtools/build/lib/rules/java/JavaConfiguration.java index 3ce52cf4d8..ecce0884b4 100644 --- a/src/main/java/com/google/devtools/build/lib/rules/java/JavaConfiguration.java +++ b/src/main/java/com/google/devtools/build/lib/rules/java/JavaConfiguration.java @@ -37,7 +37,7 @@ import javax.annotation.Nullable; @Immutable @SkylarkModule( name = "java", - doc = "A java compiler configuration", + doc = "A java compiler configuration.", category = SkylarkModuleCategory.CONFIGURATION_FRAGMENT ) public final class JavaConfiguration extends Fragment { diff --git a/src/main/java/com/google/devtools/build/lib/rules/java/JavaGenJarsProvider.java b/src/main/java/com/google/devtools/build/lib/rules/java/JavaGenJarsProvider.java index 817b14a97c..6ee4702bc1 100644 --- a/src/main/java/com/google/devtools/build/lib/rules/java/JavaGenJarsProvider.java +++ b/src/main/java/com/google/devtools/build/lib/rules/java/JavaGenJarsProvider.java @@ -22,7 +22,6 @@ import com.google.devtools.build.lib.concurrent.ThreadSafety.Immutable; 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 javax.annotation.Nullable; /** The collection of gen jars from the transitive closure. */ @@ -65,7 +64,7 @@ public final class JavaGenJarsProvider implements TransitiveInfoProvider { @SkylarkCallable( name = "enabled", structField = true, - doc = "Returns true if the Java rule uses annotation processing" + doc = "Returns true if the Java rule uses annotation processing." ) public boolean usesAnnotationProcessing() { return usesAnnotationProcessing; diff --git a/src/main/java/com/google/devtools/build/lib/rules/java/JavaRuleOutputJarsProvider.java b/src/main/java/com/google/devtools/build/lib/rules/java/JavaRuleOutputJarsProvider.java index 3cbcf252fc..c254f80a42 100644 --- a/src/main/java/com/google/devtools/build/lib/rules/java/JavaRuleOutputJarsProvider.java +++ b/src/main/java/com/google/devtools/build/lib/rules/java/JavaRuleOutputJarsProvider.java @@ -22,7 +22,6 @@ 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.util.Preconditions; - import javax.annotation.Nullable; /** Provides information about jar files produced by a Java rule. */ @@ -30,7 +29,7 @@ import javax.annotation.Nullable; @SkylarkModule( name = "java_output_jars", category = SkylarkModuleCategory.NONE, - doc = "Information about outputs of a Java rule" + doc = "Information about outputs of a Java rule." ) public final class JavaRuleOutputJarsProvider implements TransitiveInfoProvider { @@ -41,7 +40,7 @@ public final class JavaRuleOutputJarsProvider implements TransitiveInfoProvider @SkylarkModule( name = "java_output", category = SkylarkModuleCategory.NONE, - doc = "Java classes jar, together with their associated source and interface archives" + doc = "Java classes jar, together with their associated source and interface archives." ) @Immutable public static class OutputJar { @@ -59,7 +58,7 @@ public final class JavaRuleOutputJarsProvider implements TransitiveInfoProvider @Nullable @SkylarkCallable( name = "class_jar", - doc = "A classes jar file", + doc = "A classes jar file.", allowReturnNones = true, structField = true ) @@ -70,7 +69,7 @@ public final class JavaRuleOutputJarsProvider implements TransitiveInfoProvider @Nullable @SkylarkCallable( name = "ijar", - doc = "A interface jar file", + doc = "A interface jar file.", allowReturnNones = true, structField = true ) @@ -81,7 +80,7 @@ public final class JavaRuleOutputJarsProvider implements TransitiveInfoProvider @Nullable @SkylarkCallable( name = "source_jar", - doc = "A sources archive file", + doc = "A sources archive file.", allowReturnNones = true, structField = true ) diff --git a/src/main/java/com/google/devtools/build/lib/rules/java/JavaSkylarkApiProvider.java b/src/main/java/com/google/devtools/build/lib/rules/java/JavaSkylarkApiProvider.java index 39574dbfb5..1292ac065a 100644 --- a/src/main/java/com/google/devtools/build/lib/rules/java/JavaSkylarkApiProvider.java +++ b/src/main/java/com/google/devtools/build/lib/rules/java/JavaSkylarkApiProvider.java @@ -67,7 +67,7 @@ public final class JavaSkylarkApiProvider extends SkylarkApiProvider { @SkylarkCallable( name = "source_jars", - doc = "Returns the Jars containing Java source files for the target", + doc = "Returns the Jars containing Java source files for the target.", structField = true ) public NestedSet<Artifact> getSourceJars() { @@ -79,7 +79,7 @@ public final class JavaSkylarkApiProvider extends SkylarkApiProvider { @SkylarkCallable( name = "transitive_deps", - doc = "Returns the transitive set of Jars required to build the target", + doc = "Returns the transitive set of Jars required to build the target.", structField = true ) public NestedSet<Artifact> getTransitiveDeps() { @@ -91,7 +91,7 @@ public final class JavaSkylarkApiProvider extends SkylarkApiProvider { @SkylarkCallable( name = "transitive_runtime_deps", - doc = "Returns the transitive set of Jars required on the target's runtime classpath", + doc = "Returns the transitive set of Jars required on the target's runtime classpath.", structField = true ) public NestedSet<Artifact> getTransitiveRuntimeDeps() { @@ -117,7 +117,7 @@ public final class JavaSkylarkApiProvider extends SkylarkApiProvider { @SkylarkCallable( name = "outputs", - doc = "Returns information about outputs of this Java target", + doc = "Returns information about outputs of this Java target.", structField = true ) public JavaRuleOutputJarsProvider getOutputJars() { @@ -141,7 +141,7 @@ public final class JavaSkylarkApiProvider extends SkylarkApiProvider { name = "annotation_processing", structField = true, allowReturnNones = true, - doc = "Returns information about annotation processing for this Java target" + doc = "Returns information about annotation processing for this Java target." ) public JavaGenJarsProvider getGenJarsProvider() { return genJarsProvider; @@ -151,7 +151,7 @@ public final class JavaSkylarkApiProvider extends SkylarkApiProvider { name = "compilation_info", structField = true, allowReturnNones = true, - doc = "Returns compilation information for this Java target" + doc = "Returns compilation information for this Java target." ) public JavaCompilationInfoProvider getCompilationInfoProvider() { return compilationInfoProvider; diff --git a/src/main/java/com/google/devtools/build/lib/rules/objc/AppleSkylarkCommon.java b/src/main/java/com/google/devtools/build/lib/rules/objc/AppleSkylarkCommon.java index 4575bae515..1f646539d4 100644 --- a/src/main/java/com/google/devtools/build/lib/rules/objc/AppleSkylarkCommon.java +++ b/src/main/java/com/google/devtools/build/lib/rules/objc/AppleSkylarkCommon.java @@ -149,12 +149,12 @@ public class AppleSkylarkCommon { ) }, extraKeywords = - @Param( - name = "kwargs", - type = SkylarkDict.class, - defaultValue = "{}", - doc = "Dictionary of arguments" - ) + @Param( + name = "kwargs", + type = SkylarkDict.class, + defaultValue = "{}", + doc = "Dictionary of arguments." + ) ) public static final BuiltinFunction NEW_OBJC_PROVIDER = new BuiltinFunction("new_objc_provider") { diff --git a/src/main/java/com/google/devtools/build/lib/rules/objc/ObjcConfiguration.java b/src/main/java/com/google/devtools/build/lib/rules/objc/ObjcConfiguration.java index 1beb64b7f1..4a797bcada 100644 --- a/src/main/java/com/google/devtools/build/lib/rules/objc/ObjcConfiguration.java +++ b/src/main/java/com/google/devtools/build/lib/rules/objc/ObjcConfiguration.java @@ -35,7 +35,7 @@ import javax.annotation.Nullable; @SkylarkModule( name = "objc", category = SkylarkModuleCategory.CONFIGURATION_FRAGMENT, - doc = "A configuration fragment for Objective-C" + doc = "A configuration fragment for Objective-C." ) @Immutable public class ObjcConfiguration extends BuildConfiguration.Fragment { diff --git a/src/main/java/com/google/devtools/build/lib/rules/proto/ProtoSourcesProvider.java b/src/main/java/com/google/devtools/build/lib/rules/proto/ProtoSourcesProvider.java index 5220e4c47e..412cebd98a 100644 --- a/src/main/java/com/google/devtools/build/lib/rules/proto/ProtoSourcesProvider.java +++ b/src/main/java/com/google/devtools/build/lib/rules/proto/ProtoSourcesProvider.java @@ -51,13 +51,12 @@ public abstract class ProtoSourcesProvider implements TransitiveInfoProvider { } /** - * Transitive imports including weak dependencies - * This determines the order of "-I" arguments to the protocol compiler, and - * that is probably important + * Transitive imports including weak dependencies This determines the order of "-I" arguments to + * the protocol compiler, and that is probably important */ @SkylarkCallable( name = "transitive_imports", - doc = "Transitive imports including weak dependencies", + doc = "Transitive imports including weak dependencies.", structField = true ) public abstract NestedSet<Artifact> getTransitiveImports(); diff --git a/src/main/java/com/google/devtools/build/lib/syntax/BazelLibrary.java b/src/main/java/com/google/devtools/build/lib/syntax/BazelLibrary.java index 9db64d2cbf..cfee7b117d 100644 --- a/src/main/java/com/google/devtools/build/lib/syntax/BazelLibrary.java +++ b/src/main/java/com/google/devtools/build/lib/syntax/BazelLibrary.java @@ -142,8 +142,8 @@ public class BazelLibrary { "Creates a new <a href=\"depset.html\">depset</a> that contains both " + "the input depset as well as all additional elements.", parameters = { - @Param(name = "input", type = SkylarkNestedSet.class, doc = "The input depset"), - @Param(name = "new_elements", type = Iterable.class, doc = "The elements to be added") + @Param(name = "input", type = SkylarkNestedSet.class, doc = "The input depset."), + @Param(name = "new_elements", type = Iterable.class, doc = "The elements to be added.") }, useLocation = true ) diff --git a/src/main/java/com/google/devtools/build/lib/syntax/MethodLibrary.java b/src/main/java/com/google/devtools/build/lib/syntax/MethodLibrary.java index adb7b2902c..47ca735a2a 100644 --- a/src/main/java/com/google/devtools/build/lib/syntax/MethodLibrary.java +++ b/src/main/java/com/google/devtools/build/lib/syntax/MethodLibrary.java @@ -156,12 +156,12 @@ public class MethodLibrary { + "\"abcba\".lstrip(\"ba\") == \"cba\"" + "</pre>", parameters = { - @Param(name = "self", type = String.class, doc = "This string"), + @Param(name = "self", type = String.class, doc = "This string."), @Param( name = "chars", type = String.class, noneable = true, - doc = "The characters to remove, or all whitespace if None", + doc = "The characters to remove, or all whitespace if None.", defaultValue = "None" ) } @@ -185,14 +185,14 @@ public class MethodLibrary { + "\"abcba\".rstrip(\"ba\") == \"abc\"" + "</pre>", parameters = { - @Param(name = "self", type = String.class, doc = "This string"), + @Param(name = "self", type = String.class, doc = "This string."), @Param( - name = "chars", - type = String.class, - noneable = true, - doc = "The characters to remove, or all whitespace if None", - defaultValue = "None" - ) + name = "chars", + type = String.class, + noneable = true, + doc = "The characters to remove, or all whitespace if None.", + defaultValue = "None" + ) } ) private static final BuiltinFunction rstrip = @@ -214,14 +214,14 @@ public class MethodLibrary { + "\"abcba\".strip(\"ba\") == \"abc\"" + "</pre>", parameters = { - @Param(name = "self", type = String.class, doc = "This string"), + @Param(name = "self", type = String.class, doc = "This string."), @Param( - name = "chars", - type = String.class, - noneable = true, - doc = "The characters to remove, or all whitespace if None", - defaultValue = "None" - ) + name = "chars", + type = String.class, + noneable = true, + doc = "The characters to remove, or all whitespace if None.", + defaultValue = "None" + ) } ) private static final BuiltinFunction strip = @@ -941,14 +941,14 @@ public class MethodLibrary { name = "args", type = SkylarkList.class, defaultValue = "()", - doc = "List of arguments" + doc = "List of arguments." ), extraKeywords = @Param( name = "kwargs", type = SkylarkDict.class, defaultValue = "{}", - doc = "Dictionary of arguments" + doc = "Dictionary of arguments." ), useLocation = true ) @@ -1795,7 +1795,7 @@ public class MethodLibrary { "Returns a list of pairs (two-element tuples), with the index (int) and the item from" + " the input list.\n<pre class=\"language-python\">" + "enumerate([24, 21, 84]) == [(0, 24), (1, 21), (2, 84)]</pre>\n", - parameters = {@Param(name = "list", type = SkylarkList.class, doc = "input list")}, + parameters = {@Param(name = "list", type = SkylarkList.class, doc = "input list.")}, useEnvironment = true ) private static final BuiltinFunction enumerate = @@ -1811,23 +1811,25 @@ public class MethodLibrary { } }; - @SkylarkSignature(name = "hash", returnType = Integer.class, - doc = "Return a hash value for a string. This is computed deterministically using the same " - + "algorithm as Java's <code>String.hashCode()</code>, namely: " - + "<pre class=\"language-python\">s[0] * (31^(n-1)) + s[1] * (31^(n-2)) + ... + s[0]" - + "</pre> Hashing of values besides strings is not currently supported.", - // Deterministic hashing is important for the consistency of builds, hence why we - // promise a specific algorithm. This is in contrast to Java (Object.hashCode()) and - // Python, which promise stable hashing only within a given execution of the program. - parameters = { - @Param(name = "value", type = String.class, - doc = "String value to hash") - }) - private static final BuiltinFunction hash = new BuiltinFunction("hash") { - public Integer invoke(String value) throws EvalException { - return value.hashCode(); - } - }; + @SkylarkSignature( + name = "hash", + returnType = Integer.class, + doc = + "Return a hash value for a string. This is computed deterministically using the same " + + "algorithm as Java's <code>String.hashCode()</code>, namely: " + + "<pre class=\"language-python\">s[0] * (31^(n-1)) + s[1] * (31^(n-2)) + ... + s[0]" + + "</pre> Hashing of values besides strings is not currently supported.", + // Deterministic hashing is important for the consistency of builds, hence why we + // promise a specific algorithm. This is in contrast to Java (Object.hashCode()) and + // Python, which promise stable hashing only within a given execution of the program. + parameters = {@Param(name = "value", type = String.class, doc = "String value to hash.")} + ) + private static final BuiltinFunction hash = + new BuiltinFunction("hash") { + public Integer invoke(String value) throws EvalException { + return value.hashCode(); + } + }; @SkylarkSignature( name = "range", @@ -2076,44 +2078,50 @@ public class MethodLibrary { } }; - @SkylarkSignature(name = "zip", - doc = "Returns a <code>list</code> of <code>tuple</code>s, where the i-th tuple contains " - + "the i-th element from each of the argument sequences or iterables. The list has the " - + "size of the shortest input. With a single iterable argument, it returns a list of " - + "1-tuples. With no arguments, it returns an empty list. Examples:" - + "<pre class=\"language-python\">" - + "zip() # == []\n" - + "zip([1, 2]) # == [(1,), (2,)]\n" - + "zip([1, 2], [3, 4]) # == [(1, 3), (2, 4)]\n" - + "zip([1, 2], [3, 4, 5]) # == [(1, 3), (2, 4)]</pre>", - extraPositionals = @Param(name = "args", doc = "lists to zip"), - returnType = MutableList.class, useLocation = true, useEnvironment = true) - private static final BuiltinFunction zip = new BuiltinFunction("zip") { - public MutableList<?> invoke(SkylarkList<?> args, Location loc, Environment env) - throws EvalException { - Iterator<?>[] iterators = new Iterator<?>[args.size()]; - for (int i = 0; i < args.size(); i++) { - iterators[i] = EvalUtils.toIterable(args.get(i), loc).iterator(); - } - List<Tuple<?>> result = new ArrayList<>(); - boolean allHasNext; - do { - allHasNext = !args.isEmpty(); - List<Object> elem = Lists.newArrayListWithExpectedSize(args.size()); - for (Iterator<?> iterator : iterators) { - if (iterator.hasNext()) { - elem.add(iterator.next()); - } else { - allHasNext = false; + @SkylarkSignature( + name = "zip", + doc = + "Returns a <code>list</code> of <code>tuple</code>s, where the i-th tuple contains " + + "the i-th element from each of the argument sequences or iterables. The list has the " + + "size of the shortest input. With a single iterable argument, it returns a list of " + + "1-tuples. With no arguments, it returns an empty list. Examples:" + + "<pre class=\"language-python\">" + + "zip() # == []\n" + + "zip([1, 2]) # == [(1,), (2,)]\n" + + "zip([1, 2], [3, 4]) # == [(1, 3), (2, 4)]\n" + + "zip([1, 2], [3, 4, 5]) # == [(1, 3), (2, 4)]</pre>", + extraPositionals = @Param(name = "args", doc = "lists to zip."), + returnType = MutableList.class, + useLocation = true, + useEnvironment = true + ) + private static final BuiltinFunction zip = + new BuiltinFunction("zip") { + public MutableList<?> invoke(SkylarkList<?> args, Location loc, Environment env) + throws EvalException { + Iterator<?>[] iterators = new Iterator<?>[args.size()]; + for (int i = 0; i < args.size(); i++) { + iterators[i] = EvalUtils.toIterable(args.get(i), loc).iterator(); } + List<Tuple<?>> result = new ArrayList<>(); + boolean allHasNext; + do { + allHasNext = !args.isEmpty(); + List<Object> elem = Lists.newArrayListWithExpectedSize(args.size()); + for (Iterator<?> iterator : iterators) { + if (iterator.hasNext()) { + elem.add(iterator.next()); + } else { + allHasNext = false; + } + } + if (allHasNext) { + result.add(Tuple.copyOf(elem)); + } + } while (allHasNext); + return new MutableList(result, env); } - if (allHasNext) { - result.add(Tuple.copyOf(elem)); - } - } while (allHasNext); - return new MutableList(result, env); - } - }; + }; /** Skylark String module. */ @SkylarkModule( 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 f0608e6dc3..9fdabaccbf 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 @@ -42,11 +42,12 @@ public final class Runtime { doc = "Literal for the boolean false.") private static final Boolean FALSE = false; - /** - * There should be only one instance of this type to allow "== None" tests. - */ - @SkylarkModule(name = "NoneType", documented = false, - doc = "Unit type, containing the unique value None") + /** There should be only one instance of this type to allow "== None" tests. */ + @SkylarkModule( + name = "NoneType", + documented = false, + doc = "Unit type, containing the unique value None." + ) @Immutable public static final class NoneType implements SkylarkValue { private NoneType() {} diff --git a/src/main/java/com/google/devtools/build/lib/syntax/SkylarkList.java b/src/main/java/com/google/devtools/build/lib/syntax/SkylarkList.java index 8096b8c033..0a1e4afc50 100644 --- a/src/main/java/com/google/devtools/build/lib/syntax/SkylarkList.java +++ b/src/main/java/com/google/devtools/build/lib/syntax/SkylarkList.java @@ -33,10 +33,10 @@ import javax.annotation.Nullable; name = "sequence", documented = false, category = SkylarkModuleCategory.BUILTIN, - doc = "common type of lists and tuples" + doc = "common type of lists and tuples." ) -public abstract class SkylarkList<E> extends MutableCollection<E> implements List<E>, RandomAccess, - SkylarkIndexable { +public abstract class SkylarkList<E> extends MutableCollection<E> + implements List<E>, RandomAccess, SkylarkIndexable { /** * Returns an ImmutableList object with the current underlying contents of this SkylarkList. |