diff --git a/src/main/java/com/google/devtools/build/lib/bazel/repository/starlark/StarlarkBaseExternalContext.java b/src/main/java/com/google/devtools/build/lib/bazel/repository/starlark/StarlarkBaseExternalContext.java index ec0c2e76548fc4..fda4fac76a9f65 100644 --- a/src/main/java/com/google/devtools/build/lib/bazel/repository/starlark/StarlarkBaseExternalContext.java +++ b/src/main/java/com/google/devtools/build/lib/bazel/repository/starlark/StarlarkBaseExternalContext.java @@ -556,8 +556,10 @@ public boolean cancel() { @StarlarkMethod( name = "wait", doc = - "Blocks until the completion of the download and returns or throws as blocking " - + " download() call would") + """ + Blocks until the completion of the download and returns or throws as blocking \ + download() call would. + """) public StructImpl await() throws InterruptedException, RepositoryFunctionException { return completeDownload(this); } @@ -599,10 +601,12 @@ private StructImpl completeDownload(PendingDownload pendingDownload) @StarlarkMethod( name = "download", doc = - "Downloads a file to the output path for the provided url and returns a struct" - + " containing success, a flag which is true if the" - + " download completed successfully, and if successful, a hash of the file" - + " with the fields sha256 and integrity.", + """ + Downloads a file to the output path for the provided url and returns a struct \ + containing success, a flag which is true if the \ + download completed successfully, and if successful, a hash of the file \ + with the fields sha256 and integrity. + """, useStarlarkThread = true, parameters = { @Param( @@ -628,34 +632,36 @@ private StructImpl completeDownload(PendingDownload pendingDownload) defaultValue = "''", named = true, doc = - "the expected SHA-256 hash of the file downloaded." - + " This must match the SHA-256 hash of the file downloaded. It is a security" - + " risk to omit the SHA-256 as remote files can change. At best omitting this" - + " field will make your build non-hermetic. It is optional to make development" - + " easier but should be set before shipping." - + " If provided, the repository cache will first be checked for a file with the" - + " given hash; a download will only be attempted if the file was not found in" - + " the cache. After a successful download, the file will be added to the cache."), + """ + The expected SHA-256 hash of the file downloaded. \ + This must match the SHA-256 hash of the file downloaded. It is a security \ + risk to omit the SHA-256 as remote files can change. At best omitting this \ + field will make your build non-hermetic. It is optional to make development \ + easier but should be set before shipping. + """), @Param( name = "executable", defaultValue = "False", named = true, - doc = "set the executable flag on the created file, false by default."), + doc = "Set the executable flag on the created file, false by default."), @Param( name = "allow_fail", defaultValue = "False", named = true, doc = - "If set, indicate the error in the return value" - + " instead of raising an error for failed downloads"), + """ + If set, indicate the error in the return value \ + instead of raising an error for failed downloads. + """), @Param( name = "canonical_id", defaultValue = "''", named = true, doc = - "If set, restrict cache hits to those cases where the file was added to the cache" - + " with the same canonical id. By default caching uses the checksum" - + "(sha256 or integrity)."), + """ + If set, restrict cache hits to those cases where the file was added to the cache \ + with the same canonical id. + """), @Param( name = "auth", defaultValue = "{}", @@ -672,24 +678,25 @@ private StructImpl completeDownload(PendingDownload pendingDownload) named = true, positional = false, doc = - "Expected checksum of the file downloaded, in Subresource Integrity format." - + " This must match the checksum of the file downloaded. It is a security" - + " risk to omit the checksum as remote files can change. At best omitting this" - + " field will make your build non-hermetic. It is optional to make development" - + " easier but should be set before shipping." - + " If provided, the repository cache will first be checked for a file with the" - + " given checksum; a download will only be attempted if the file was not found in" - + " the cache. After a successful download, the file will be added to the cache."), + """ + Expected checksum of the file downloaded, in Subresource Integrity format. \ + This must match the checksum of the file downloaded. It is a security \ + risk to omit the checksum as remote files can change. At best omitting this \ + field will make your build non-hermetic. It is optional to make development \ + easier but should be set before shipping. + """), @Param( name = "block", defaultValue = "True", named = true, positional = false, doc = - "If set to false, the call returns immediately and instead of the regular return" - + " value, it returns a token with one single method, wait(), which blocks" - + " until the download is finished and returns the usual return value or" - + " throws as usual.") + """ + If set to false, the call returns immediately and instead of the regular return \ + value, it returns a token with one single method, wait(), which blocks \ + until the download is finished and returns the usual return value or \ + throws as usual. + """) }) public Object download( Object url, @@ -786,10 +793,12 @@ public Object download( @StarlarkMethod( name = "download_and_extract", doc = - "Downloads a file to the output path for the provided url, extracts it, and returns a" - + " struct containing success, a flag which is true if the" - + " download completed successfully, and if successful, a hash of the file with the" - + " fields sha256 and integrity.", + """ + Downloads a file to the output path for the provided url, extracts it, and returns a \ + struct containing success, a flag which is true if the \ + download completed successfully, and if successful, a hash of the file with the \ + fields sha256 and integrity. + """, useStarlarkThread = true, parameters = { @Param( @@ -810,57 +819,68 @@ public Object download( defaultValue = "''", named = true, doc = - "path to the directory where the archive will be unpacked," - + " relative to the repository directory."), + """ + Path to the directory where the archive will be unpacked, \ + relative to the repository directory. + """), @Param( name = "sha256", defaultValue = "''", named = true, doc = - "the expected SHA-256 hash of the file downloaded." - + " This must match the SHA-256 hash of the file downloaded. It is a security" - + " risk to omit the SHA-256 as remote files can change. At best omitting this" - + " field will make your build non-hermetic. It is optional to make development" - + " easier but should be set before shipping." - + " If provided, the repository cache will first be checked for a file with the" - + " given hash; a download will only be attempted if the file was not found in" - + " the cache. After a successful download, the file will be added to the" - + " cache."), + """ + The expected SHA-256 hash of the file downloaded. \ + This must match the SHA-256 hash of the file downloaded. It is a security \ + risk to omit the SHA-256 as remote files can change. At best omitting this \ + field will make your build non-hermetic. It is optional to make development \ + easier but should be set before shipping. \ + If provided, the repository cache will first be checked for a file with the \ + given hash; a download will only be attempted if the file was not found in \ + the cache. After a successful download, the file will be added to the \ + cache. + """), @Param( name = "type", defaultValue = "''", named = true, doc = - "the archive type of the downloaded file. By default, the archive type is" - + " determined from the file extension of the URL. If the file has no" - + " extension, you can explicitly specify either \"zip\", \"jar\", \"war\"," - + " \"aar\", \"tar\", \"tar.gz\", \"tgz\", \"tar.xz\", \"txz\", \".tar.zst\"," - + " \".tzst\", \"tar.bz2\", \".tbz\", \".ar\", or \".deb\" here."), + """ + The archive type of the downloaded file. By default, the archive type is \ + determined from the file extension of the URL. If the file has no \ + extension, you can explicitly specify either "zip", "jar", "war", \ + "aar", "tar", "tar.gz", "tgz", "tar.xz", "txz", ".tar.zst", \ + ".tzst", "tar.bz2", ".tbz", ".ar", or ".deb" here. + """), @Param( name = "stripPrefix", defaultValue = "''", named = true, doc = - "a directory prefix to strip from the extracted files." - + "\nMany archives contain a top-level directory that contains all files in the" - + " archive. Instead of needing to specify this prefix over and over in the" - + " build_file, this field can be used to strip it from extracted" - + " files."), + """ + A directory prefix to strip from the extracted files. + Many archives contain a top-level directory that contains all files in the \ + archive. Instead of needing to specify this prefix over and over in the \ + build_file, this field can be used to strip it from extracted \ + files. + """), @Param( name = "allow_fail", defaultValue = "False", named = true, doc = - "If set, indicate the error in the return value" - + " instead of raising an error for failed downloads"), + """ + If set, indicate the error in the return value \ + instead of raising an error for failed downloads. + """), @Param( name = "canonical_id", defaultValue = "''", named = true, doc = - "If set, restrict cache hits to those cases where the file was added to the cache" - + " with the same canonical id. By default caching uses the checksum" - + "(sha256 or integrity)."), + """ + If set, restrict cache hits to those cases where the file was added to the cache \ + with the same canonical id. + """), @Param( name = "auth", defaultValue = "{}", @@ -877,25 +897,26 @@ public Object download( named = true, positional = false, doc = - "Expected checksum of the file downloaded, in Subresource Integrity format." - + " This must match the checksum of the file downloaded. It is a security" - + " risk to omit the checksum as remote files can change. At best omitting this" - + " field will make your build non-hermetic. It is optional to make development" - + " easier but should be set before shipping." - + " If provided, the repository cache will first be checked for a file with the" - + " given checksum; a download will only be attempted if the file was not found in" - + " the cache. After a successful download, the file will be added to the cache."), + """ + Expected checksum of the file downloaded, in Subresource Integrity format. \ + This must match the checksum of the file downloaded. It is a security \ + risk to omit the checksum as remote files can change. At best omitting this \ + field will make your build non-hermetic. It is optional to make development \ + easier but should be set before shipping. + """), @Param( name = "rename_files", defaultValue = "{}", named = true, positional = false, doc = - "An optional dict specifying files to rename during the extraction. Archive entries" - + " with names exactly matching a key will be renamed to the value, prior to" - + " any directory prefix adjustment. This can be used to extract archives that" - + " contain non-Unicode filenames, or which have files that would extract to" - + " the same path on case-insensitive filesystems."), + """ +An optional dict specifying files to rename during the extraction. Archive entries \ +with names exactly matching a key will be renamed to the value, prior to \ +any directory prefix adjustment. This can be used to extract archives that \ +contain non-Unicode filenames, or which have files that would extract to \ +the same path on case-insensitive filesystems. +"""), }) public StructImpl downloadAndExtract( Object url, @@ -1190,24 +1211,26 @@ public boolean isFinished() { @ParamType(type = Label.class), @ParamType(type = StarlarkPath.class) }, - doc = "path of the file to create, relative to the repository directory."), + doc = "Path of the file to create, relative to the repository directory."), @Param( name = "content", named = true, defaultValue = "''", - doc = "the content of the file to create, empty by default."), + doc = "The content of the file to create, empty by default."), @Param( name = "executable", named = true, defaultValue = "True", - doc = "set the executable flag on the created file, true by default."), + doc = "Set the executable flag on the created file, true by default."), @Param( name = "legacy_utf8", named = true, defaultValue = "True", doc = - "encode file content to UTF-8, true by default. Future versions will change" - + " the default and remove this parameter."), + """ + Encode file content to UTF-8, true by default. Future versions will change \ + the default and remove this parameter. + """), }) public void createFile( Object path, String content, Boolean executable, Boolean legacyUtf8, StarlarkThread thread) @@ -1254,18 +1277,20 @@ private static T nullIfNone(Object object, Class type) { @StarlarkMethod( name = "getenv", doc = - "Returns the value of an environment variable name as a string if exists, " - + "or default if it doesn't." - + "

When building incrementally, any change to the value of the variable named by " - + "name will cause this repository to be re-fetched.", + """ + Returns the value of an environment variable name as a string if exists, \ + or default if it doesn't. \ +

When building incrementally, any change to the value of the variable named by \ + name will cause this repository to be re-fetched. + """, parameters = { @Param( name = "name", - doc = "name of desired environment variable", + doc = "Name of desired environment variable.", allowedTypes = {@ParamType(type = String.class)}), @Param( name = "default", - doc = "Default value to return if `name` is not found", + doc = "Default value to return if name is not found.", allowedTypes = {@ParamType(type = String.class), @ParamType(type = NoneType.class)}, defaultValue = "None") }, @@ -1289,12 +1314,14 @@ public String getEnvironmentValue(String name, Object defaultValue) @StarlarkMethod( name = "path", doc = - "Returns a path from a string, label or path. If the path is relative, it will resolve " - + "relative to the repository directory. If the path is a label, it will resolve to " - + "the path of the corresponding file. Note that remote repositories are executed " - + "during the analysis phase and thus cannot depends on a target result (the " - + "label should point to a non-generated file). If path is a path, it will return " - + "that path as is.", + """ + Returns a path from a string, label or path. If the path is relative, it will resolve \ + relative to the repository directory. If the path is a label, it will resolve to \ + the path of the corresponding file. Note that remote repositories are executed \ + during the analysis phase and thus cannot depends on a target result (the \ + label should point to a non-generated file). If path is a path, it will return \ + that path as is. + """, parameters = { @Param( name = "path", @@ -1303,7 +1330,9 @@ public String getEnvironmentValue(String name, Object defaultValue) @ParamType(type = Label.class), @ParamType(type = StarlarkPath.class) }, - doc = "string, label or path from which to create a path from") + doc = + "string, Label or path from which to create" + + " a path from.") }) public StarlarkPath path(Object path) throws EvalException, InterruptedException { return getPath("path()", path); @@ -1335,19 +1364,21 @@ protected StarlarkPath getPath(String method, Object path) @ParamType(type = Label.class), @ParamType(type = StarlarkPath.class) }, - doc = "path of the file to read from."), + doc = "Path of the file to read from."), @Param( name = "watch", defaultValue = "'auto'", positional = false, named = true, doc = - "whether to watch the file. Can be the string 'yes', 'no', " - + "or 'auto'. Passing 'yes' is equivalent to immediately invoking the " - + "watch() method; passing 'no' does not " - + "attempt to watch the file; passing 'auto' will only attempt to watch the " - + "file when it is legal to do so (see watch() docs for more " - + "information.") + """ + Whether to watch the file. Can be the string 'yes', 'no', \ + or 'auto'. Passing 'yes' is equivalent to immediately invoking the \ + watch() method; passing 'no' does not \ + attempt to watch the file; passing 'auto' will only attempt to watch the \ + file when it is legal to do so (see watch() docs for more \ + information. + """) }) public String readFile(Object path, String watch, StarlarkThread thread) throws RepositoryFunctionException, EvalException, InterruptedException { @@ -1480,18 +1511,20 @@ protected void maybeWatchDirents(Path path, ShouldWatch shouldWatch) @StarlarkMethod( name = "watch", doc = - "Tells Bazel to watch for changes to the given path, whether or not it exists, or " - + "whether it's a file or a directory. Any changes to the file or directory will " - + "invalidate this repository or module extension, and cause it to be refetched or " - + "re-evaluated next time.

\"Changes\" include changes to the contents of the file " - + "(if the path is a file); if the path was a file but is now a directory, or vice " - + "versa; and if the path starts or stops existing. Notably, this does not " - + "include changes to any files under the directory if the path is a directory. For " - + "that, use path.readdir() " - + "instead.

Note that attempting to watch paths inside the repo currently being " - + "fetched, or inside the working directory of the current module extension, will " - + "result in an error. A module extension attempting to watch a path outside the " - + "current Bazel workspace will also result in an error.", + """ + Tells Bazel to watch for changes to the given path, whether or not it exists, or \ + whether it's a file or a directory. Any changes to the file or directory will \ + invalidate this repository or module extension, and cause it to be refetched or \ + re-evaluated next time.

"Changes" include changes to the contents of the file \ + (if the path is a file); if the path was a file but is now a directory, or vice \ + versa; and if the path starts or stops existing. Notably, this does not \ + include changes to any files under the directory if the path is a directory. For \ + that, use path.readdir() \ + instead.

Note that attempting to watch paths inside the repo currently being \ + fetched, or inside the working directory of the current module extension, will \ + result in an error. A module extension attempting to watch a path outside the \ + current Bazel workspace will also result in an error. + """, parameters = { @Param( name = "path", @@ -1500,7 +1533,7 @@ protected void maybeWatchDirents(Path path, ShouldWatch shouldWatch) @ParamType(type = Label.class), @ParamType(type = StarlarkPath.class) }, - doc = "path of the file to watch."), + doc = "Path of the file to watch."), }) public void watchForStarlark(Object path) throws RepositoryFunctionException, EvalException, InterruptedException { @@ -1517,13 +1550,13 @@ protected static void makeDirectories(Path path) throws IOException { @StarlarkMethod( name = "report_progress", - doc = "Updates the progress status for the fetching of this repository or module extension", + doc = "Updates the progress status for the fetching of this repository or module extension.", parameters = { @Param( name = "status", defaultValue = "''", allowedTypes = {@ParamType(type = String.class)}, - doc = "string describing the current status of the fetch progress") + doc = "string describing the current status of the fetch progress.") }) public void reportProgress(String status) { env.getListener() @@ -1692,28 +1725,32 @@ private static String profileArgsDesc(String method, List args) { @StarlarkMethod( name = "execute", doc = - "Executes the command given by the list of arguments. The execution time of the command" - + " is limited by timeout (in seconds, default 600 seconds). This method" - + " returns an exec_result structure containing the output of the" - + " command. The environment map can be used to override some" - + " environment variables to be passed to the process.", + """ + Executes the command given by the list of arguments. The execution time of the command \ + is limited by timeout (in seconds, default 600 seconds). This method \ + returns an exec_result structure containing the output of the \ + command. The environment map can be used to override some \ + environment variables to be passed to the process. + """, useStarlarkThread = true, parameters = { @Param( name = "arguments", doc = - "List of arguments, the first element should be the path to the program to " - + "execute."), + """ + List of arguments, the first element should be the path to the program to \ + execute. + """), @Param( name = "timeout", named = true, defaultValue = "600", - doc = "maximum duration of the command in seconds (default is 600 seconds)."), + doc = "Maximum duration of the command in seconds (default is 600 seconds)."), @Param( name = "environment", defaultValue = "{}", named = true, - doc = "force some environment variables to be set to be passed to the process."), + doc = "Force some environment variables to be set to be passed to the process."), @Param( name = "quiet", defaultValue = "True", @@ -1724,9 +1761,11 @@ private static String profileArgsDesc(String method, List args) { defaultValue = "\"\"", named = true, doc = - "Working directory for command execution.\n" - + "Can be relative to the repository root or absolute.\n" - + "The default is the repository root."), + """ + Working directory for command execution. + Can be relative to the repository root or absolute. + The default is the repository root. + """), }) public StarlarkExecutionResult execute( Sequence arguments, // or or

NOTE: Retrieving an environment variable from this dictionary does not " - + "establish a dependency from a repository rule or module extension to the " - + "environment variable. To establish a dependency when looking up an " - + "environment variable, use either repository_ctx.getenv or " - + "module_ctx.getenv instead.") + """ + The dictionary of environment variables. \ +

NOTE: Retrieving an environment variable from this dictionary does not \ + establish a dependency from a repository rule or module extension to the \ + environment variable. To establish a dependency when looking up an \ + environment variable, use either repository_ctx.getenv or \ + module_ctx.getenv instead. + """) public ImmutableMap getEnvironmentVariables() { return environ; } @@ -60,8 +62,10 @@ public ImmutableMap getEnvironmentVariables() { name = "name", structField = true, doc = - "A string identifying the operating system Bazel is running on (the value of the" - + " \"os.name\" Java property converted to lower case).") + """ + A string identifying the operating system Bazel is running on (the value of the \ + "os.name" Java property converted to lower case). + """) public String getName() { return System.getProperty("os.name").toLowerCase(Locale.ROOT); } @@ -70,8 +74,10 @@ public String getName() { name = "arch", structField = true, doc = - "A string identifying the architecture Bazel is running on (the value of the \"os.arch\"" - + " Java property converted to lower case).") + """ + A string identifying the architecture Bazel is running on (the value of the \ + "os.arch" Java property converted to lower case). + """) public String getArch() { return System.getProperty("os.arch").toLowerCase(Locale.ROOT); } diff --git a/src/main/java/com/google/devtools/build/lib/bazel/repository/starlark/StarlarkPath.java b/src/main/java/com/google/devtools/build/lib/bazel/repository/starlark/StarlarkPath.java index 3e676ecfdb8d78..0fda30e10f1911 100644 --- a/src/main/java/com/google/devtools/build/lib/bazel/repository/starlark/StarlarkPath.java +++ b/src/main/java/com/google/devtools/build/lib/bazel/repository/starlark/StarlarkPath.java @@ -84,8 +84,10 @@ public String getBasename() { @StarlarkMethod( name = "readdir", doc = - "Returns the list of entries in the directory denoted by this path. Each entry is a " - + "path object itself.", + """ + Returns the list of entries in the directory denoted by this path. Each entry is a \ + path object itself. + """, parameters = { @Param( name = "watch", @@ -93,15 +95,16 @@ public String getBasename() { positional = false, named = true, doc = - "whether Bazel should watch the list of entries in this directory and refetch the " - + "repository or re-evaluate the module extension next time when any changes " - + "are detected. Changes to detect include entry creation, deletion, and " - + "renaming. Note that this doesn't watch the contents of any entries " - + "in the directory.

Can be the string 'yes', 'no', or 'auto'. If set to " - + "'auto', Bazel will only watch this directory when it is legal to do so (see " - + "repository_ctx.watch() " - + "docs for more information)."), + """ + whether Bazel should watch the list of entries in this directory and refetch the \ + repository or re-evaluate the module extension next time when any changes \ + are detected. Changes to detect include entry creation, deletion, and \ + renaming. Note that this doesn't watch the contents of any entries \ + in the directory.

Can be the string 'yes', 'no', or 'auto'. If set to \ + 'auto', Bazel will only watch this directory when it is legal to do so (see \ + repository_ctx.watch() \ + docs for more information). + """), }) public ImmutableList readdir(String watch) throws EvalException, RepositoryFunctionException, InterruptedException { @@ -138,8 +141,10 @@ public StarlarkPath getDirname() { @Param( name = "relative_paths", doc = - "Zero or more relative path strings to append to this path with path separators" - + "added as needed.")) + """ + Zero or more relative path strings to append to this path with path separators \ + added as needed. + """)) public StarlarkPath getChild(Tuple relativePaths) throws EvalException { return new StarlarkPath( ctx, @@ -153,10 +158,12 @@ public StarlarkPath getChild(Tuple relativePaths) throws EvalException { name = "exists", structField = true, doc = - "Returns true if the file or directory denoted by this path exists.

Note that " - + "accessing this field does not cause the path to be watched. If you'd " - + "like the repo rule or module extension to be sensitive to the path's existence, " - + "use the watch() method on the context object.") + """ + Returns true if the file or directory denoted by this path exists.

Note that \ + accessing this field does not cause the path to be watched. If you'd \ + like the repo rule or module extension to be sensitive to the path's existence, \ + use the watch() method on the context object. + """) public boolean exists() { return path.exists(); } @@ -165,10 +172,12 @@ public boolean exists() { name = "is_dir", structField = true, doc = - "Returns true if this path points to a directory.

Note that accessing this field does " - + "not cause the path to be watched. If you'd like the repo rule or module " - + "extension to be sensitive to whether the path is a directory or a file, use the " - + "watch() method on the context object.") + """ + Returns true if this path points to a directory.

Note that accessing this field does \ + not cause the path to be watched. If you'd like the repo rule or module \ + extension to be sensitive to whether the path is a directory or a file, use the \ + watch() method on the context object. + """) public boolean isDir() { return path.isDirectory(); } @@ -177,8 +186,10 @@ public boolean isDir() { name = "realpath", structField = true, doc = - "Returns the canonical path for this path by repeatedly replacing all symbolic links " - + "with their referents.") + """ + Returns the canonical path for this path by repeatedly replacing all symbolic links \ + with their referents. + """) public StarlarkPath realpath() throws IOException { return new StarlarkPath(ctx, path.resolveSymbolicLinks()); } diff --git a/src/main/java/com/google/devtools/build/lib/bazel/repository/starlark/StarlarkRepositoryContext.java b/src/main/java/com/google/devtools/build/lib/bazel/repository/starlark/StarlarkRepositoryContext.java index 05a98da4e115f7..028f5e2ae34d56 100644 --- a/src/main/java/com/google/devtools/build/lib/bazel/repository/starlark/StarlarkRepositoryContext.java +++ b/src/main/java/com/google/devtools/build/lib/bazel/repository/starlark/StarlarkRepositoryContext.java @@ -69,10 +69,12 @@ name = "repository_ctx", category = DocCategory.BUILTIN, doc = - "The context of the repository rule containing" - + " helper functions and information about attributes. You get a repository_ctx object" - + " as an argument to the implementation function when you create a" - + " repository rule.") + """ + The context of the repository rule containing \ + helper functions and information about attributes. You get a repository_ctx object \ + as an argument to the implementation function when you create a \ + repository rule. + """) public class StarlarkRepositoryContext extends StarlarkBaseExternalContext { private final Rule rule; private final PathPackageLocator packageLocator; @@ -158,8 +160,10 @@ public StarlarkPath getWorkspaceRoot() { name = "attr", structField = true, doc = - "A struct to access the values of the attributes. The values are provided by " - + "the user (if not, a default value is used).") + """ + A struct to access the values of the attributes. The values are provided by \ + the user (if not, a default value is used). + """) public StructImpl getAttr() { return attrObject; } @@ -243,11 +247,13 @@ public void symlink(Object target, Object linkName, StarlarkThread thread) @StarlarkMethod( name = "template", doc = - "Generates a new file using a template. Every occurrence in " - + "template of a key of substitutions will be replaced by " - + "the corresponding value. The result is written in path. An optional" - + "executable argument (default to true) can be set to turn on or off" - + "the executable bit.", + """ + Generates a new file using a template. Every occurrence in \ + template of a key of substitutions will be replaced by \ + the corresponding value. The result is written in path. An optional \ + executable argument (default to true) can be set to turn on or off \ + the executable bit. + """, useStarlarkThread = true, parameters = { @Param( @@ -257,7 +263,7 @@ public void symlink(Object target, Object linkName, StarlarkThread thread) @ParamType(type = Label.class), @ParamType(type = StarlarkPath.class) }, - doc = "path of the file to create, relative to the repository directory."), + doc = "Path of the file to create, relative to the repository directory."), @Param( name = "template", allowedTypes = { @@ -265,29 +271,31 @@ public void symlink(Object target, Object linkName, StarlarkThread thread) @ParamType(type = Label.class), @ParamType(type = StarlarkPath.class) }, - doc = "path to the template file."), + doc = "Path to the template file."), @Param( name = "substitutions", defaultValue = "{}", named = true, - doc = "substitutions to make when expanding the template."), + doc = "Substitutions to make when expanding the template."), @Param( name = "executable", defaultValue = "True", named = true, - doc = "set the executable flag on the created file, true by default."), + doc = "Set the executable flag on the created file, true by default."), @Param( name = "watch_template", defaultValue = "'auto'", positional = false, named = true, doc = - "whether to watch the template file. Can be the string " - + "'yes', 'no', or 'auto'. Passing 'yes' is equivalent to immediately invoking " - + "the watch() method; passing 'no' does " - + "not attempt to watch the file; passing 'auto' will only attempt to watch " - + "the file when it is legal to do so (see watch() docs for more " - + "information."), + """ + Whether to watch the template file. Can be the string \ + 'yes', 'no', or 'auto'. Passing 'yes' is equivalent to immediately invoking \ + the watch() method; passing 'no' does \ + not attempt to watch the file; passing 'auto' will only attempt to watch \ + the file when it is legal to do so (see watch() docs for more \ + information. + """), }) public void createFileFromTemplate( Object path, @@ -356,16 +364,20 @@ protected ImmutableMap getRemoteExecProperties() throws EvalExce @StarlarkMethod( name = "delete", doc = - "Deletes a file or a directory. Returns a bool, indicating whether the file or directory" - + " was actually deleted by this call.", + """ + Deletes a file or a directory. Returns a bool, indicating whether the file or directory \ + was actually deleted by this call. + """, useStarlarkThread = true, parameters = { @Param( name = "path", allowedTypes = {@ParamType(type = String.class), @ParamType(type = StarlarkPath.class)}, doc = - "Path of the file to delete, relative to the repository directory, or absolute." - + " Can be a path or a string."), + """ + Path of the file to delete, relative to the repository directory, or absolute. \ + Can be a path or a string. + """), }) public boolean delete(Object pathObject, StarlarkThread thread) throws EvalException, RepositoryFunctionException, InterruptedException { @@ -386,12 +398,14 @@ public boolean delete(Object pathObject, StarlarkThread thread) @StarlarkMethod( name = "patch", doc = - "Apply a patch file to the root directory of external repository. " - + "The patch file should be a standard " - + "" - + "unified diff format file. " - + "The Bazel-native patch implementation doesn't support fuzz match and binary patch " - + "like the patch command line tool.", + """ + Apply a patch file to the root directory of external repository. \ + The patch file should be a standard \ + \ + unified diff format file. \ + The Bazel-native patch implementation doesn't support fuzz match and binary patch \ + like the patch command line tool. + """, useStarlarkThread = true, parameters = { @Param( @@ -402,25 +416,29 @@ public boolean delete(Object pathObject, StarlarkThread thread) @ParamType(type = StarlarkPath.class) }, doc = - "The patch file to apply, it can be label, relative path or absolute path. " - + "If it's a relative path, it will resolve to the repository directory."), + """ + The patch file to apply, it can be label, relative path or absolute path. \ + If it's a relative path, it will resolve to the repository directory. + """), @Param( name = "strip", named = true, defaultValue = "0", - doc = "strip the specified number of leading components from file names."), + doc = "Strip the specified number of leading components from file names."), @Param( name = "watch_patch", defaultValue = "'auto'", positional = false, named = true, doc = - "whether to watch the patch file. Can be the string " - + "'yes', 'no', or 'auto'. Passing 'yes' is equivalent to immediately invoking " - + "the watch() method; passing 'no' does " - + "not attempt to watch the file; passing 'auto' will only attempt to watch " - + "the file when it is legal to do so (see watch() docs for more " - + "information."), + """ + Whether to watch the patch file. Can be the string \ + 'yes', 'no', or 'auto'. Passing 'yes' is equivalent to immediately invoking \ + the watch() method; passing 'no' does \ + not attempt to watch the file; passing 'auto' will only attempt to watch \ + the file when it is legal to do so (see watch() docs for more \ + information. + """), }) public void patch(Object patchFile, StarlarkInt stripI, String watchPatch, StarlarkThread thread) throws EvalException, RepositoryFunctionException, InterruptedException { @@ -451,11 +469,13 @@ public void patch(Object patchFile, StarlarkInt stripI, String watchPatch, Starl @StarlarkMethod( name = "watch_tree", doc = - "Tells Bazel to watch for changes to any files or directories transitively under the " - + "given path. Any changes to the contents of files, the existence of files or " - + "directories, file names or directory names, will cause this repo to be " - + "refetched.

Note that attempting to watch paths inside the repo currently being " - + "fetched will result in an error. ", + """ + Tells Bazel to watch for changes to any files or directories transitively under the \ + given path. Any changes to the contents of files, the existence of files or \ + directories, file names or directory names, will cause this repo to be \ + refetched.

Note that attempting to watch paths inside the repo currently being \ + fetched will result in an error. + """, parameters = { @Param( name = "path", @@ -464,7 +484,7 @@ public void patch(Object patchFile, StarlarkInt stripI, String watchPatch, Starl @ParamType(type = Label.class), @ParamType(type = StarlarkPath.class) }, - doc = "path of the directory tree to watch."), + doc = "Path of the directory tree to watch."), }) public void watchTree(Object path) throws EvalException, InterruptedException, RepositoryFunctionException { diff --git a/src/main/java/com/google/devtools/build/lib/bazel/repository/starlark/StarlarkRepositoryModule.java b/src/main/java/com/google/devtools/build/lib/bazel/repository/starlark/StarlarkRepositoryModule.java index aa0a813e273757..dabbd64778246c 100644 --- a/src/main/java/com/google/devtools/build/lib/bazel/repository/starlark/StarlarkRepositoryModule.java +++ b/src/main/java/com/google/devtools/build/lib/bazel/repository/starlark/StarlarkRepositoryModule.java @@ -142,9 +142,11 @@ public StarlarkCallable repositoryRule( name = "repository_rule", category = DocCategory.BUILTIN, doc = - "A callable value that may be invoked during evaluation of the WORKSPACE file or within" - + " the implementation function of a module extension to instantiate and return a" - + " repository rule.") + """ + A callable value that may be invoked during evaluation of the WORKSPACE file or within \ + the implementation function of a module extension to instantiate and return a \ + repository rule. + """) public static final class RepositoryRuleFunction implements StarlarkCallable, StarlarkExportable, RuleFunction { private final RuleClass.Builder builder;