From 772ba9849b4115da2f97c605a41692f8c512cbaf Mon Sep 17 00:00:00 2001 From: Jordan Mele Date: Tue, 9 Jul 2024 09:09:04 -0700 Subject: [PATCH] Normalize repository starlark API docs Now that Bazel built with JDK21, Starlark builtin documentation can be made more readable in source (and easier to author, since less escaping is required). This PR refactors the repository starlark API under `src/main/java/com/google/devtools/build/lib/bazel/repository/starlark/` to use multi-line text blocks. Minor edits have also been made to some documentation (replacing unprocessed back-ticks with HTML `code` tags, adding `code` tags where I think it makes sense, capitalization, punctuation). Stats wise (excluding `test` directory) this covers; - 34 of 1101 `@StarlarkMethod(...)` (5 of 170 files) - 5 of 233 `@StarlarkBuiltin(...)` (5 of 221 files) Closes #22762. PiperOrigin-RevId: 650649974 Change-Id: I3002b8d4bccbe1d11aa6aff184b448eb1f280ba4 --- .../starlark/StarlarkBaseExternalContext.java | 299 ++++++++++-------- .../starlark/StarlarkExecutionResult.java | 16 +- .../bazel/repository/starlark/StarlarkOS.java | 26 +- .../repository/starlark/StarlarkPath.java | 57 ++-- .../starlark/StarlarkRepositoryContext.java | 112 ++++--- .../starlark/StarlarkRepositoryModule.java | 8 +- 6 files changed, 301 insertions(+), 217 deletions(-) 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;