bazel
/
bazel-lib
mirror of https://github.com/bazel-contrib/bazel-lib
2
0
Fork 0
Code Issues Releases Activity

chore(deps): upgrade stardoc (#894) 

* chore(deps): upgrade stardoc

This uses the Bazel 7 'starlark_doc_extract' rule which our docsite expects for slurping data.

* chore: stardoc setup in WORKSPACE too

* chore: skip stardoc on bazel 6 in cases where the legacy extractor produces different docstrings
This commit is contained in:
Alex Eagle 2024-08-08 12:56:11 -07:00 committed by GitHub
parent 109f32eefb
commit 0f5e1dcafd
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
47 changed files with 841 additions and 880 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
MODULE.bazel
View File

@ -12,7 +12,7 @@ bazel_dep(name = "bazel_skylib", version = "1.5.0")
bazel_dep(name = "platforms", version = "0.0.8") bazel_dep(name = "platforms", version = "0.0.8")
# 0.5.4 is the first version with bzlmod support # 0.5.4 is the first version with bzlmod support
bazel_dep(name = "stardoc", version = "0.5.4", repo_name = "io_bazel_stardoc") bazel_dep(name = "stardoc", version = "0.6.2", repo_name = "io_bazel_stardoc")
bazel_lib_toolchains = use_extension("@aspect_bazel_lib//lib:extensions.bzl", "toolchains") bazel_lib_toolchains = use_extension("@aspect_bazel_lib//lib:extensions.bzl", "toolchains")
bazel_lib_toolchains.copy_directory() bazel_lib_toolchains.copy_directory()

16
WORKSPACE
View File

@ -18,6 +18,22 @@ load("@io_bazel_stardoc//:setup.bzl", "stardoc_repositories")
stardoc_repositories() stardoc_repositories()
load("@rules_jvm_external//:repositories.bzl", "rules_jvm_external_deps")
rules_jvm_external_deps()
load("@rules_jvm_external//:setup.bzl", "rules_jvm_external_setup")
rules_jvm_external_setup()
load("@io_bazel_stardoc//:deps.bzl", "stardoc_external_deps")
stardoc_external_deps()
load("@stardoc_maven//:defs.bzl", stardoc_pinned_maven_install = "pinned_maven_install")
stardoc_pinned_maven_install()
load("//lib:repositories.bzl", "aspect_bazel_lib_dependencies", "aspect_bazel_lib_register_toolchains") load("//lib:repositories.bzl", "aspect_bazel_lib_dependencies", "aspect_bazel_lib_register_toolchains")
aspect_bazel_lib_dependencies() aspect_bazel_lib_dependencies()

5
docs/BUILD.bazel
View File

@ -44,7 +44,6 @@ stardoc_with_diff_test(
stardoc_with_diff_test( stardoc_with_diff_test(
name = "params_file", name = "params_file",
bzl_library_target = "//lib:params_file", bzl_library_target = "//lib:params_file",
func_template = "//docs/templates:func_html.vm",
) )
stardoc_with_diff_test( stardoc_with_diff_test(
@ -162,4 +161,6 @@ stardoc_with_diff_test(
bzl_library_target = "//lib:resource_sets", bzl_library_target = "//lib:resource_sets",
) )
update_docs() update_docs(
tags = ["skip-on-bazel6"],
)

16
docs/base64.md generated
View File

@ -1,6 +1,8 @@
<!-- Generated with Stardoc: http://skydoc.bazel.build --> <!-- Generated with Stardoc: http://skydoc.bazel.build -->
Public API Utility functions for encoding and decoding strings with base64.
See https://en.wikipedia.org/wiki/Base64.
<a id="base64.decode"></a> <a id="base64.decode"></a>
@ -10,17 +12,14 @@ Public API
base64.decode(<a href="#base64.decode-data">data</a>) base64.decode(<a href="#base64.decode-data">data</a>)
</pre> </pre>
Decode a Base64 encoded string. Decode a base64 encoded string.
See https://en.wikipedia.org/wiki/Base64.
**PARAMETERS** **PARAMETERS**
| Name | Description | Default Value | | Name | Description | Default Value |
| :------------- | :------------- | :------------- | | :------------- | :------------- | :------------- |
| <a id="base64.decode-data"></a>data | base64 encoded string | none | | <a id="base64.decode-data"></a>data | base64-encoded string | none |
**RETURNS** **RETURNS**
@ -37,9 +36,6 @@ base64.encode(<a href="#base64.encode-data">data</a>)
Base64 encode a string. Base64 encode a string.
See https://en.wikipedia.org/wiki/Base64.
**PARAMETERS** **PARAMETERS**
@ -49,6 +45,6 @@ See https://en.wikipedia.org/wiki/Base64.
**RETURNS** **RETURNS**
The base64 encoded string The base64-encoded string

9
docs/bats.md generated
View File

@ -21,13 +21,12 @@ bats_test(
) )
``` ```
<a id="bats_test"></a> <a id="bats_test"></a>
## bats_test ## bats_test
<pre> <pre>
bats_test(<a href="#bats_test-name">name</a>, <a href="#bats_test-data">data</a>, <a href="#bats_test-env">env</a>, <a href="#bats_test-srcs">srcs</a>) bats_test(<a href="#bats_test-name">name</a>, <a href="#bats_test-srcs">srcs</a>, <a href="#bats_test-data">data</a>, <a href="#bats_test-env">env</a>)
</pre> </pre>
@ -38,8 +37,8 @@ bats_test(<a href="#bats_test-name">name</a>, <a href="#bats_test-data">data</a>
| Name | Description | Type | Mandatory | Default | | Name | Description | Type | Mandatory | Default |
| :------------- | :------------- | :------------- | :------------- | :------------- | | :------------- | :------------- | :------------- | :------------- | :------------- |
| <a id="bats_test-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | | | <a id="bats_test-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | |
| <a id="bats_test-data"></a>data | Runtime dependencies of the test. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | <code>[]</code> | | <a id="bats_test-srcs"></a>srcs | Test files | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | `[]` |
| <a id="bats_test-env"></a>env | Environment variables of the action.<br><br> Subject to [$(location)](https://bazel.build/reference/be/make-variables#predefined_label_variables) and ["Make variable"](https://bazel.build/reference/be/make-variables) substitution. | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a> | optional | <code>{}</code> | | <a id="bats_test-data"></a>data | Runtime dependencies of the test. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | `[]` |
| <a id="bats_test-srcs"></a>srcs | Test files | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | <code>[]</code> | | <a id="bats_test-env"></a>env | Environment variables of the action.<br><br>Subject to [$(location)](https://bazel.build/reference/be/make-variables#predefined_label_variables) and ["Make variable"](https://bazel.build/reference/be/make-variables) substitution. | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a> | optional | `{}` |

12
docs/bazelrc_presets.md generated
View File

@ -1,6 +1,8 @@
<!-- Generated with Stardoc: http://skydoc.bazel.build --> <!-- Generated with Stardoc: http://skydoc.bazel.build -->
Aspect bazelrc presets; see https://docs.aspect.build/guides/bazelrc 'Presets' for bazelrc
See https://docs.aspect.build/guides/bazelrc
<a id="write_aspect_bazelrc_presets"></a> <a id="write_aspect_bazelrc_presets"></a>
@ -16,9 +18,7 @@ This macro uses a [write_source_files](https://docs.aspect.build/rules/aspect_ba
rule under the hood to keep your presets up-to-date. rule under the hood to keep your presets up-to-date.
By default all presets are vendored but this list can be customized using By default all presets are vendored but this list can be customized using
the 'presets' attribute. the `presets` attribute.
See https://docs.aspect.build/guides/bazelrc for more info.
**PARAMETERS** **PARAMETERS**
@ -27,7 +27,7 @@ See https://docs.aspect.build/guides/bazelrc for more info.
| Name | Description | Default Value | | Name | Description | Default Value |
| :------------- | :------------- | :------------- | | :------------- | :------------- | :------------- |
| <a id="write_aspect_bazelrc_presets-name"></a>name | a unique name for this target | none | | <a id="write_aspect_bazelrc_presets-name"></a>name | a unique name for this target | none |
| <a id="write_aspect_bazelrc_presets-presets"></a>presets | a list of preset names to keep up-to-date<br><br>For example,<br><br><pre><code> write_aspect_bazelrc_presets( name = "update_aspect_bazelrc_presets", presets = [ "bazel6", "bazel7", "ci", "convenience", "correctness", "debug", "javascript", "performance", ], ) </code></pre> | <code>["bazel6", "bazel7", "ci", "convenience", "correctness", "debug", "javascript", "performance"]</code> | | <a id="write_aspect_bazelrc_presets-presets"></a>presets | a list of preset names to keep up-to-date | `["bazel6", "bazel7", "ci", "convenience", "correctness", "debug", "javascript", "performance"]` |
| <a id="write_aspect_bazelrc_presets-kwargs"></a>kwargs | Additional arguments to pass to <code>write_source_files</code> | none | | <a id="write_aspect_bazelrc_presets-kwargs"></a>kwargs | Additional arguments to pass to `write_source_files` | none |

9
docs/copy_directory.md generated
View File

@ -5,7 +5,6 @@ A rule that copies a directory to another place.
The rule uses a Bash command on Linux/macOS/non-Windows, and a cmd.exe command The rule uses a Bash command on Linux/macOS/non-Windows, and a cmd.exe command
on Windows (no Bash is required). on Windows (no Bash is required).
<a id="copy_directory"></a> <a id="copy_directory"></a>
## copy_directory ## copy_directory
@ -33,8 +32,8 @@ for more context.
| <a id="copy_directory-name"></a>name | Name of the rule. | none | | <a id="copy_directory-name"></a>name | Name of the rule. | none |
| <a id="copy_directory-src"></a>src | The directory to make a copy of. Can be a source directory or TreeArtifact. | none | | <a id="copy_directory-src"></a>src | The directory to make a copy of. Can be a source directory or TreeArtifact. | none |
| <a id="copy_directory-out"></a>out | Path of the output directory, relative to this package. | none | | <a id="copy_directory-out"></a>out | Path of the output directory, relative to this package. | none |
| <a id="copy_directory-hardlink"></a>hardlink | Controls when to use hardlinks to files instead of making copies.<br><br>Creating hardlinks is much faster than making copies of files with the caveat that hardlinks share file permissions with their source.<br><br>Since Bazel removes write permissions on files in the output tree after an action completes, hardlinks to source files within source directories is not recommended since write permissions will be inadvertently removed from sources files.<br><br>- "auto": hardlinks are used if src is a tree artifact already in the output tree - "off": files are always copied - "on": hardlinks are always used (not recommended) | <code>"auto"</code> | | <a id="copy_directory-hardlink"></a>hardlink | Controls when to use hardlinks to files instead of making copies.<br><br>Creating hardlinks is much faster than making copies of files with the caveat that hardlinks share file permissions with their source.<br><br>Since Bazel removes write permissions on files in the output tree after an action completes, hardlinks to source files within source directories is not recommended since write permissions will be inadvertently removed from sources files.<br><br>- "auto": hardlinks are used if src is a tree artifact already in the output tree - "off": files are always copied - "on": hardlinks are always used (not recommended) | `"auto"` |
| <a id="copy_directory-kwargs"></a>kwargs | further keyword arguments, e.g. <code>visibility</code> | none | | <a id="copy_directory-kwargs"></a>kwargs | further keyword arguments, e.g. `visibility` | none |
<a id="copy_directory_bin_action"></a> <a id="copy_directory_bin_action"></a>
@ -63,7 +62,7 @@ within other rule implementations.
| <a id="copy_directory_bin_action-src"></a>src | The source directory to copy. | none | | <a id="copy_directory_bin_action-src"></a>src | The source directory to copy. | none |
| <a id="copy_directory_bin_action-dst"></a>dst | The directory to copy to. Must be a TreeArtifact. | none | | <a id="copy_directory_bin_action-dst"></a>dst | The directory to copy to. Must be a TreeArtifact. | none |
| <a id="copy_directory_bin_action-copy_directory_bin"></a>copy_directory_bin | Copy to directory tool binary. | none | | <a id="copy_directory_bin_action-copy_directory_bin"></a>copy_directory_bin | Copy to directory tool binary. | none |
| <a id="copy_directory_bin_action-hardlink"></a>hardlink | Controls when to use hardlinks to files instead of making copies.<br><br>See copy_directory rule documentation for more details. | <code>"auto"</code> | | <a id="copy_directory_bin_action-hardlink"></a>hardlink | Controls when to use hardlinks to files instead of making copies.<br><br>See copy_directory rule documentation for more details. | `"auto"` |
| <a id="copy_directory_bin_action-verbose"></a>verbose | If true, prints out verbose logs to stdout | <code>False</code> | | <a id="copy_directory_bin_action-verbose"></a>verbose | If true, prints out verbose logs to stdout | `False` |

19
docs/copy_file.md generated
View File

@ -2,15 +2,14 @@
A rule that copies a file to another place. A rule that copies a file to another place.
native.genrule() is sometimes used to copy files (often wishing to rename them). `native.genrule()` is sometimes used to copy files (often wishing to rename them).
The 'copy_file' rule does this with a simpler interface than genrule. The `copy_file` rule does this with a simpler interface than genrule.
The rule uses a Bash command on Linux/macOS/non-Windows, and a cmd.exe command The rule uses a Bash command on Linux/macOS/non-Windows, and a `cmd.exe` command
on Windows (no Bash is required). on Windows (no Bash is required).
This fork of bazel-skylib's copy_file adds DirectoryPathInfo support and allows multiple This fork of bazel-skylib's copy_file adds `DirectoryPathInfo` support and allows multiple
copy_file in the same package. `copy_file` rules in the same package.
<a id="copy_file"></a> <a id="copy_file"></a>
@ -41,9 +40,9 @@ for more context.
| <a id="copy_file-name"></a>name | Name of the rule. | none | | <a id="copy_file-name"></a>name | Name of the rule. | none |
| <a id="copy_file-src"></a>src | A Label. The file to make a copy of. (Can also be the label of a rule that generates a file.) | none | | <a id="copy_file-src"></a>src | A Label. The file to make a copy of. (Can also be the label of a rule that generates a file.) | none |
| <a id="copy_file-out"></a>out | Path of the output file, relative to this package. | none | | <a id="copy_file-out"></a>out | Path of the output file, relative to this package. | none |
| <a id="copy_file-is_executable"></a>is_executable | A boolean. Whether to make the output file executable. When True, the rule's output can be executed using <code>bazel run</code> and can be in the srcs of binary and test rules that require executable sources. WARNING: If <code>allow_symlink</code> is True, <code>src</code> must also be executable. | <code>False</code> | | <a id="copy_file-is_executable"></a>is_executable | A boolean. Whether to make the output file executable. When True, the rule's output can be executed using `bazel run` and can be in the srcs of binary and test rules that require executable sources. WARNING: If `allow_symlink` is True, `src` must also be executable. | `False` |
| <a id="copy_file-allow_symlink"></a>allow_symlink | A boolean. Whether to allow symlinking instead of copying. When False, the output is always a hard copy. When True, the output *can* be a symlink, but there is no guarantee that a symlink is created (i.e., at the time of writing, we don't create symlinks on Windows). Set this to True if you need fast copying and your tools can handle symlinks (which most UNIX tools can). | <code>False</code> | | <a id="copy_file-allow_symlink"></a>allow_symlink | A boolean. Whether to allow symlinking instead of copying. When False, the output is always a hard copy. When True, the output *can* be a symlink, but there is no guarantee that a symlink is created (i.e., at the time of writing, we don't create symlinks on Windows). Set this to True if you need fast copying and your tools can handle symlinks (which most UNIX tools can). | `False` |
| <a id="copy_file-kwargs"></a>kwargs | further keyword arguments, e.g. <code>visibility</code> | none | | <a id="copy_file-kwargs"></a>kwargs | further keyword arguments, e.g. `visibility` | none |
<a id="copy_file_action"></a> <a id="copy_file_action"></a>
@ -92,6 +91,6 @@ register_coreutils_toolchains()
| <a id="copy_file_action-ctx"></a>ctx | The rule context. | none | | <a id="copy_file_action-ctx"></a>ctx | The rule context. | none |
| <a id="copy_file_action-src"></a>src | The source file to copy or TreeArtifact to copy a single file out of. | none | | <a id="copy_file_action-src"></a>src | The source file to copy or TreeArtifact to copy a single file out of. | none |
| <a id="copy_file_action-dst"></a>dst | The destination file. | none | | <a id="copy_file_action-dst"></a>dst | The destination file. | none |
| <a id="copy_file_action-dir_path"></a>dir_path | If src is a TreeArtifact, the path within the TreeArtifact to the file to copy. | <code>None</code> | | <a id="copy_file_action-dir_path"></a>dir_path | If src is a TreeArtifact, the path within the TreeArtifact to the file to copy. | `None` |

5
docs/copy_to_bin.md generated
View File

@ -8,7 +8,6 @@ command (fc.exe) on Windows (no Bash is required).
Originally authored in rules_nodejs Originally authored in rules_nodejs
https://github.com/bazelbuild/rules_nodejs/blob/8b5d27400db51e7027fe95ae413eeabea4856f8e/internal/common/copy_to_bin.bzl https://github.com/bazelbuild/rules_nodejs/blob/8b5d27400db51e7027fe95ae413eeabea4856f8e/internal/common/copy_to_bin.bzl
<a id="copy_file_to_bin_action"></a> <a id="copy_file_to_bin_action"></a>
## copy_file_to_bin_action ## copy_file_to_bin_action
@ -100,7 +99,7 @@ copy_to_bin(<a href="#copy_to_bin-name">name</a>, <a href="#copy_to_bin-srcs">sr
Copies a source file to output tree at the same workspace-relative path. Copies a source file to output tree at the same workspace-relative path.
e.g. `&lt;execroot&gt;/path/to/file -&gt; &lt;execroot&gt;/bazel-out/&lt;platform&gt;/bin/path/to/file` e.g. `<execroot>/path/to/file -> <execroot>/bazel-out/<platform>/bin/path/to/file`
If a file passed in is already in the output tree is then it is added directly to the If a file passed in is already in the output tree is then it is added directly to the
DefaultInfo provided by the rule without a copy. DefaultInfo provided by the rule without a copy.
@ -120,6 +119,6 @@ files are divided between the source tree and the output tree.
| :------------- | :------------- | :------------- | | :------------- | :------------- | :------------- |
| <a id="copy_to_bin-name"></a>name | Name of the rule. | none | | <a id="copy_to_bin-name"></a>name | Name of the rule. | none |
| <a id="copy_to_bin-srcs"></a>srcs | A list of labels. File(s) to copy. | none | | <a id="copy_to_bin-srcs"></a>srcs | A list of labels. File(s) to copy. | none |
| <a id="copy_to_bin-kwargs"></a>kwargs | further keyword arguments, e.g. <code>visibility</code> | none | | <a id="copy_to_bin-kwargs"></a>kwargs | further keyword arguments, e.g. `visibility` | none |

57
docs/copy_to_directory.md generated
View File

@ -2,15 +2,14 @@
Copy files and directories to an output directory. Copy files and directories to an output directory.
<a id="copy_to_directory"></a> <a id="copy_to_directory"></a>
## copy_to_directory ## copy_to_directory
<pre> <pre>
copy_to_directory(<a href="#copy_to_directory-name">name</a>, <a href="#copy_to_directory-allow_overwrites">allow_overwrites</a>, <a href="#copy_to_directory-exclude_srcs_packages">exclude_srcs_packages</a>, <a href="#copy_to_directory-exclude_srcs_patterns">exclude_srcs_patterns</a>, <a href="#copy_to_directory-hardlink">hardlink</a>, copy_to_directory(<a href="#copy_to_directory-name">name</a>, <a href="#copy_to_directory-srcs">srcs</a>, <a href="#copy_to_directory-out">out</a>, <a href="#copy_to_directory-allow_overwrites">allow_overwrites</a>, <a href="#copy_to_directory-exclude_srcs_packages">exclude_srcs_packages</a>, <a href="#copy_to_directory-exclude_srcs_patterns">exclude_srcs_patterns</a>,
<a href="#copy_to_directory-include_external_repositories">include_external_repositories</a>, <a href="#copy_to_directory-include_srcs_packages">include_srcs_packages</a>, <a href="#copy_to_directory-include_srcs_patterns">include_srcs_patterns</a>, <a href="#copy_to_directory-out">out</a>, <a href="#copy_to_directory-hardlink">hardlink</a>, <a href="#copy_to_directory-include_external_repositories">include_external_repositories</a>, <a href="#copy_to_directory-include_srcs_packages">include_srcs_packages</a>,
<a href="#copy_to_directory-replace_prefixes">replace_prefixes</a>, <a href="#copy_to_directory-root_paths">root_paths</a>, <a href="#copy_to_directory-srcs">srcs</a>, <a href="#copy_to_directory-verbose">verbose</a>) <a href="#copy_to_directory-include_srcs_patterns">include_srcs_patterns</a>, <a href="#copy_to_directory-replace_prefixes">replace_prefixes</a>, <a href="#copy_to_directory-root_paths">root_paths</a>, <a href="#copy_to_directory-verbose">verbose</a>)
</pre> </pre>
Copies files and directories to an output directory. Copies files and directories to an output directory.
@ -43,26 +42,24 @@ are supported with the underlying globbing library, https://github.com/bmatcuk/d
globbing library used by [gazelle](https://github.com/bazelbuild/bazel-gazelle). See https://github.com/bmatcuk/doublestar#patterns globbing library used by [gazelle](https://github.com/bazelbuild/bazel-gazelle). See https://github.com/bmatcuk/doublestar#patterns
for more information on supported globbing patterns. for more information on supported globbing patterns.
**ATTRIBUTES** **ATTRIBUTES**
| Name | Description | Type | Mandatory | Default | | Name | Description | Type | Mandatory | Default |
| :------------- | :------------- | :------------- | :------------- | :------------- | | :------------- | :------------- | :------------- | :------------- | :------------- |
| <a id="copy_to_directory-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | | | <a id="copy_to_directory-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | |
| <a id="copy_to_directory-allow_overwrites"></a>allow_overwrites | If True, allow files to be overwritten if the same output file is copied to twice.<br><br>The order of srcs matters as the last copy of a particular file will win when overwriting. Performance of copy_to_directory will be slightly degraded when allow_overwrites is True since copies cannot be parallelized out as they are calculated. Instead all copy paths must be calculated before any copies can be started. | Boolean | optional | <code>False</code> | | <a id="copy_to_directory-srcs"></a>srcs | Files and/or directories or targets that provide `DirectoryPathInfo` to copy into the output directory. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | `[]` |
| <a id="copy_to_directory-exclude_srcs_packages"></a>exclude_srcs_packages | List of Bazel packages (with glob support) to exclude from output directory.<br><br>Files in srcs are not copied to the output directory if the Bazel package of the file matches one of the patterns specified.<br><br>Forward slashes (<code>/</code>) should be used as path separators. A first character of <code>"."</code> will be replaced by the target's package path.<br><br>Files that have do not have matching Bazel packages are subject to subsequent filters and transformations to determine if they are copied and what their path in the output directory will be.<br><br>Globs are supported (see rule docstring above). | List of strings | optional | <code>[]</code> | | <a id="copy_to_directory-out"></a>out | Path of the output directory, relative to this package.<br><br>If not set, the name of the target is used. | String | optional | `""` |
| <a id="copy_to_directory-exclude_srcs_patterns"></a>exclude_srcs_patterns | List of paths (with glob support) to exclude from output directory.<br><br>Files in srcs are not copied to the output directory if their output directory path, after applying <code>root_paths</code>, matches one of the patterns specified.<br><br>Forward slashes (<code>/</code>) should be used as path separators.<br><br>Files that do not have matching output directory paths are subject to subsequent filters and transformations to determine if they are copied and what their path in the output directory will be.<br><br>Globs are supported (see rule docstring above). | List of strings | optional | <code>[]</code> | | <a id="copy_to_directory-allow_overwrites"></a>allow_overwrites | If True, allow files to be overwritten if the same output file is copied to twice.<br><br>The order of srcs matters as the last copy of a particular file will win when overwriting. Performance of copy_to_directory will be slightly degraded when allow_overwrites is True since copies cannot be parallelized out as they are calculated. Instead all copy paths must be calculated before any copies can be started. | Boolean | optional | `False` |
| <a id="copy_to_directory-hardlink"></a>hardlink | Controls when to use hardlinks to files instead of making copies.<br><br>Creating hardlinks is much faster than making copies of files with the caveat that hardlinks share file permissions with their source.<br><br>Since Bazel removes write permissions on files in the output tree after an action completes, hardlinks to source files are not recommended since write permissions will be inadvertently removed from sources files.<br><br>- <code>auto</code>: hardlinks are used for generated files already in the output tree - <code>off</code>: all files are copied - <code>on</code>: hardlinks are used for all files (not recommended) | String | optional | <code>"auto"</code> | | <a id="copy_to_directory-exclude_srcs_packages"></a>exclude_srcs_packages | List of Bazel packages (with glob support) to exclude from output directory.<br><br>Files in srcs are not copied to the output directory if the Bazel package of the file matches one of the patterns specified.<br><br>Forward slashes (`/`) should be used as path separators. A first character of `"."` will be replaced by the target's package path.<br><br>Files that have do not have matching Bazel packages are subject to subsequent filters and transformations to determine if they are copied and what their path in the output directory will be.<br><br>Globs are supported (see rule docstring above). | List of strings | optional | `[]` |
| <a id="copy_to_directory-include_external_repositories"></a>include_external_repositories | List of external repository names (with glob support) to include in the output directory.<br><br>Files from external repositories are only copied into the output directory if the external repository they come from matches one of the external repository patterns specified or if they are in the same external repository as this target.<br><br>When copied from an external repository, the file path in the output directory defaults to the file's path within the external repository. The external repository name is _not_ included in that path.<br><br>For example, the following copies <code>@external_repo//path/to:file</code> to <code>path/to/file</code> within the output directory.<br><br><pre><code> copy_to_directory( name = "dir", include_external_repositories = ["external_*"], srcs = ["@external_repo//path/to:file"], ) </code></pre><br><br>Files that come from matching external are subject to subsequent filters and transformations to determine if they are copied and what their path in the output directory will be. The external repository name of the file from an external repository is not included in the output directory path and is considered in subsequent filters and transformations.<br><br>Globs are supported (see rule docstring above). | List of strings | optional | <code>[]</code> | | <a id="copy_to_directory-exclude_srcs_patterns"></a>exclude_srcs_patterns | List of paths (with glob support) to exclude from output directory.<br><br>Files in srcs are not copied to the output directory if their output directory path, after applying `root_paths`, matches one of the patterns specified.<br><br>Forward slashes (`/`) should be used as path separators.<br><br>Files that do not have matching output directory paths are subject to subsequent filters and transformations to determine if they are copied and what their path in the output directory will be.<br><br>Globs are supported (see rule docstring above). | List of strings | optional | `[]` |
| <a id="copy_to_directory-include_srcs_packages"></a>include_srcs_packages | List of Bazel packages (with glob support) to include in output directory.<br><br>Files in srcs are only copied to the output directory if the Bazel package of the file matches one of the patterns specified.<br><br>Forward slashes (<code>/</code>) should be used as path separators. A first character of <code>"."</code> will be replaced by the target's package path.<br><br>Defaults to <code>["**"]</code> which includes sources from all packages.<br><br>Files that have matching Bazel packages are subject to subsequent filters and transformations to determine if they are copied and what their path in the output directory will be.<br><br>Globs are supported (see rule docstring above). | List of strings | optional | <code>["**"]</code> | | <a id="copy_to_directory-hardlink"></a>hardlink | Controls when to use hardlinks to files instead of making copies.<br><br>Creating hardlinks is much faster than making copies of files with the caveat that hardlinks share file permissions with their source.<br><br>Since Bazel removes write permissions on files in the output tree after an action completes, hardlinks to source files are not recommended since write permissions will be inadvertently removed from sources files.<br><br>- `auto`: hardlinks are used for generated files already in the output tree - `off`: all files are copied - `on`: hardlinks are used for all files (not recommended) | String | optional | `"auto"` |
| <a id="copy_to_directory-include_srcs_patterns"></a>include_srcs_patterns | List of paths (with glob support) to include in output directory.<br><br>Files in srcs are only copied to the output directory if their output directory path, after applying <code>root_paths</code>, matches one of the patterns specified.<br><br>Forward slashes (<code>/</code>) should be used as path separators.<br><br>Defaults to <code>["**"]</code> which includes all sources.<br><br>Files that have matching output directory paths are subject to subsequent filters and transformations to determine if they are copied and what their path in the output directory will be.<br><br>Globs are supported (see rule docstring above). | List of strings | optional | <code>["**"]</code> | | <a id="copy_to_directory-include_external_repositories"></a>include_external_repositories | List of external repository names (with glob support) to include in the output directory.<br><br>Files from external repositories are only copied into the output directory if the external repository they come from matches one of the external repository patterns specified or if they are in the same external repository as this target.<br><br>When copied from an external repository, the file path in the output directory defaults to the file's path within the external repository. The external repository name is _not_ included in that path.<br><br>For example, the following copies `@external_repo//path/to:file` to `path/to/file` within the output directory.<br><br><pre><code>copy_to_directory(&#10; name = "dir",&#10; include_external_repositories = ["external_*"],&#10; srcs = ["@external_repo//path/to:file"],&#10;)</code></pre><br><br>Files that come from matching external are subject to subsequent filters and transformations to determine if they are copied and what their path in the output directory will be. The external repository name of the file from an external repository is not included in the output directory path and is considered in subsequent filters and transformations.<br><br>Globs are supported (see rule docstring above). | List of strings | optional | `[]` |
| <a id="copy_to_directory-out"></a>out | Path of the output directory, relative to this package.<br><br>If not set, the name of the target is used. | String | optional | <code>""</code> | | <a id="copy_to_directory-include_srcs_packages"></a>include_srcs_packages | List of Bazel packages (with glob support) to include in output directory.<br><br>Files in srcs are only copied to the output directory if the Bazel package of the file matches one of the patterns specified.<br><br>Forward slashes (`/`) should be used as path separators. A first character of `"."` will be replaced by the target's package path.<br><br>Defaults to `["**"]` which includes sources from all packages.<br><br>Files that have matching Bazel packages are subject to subsequent filters and transformations to determine if they are copied and what their path in the output directory will be.<br><br>Globs are supported (see rule docstring above). | List of strings | optional | `["**"]` |
| <a id="copy_to_directory-replace_prefixes"></a>replace_prefixes | Map of paths prefixes (with glob support) to replace in the output directory path when copying files.<br><br>If the output directory path for a file starts with or fully matches a a key in the dict then the matching portion of the output directory path is replaced with the dict value for that key. The final path segment matched can be a partial match of that segment and only the matching portion will be replaced. If there are multiple keys that match, the longest match wins.<br><br>Forward slashes (<code>/</code>) should be used as path separators.<br><br>Replace prefix transformation are the final step in the list of filters and transformations. The final output path of a file being copied into the output directory is determined at this step.<br><br>Globs are supported (see rule docstring above). | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a> | optional | <code>{}</code> | | <a id="copy_to_directory-include_srcs_patterns"></a>include_srcs_patterns | List of paths (with glob support) to include in output directory.<br><br>Files in srcs are only copied to the output directory if their output directory path, after applying `root_paths`, matches one of the patterns specified.<br><br>Forward slashes (`/`) should be used as path separators.<br><br>Defaults to `["**"]` which includes all sources.<br><br>Files that have matching output directory paths are subject to subsequent filters and transformations to determine if they are copied and what their path in the output directory will be.<br><br>Globs are supported (see rule docstring above). | List of strings | optional | `["**"]` |
| <a id="copy_to_directory-root_paths"></a>root_paths | List of paths (with glob support) that are roots in the output directory.<br><br>If any parent directory of a file being copied matches one of the root paths patterns specified, the output directory path will be the path relative to the root path instead of the path relative to the file's workspace. If there are multiple root paths that match, the longest match wins.<br><br>Matching is done on the parent directory of the output file path so a trailing '**' glob patterm will match only up to the last path segment of the dirname and will not include the basename. Only complete path segments are matched. Partial matches on the last segment of the root path are ignored.<br><br>Forward slashes (<code>/</code>) should be used as path separators.<br><br>A <code>"."</code> value expands to the target's package path (<code>ctx.label.package</code>).<br><br>Defaults to <code>["."]</code> which results in the output directory path of files in the target's package and and sub-packages are relative to the target's package and files outside of that retain their full workspace relative paths.<br><br>Globs are supported (see rule docstring above). | List of strings | optional | <code>["."]</code> | | <a id="copy_to_directory-replace_prefixes"></a>replace_prefixes | Map of paths prefixes (with glob support) to replace in the output directory path when copying files.<br><br>If the output directory path for a file starts with or fully matches a a key in the dict then the matching portion of the output directory path is replaced with the dict value for that key. The final path segment matched can be a partial match of that segment and only the matching portion will be replaced. If there are multiple keys that match, the longest match wins.<br><br>Forward slashes (`/`) should be used as path separators.<br><br>Replace prefix transformation are the final step in the list of filters and transformations. The final output path of a file being copied into the output directory is determined at this step.<br><br>Globs are supported (see rule docstring above). | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a> | optional | `{}` |
| <a id="copy_to_directory-srcs"></a>srcs | Files and/or directories or targets that provide <code>DirectoryPathInfo</code> to copy into the output directory. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | <code>[]</code> | | <a id="copy_to_directory-root_paths"></a>root_paths | List of paths (with glob support) that are roots in the output directory.<br><br>If any parent directory of a file being copied matches one of the root paths patterns specified, the output directory path will be the path relative to the root path instead of the path relative to the file's workspace. If there are multiple root paths that match, the longest match wins.<br><br>Matching is done on the parent directory of the output file path so a trailing '**' glob patterm will match only up to the last path segment of the dirname and will not include the basename. Only complete path segments are matched. Partial matches on the last segment of the root path are ignored.<br><br>Forward slashes (`/`) should be used as path separators.<br><br>A `"."` value expands to the target's package path (`ctx.label.package`).<br><br>Defaults to `["."]` which results in the output directory path of files in the target's package and and sub-packages are relative to the target's package and files outside of that retain their full workspace relative paths.<br><br>Globs are supported (see rule docstring above). | List of strings | optional | `["."]` |
| <a id="copy_to_directory-verbose"></a>verbose | If true, prints out verbose logs to stdout | Boolean | optional | <code>False</code> | | <a id="copy_to_directory-verbose"></a>verbose | If true, prints out verbose logs to stdout | Boolean | optional | `False` |
<a id="copy_to_directory_bin_action"></a> <a id="copy_to_directory_bin_action"></a>
@ -94,18 +91,18 @@ other rule implementations where additional_files can also be passed in.
| <a id="copy_to_directory_bin_action-name"></a>name | Name of target creating this action used for config file generation. | none | | <a id="copy_to_directory_bin_action-name"></a>name | Name of target creating this action used for config file generation. | none |
| <a id="copy_to_directory_bin_action-dst"></a>dst | The directory to copy to. Must be a TreeArtifact. | none | | <a id="copy_to_directory_bin_action-dst"></a>dst | The directory to copy to. Must be a TreeArtifact. | none |
| <a id="copy_to_directory_bin_action-copy_to_directory_bin"></a>copy_to_directory_bin | Copy to directory tool binary. | none | | <a id="copy_to_directory_bin_action-copy_to_directory_bin"></a>copy_to_directory_bin | Copy to directory tool binary. | none |
| <a id="copy_to_directory_bin_action-files"></a>files | List of files to copy into the output directory. | <code>[]</code> | | <a id="copy_to_directory_bin_action-files"></a>files | List of files to copy into the output directory. | `[]` |
| <a id="copy_to_directory_bin_action-targets"></a>targets | List of targets that provide <code>DirectoryPathInfo</code> to copy into the output directory. | <code>[]</code> | | <a id="copy_to_directory_bin_action-targets"></a>targets | List of targets that provide `DirectoryPathInfo` to copy into the output directory. | `[]` |
| <a id="copy_to_directory_bin_action-root_paths"></a>root_paths | List of paths that are roots in the output directory.<br><br>See copy_to_directory rule documentation for more details. | <code>["."]</code> | | <a id="copy_to_directory_bin_action-root_paths"></a>root_paths | List of paths that are roots in the output directory.<br><br>See copy_to_directory rule documentation for more details. | `["."]` |
| <a id="copy_to_directory_bin_action-include_external_repositories"></a>include_external_repositories | List of external repository names to include in the output directory.<br><br>See copy_to_directory rule documentation for more details. | <code>[]</code> | | <a id="copy_to_directory_bin_action-include_external_repositories"></a>include_external_repositories | List of external repository names to include in the output directory.<br><br>See copy_to_directory rule documentation for more details. | `[]` |
| <a id="copy_to_directory_bin_action-include_srcs_packages"></a>include_srcs_packages | List of Bazel packages to include in output directory.<br><br>See copy_to_directory rule documentation for more details. | <code>["**"]</code> | | <a id="copy_to_directory_bin_action-include_srcs_packages"></a>include_srcs_packages | List of Bazel packages to include in output directory.<br><br>See copy_to_directory rule documentation for more details. | `["**"]` |
| <a id="copy_to_directory_bin_action-exclude_srcs_packages"></a>exclude_srcs_packages | List of Bazel packages (with glob support) to exclude from output directory.<br><br>See copy_to_directory rule documentation for more details. | <code>[]</code> | | <a id="copy_to_directory_bin_action-exclude_srcs_packages"></a>exclude_srcs_packages | List of Bazel packages (with glob support) to exclude from output directory.<br><br>See copy_to_directory rule documentation for more details. | `[]` |
| <a id="copy_to_directory_bin_action-include_srcs_patterns"></a>include_srcs_patterns | List of paths (with glob support) to include in output directory.<br><br>See copy_to_directory rule documentation for more details. | <code>["**"]</code> | | <a id="copy_to_directory_bin_action-include_srcs_patterns"></a>include_srcs_patterns | List of paths (with glob support) to include in output directory.<br><br>See copy_to_directory rule documentation for more details. | `["**"]` |
| <a id="copy_to_directory_bin_action-exclude_srcs_patterns"></a>exclude_srcs_patterns | List of paths (with glob support) to exclude from output directory.<br><br>See copy_to_directory rule documentation for more details. | <code>[]</code> | | <a id="copy_to_directory_bin_action-exclude_srcs_patterns"></a>exclude_srcs_patterns | List of paths (with glob support) to exclude from output directory.<br><br>See copy_to_directory rule documentation for more details. | `[]` |
| <a id="copy_to_directory_bin_action-replace_prefixes"></a>replace_prefixes | Map of paths prefixes to replace in the output directory path when copying files.<br><br>See copy_to_directory rule documentation for more details. | <code>{}</code> | | <a id="copy_to_directory_bin_action-replace_prefixes"></a>replace_prefixes | Map of paths prefixes to replace in the output directory path when copying files.<br><br>See copy_to_directory rule documentation for more details. | `{}` |
| <a id="copy_to_directory_bin_action-allow_overwrites"></a>allow_overwrites | If True, allow files to be overwritten if the same output file is copied to twice.<br><br>See copy_to_directory rule documentation for more details. | <code>False</code> | | <a id="copy_to_directory_bin_action-allow_overwrites"></a>allow_overwrites | If True, allow files to be overwritten if the same output file is copied to twice.<br><br>See copy_to_directory rule documentation for more details. | `False` |
| <a id="copy_to_directory_bin_action-hardlink"></a>hardlink | Controls when to use hardlinks to files instead of making copies.<br><br>See copy_to_directory rule documentation for more details. | <code>"auto"</code> | | <a id="copy_to_directory_bin_action-hardlink"></a>hardlink | Controls when to use hardlinks to files instead of making copies.<br><br>See copy_to_directory rule documentation for more details. | `"auto"` |
| <a id="copy_to_directory_bin_action-verbose"></a>verbose | If true, prints out verbose logs to stdout | <code>False</code> | | <a id="copy_to_directory_bin_action-verbose"></a>verbose | If true, prints out verbose logs to stdout | `False` |
<a id="copy_to_directory_lib.impl"></a> <a id="copy_to_directory_lib.impl"></a>

9
docs/diff_test.md generated
View File

@ -8,6 +8,7 @@ but also supports comparing directories.
The rule uses a Bash command (diff) on Linux/macOS/non-Windows, and a cmd.exe The rule uses a Bash command (diff) on Linux/macOS/non-Windows, and a cmd.exe
command (fc.exe) on Windows (no Bash is required). command (fc.exe) on Windows (no Bash is required).
See also: [rules_diff](https://gitlab.arm.com/bazel/rules_diff)
<a id="diff_test"></a> <a id="diff_test"></a>
@ -28,9 +29,9 @@ The test succeeds if the files' contents match.
| Name | Description | Default Value | | Name | Description | Default Value |
| :------------- | :------------- | :------------- | | :------------- | :------------- | :------------- |
| <a id="diff_test-name"></a>name | The name of the test rule. | none | | <a id="diff_test-name"></a>name | The name of the test rule. | none |
| <a id="diff_test-file1"></a>file1 | Label of the file to compare to &lt;code&gt;file2&lt;/code&gt;. | none | | <a id="diff_test-file1"></a>file1 | Label of the file to compare to <code>file2</code>. | none |
| <a id="diff_test-file2"></a>file2 | Label of the file to compare to &lt;code&gt;file1&lt;/code&gt;. | none | | <a id="diff_test-file2"></a>file2 | Label of the file to compare to <code>file1</code>. | none |
| <a id="diff_test-size"></a>size | standard attribute for tests | <code>"small"</code> | | <a id="diff_test-size"></a>size | standard attribute for tests | `"small"` |
| <a id="diff_test-kwargs"></a>kwargs | The &lt;a href="https://docs.bazel.build/versions/main/be/common-definitions.html#common-attributes-tests"&gt;common attributes for tests&lt;/a&gt;. | none | | <a id="diff_test-kwargs"></a>kwargs | The <a href="https://docs.bazel.build/versions/main/be/common-definitions.html#common-attributes-tests">common attributes for tests</a>. | none |

11
docs/directory_path.md generated
View File

@ -3,7 +3,6 @@
Rule and corresponding provider that joins a label pointing to a TreeArtifact Rule and corresponding provider that joins a label pointing to a TreeArtifact
with a path nested within that directory with a path nested within that directory
<a id="directory_path"></a> <a id="directory_path"></a>
## directory_path ## directory_path
@ -60,10 +59,10 @@ Helper function to generate a directory_path target and return its label.
| Name | Description | Default Value | | Name | Description | Default Value |
| :------------- | :------------- | :------------- | | :------------- | :------------- | :------------- |
| <a id="make_directory_path-name"></a>name | unique name for the generated <code>directory_path</code> target | none | | <a id="make_directory_path-name"></a>name | unique name for the generated `directory_path` target | none |
| <a id="make_directory_path-directory"></a>directory | <code>directory</code> attribute passed to generated <code>directory_path</code> target | none | | <a id="make_directory_path-directory"></a>directory | `directory` attribute passed to generated `directory_path` target | none |
| <a id="make_directory_path-path"></a>path | <code>path</code> attribute passed to generated <code>directory_path</code> target | none | | <a id="make_directory_path-path"></a>path | `path` attribute passed to generated `directory_path` target | none |
| <a id="make_directory_path-kwargs"></a>kwargs | parameters to pass to generated <code>output_files</code> target | none | | <a id="make_directory_path-kwargs"></a>kwargs | parameters to pass to generated `output_files` target | none |
**RETURNS** **RETURNS**
@ -127,7 +126,7 @@ and the list of targets is returned,
| Name | Description | Default Value | | Name | Description | Default Value |
| :------------- | :------------- | :------------- | | :------------- | :------------- | :------------- |
| <a id="make_directory_paths-name"></a>name | The target name to use for the generated targets & labels.<br><br>The names are generated as zero-indexed <code>name + "_" + i</code> | none | | <a id="make_directory_paths-name"></a>name | The target name to use for the generated targets & labels.<br><br>The names are generated as zero-indexed `name + "_" + i` | none |
| <a id="make_directory_paths-dict"></a>dict | The dictionary of directory keys to path or path list values. | none | | <a id="make_directory_paths-dict"></a>dict | The dictionary of directory keys to path or path list values. | none |
| <a id="make_directory_paths-kwargs"></a>kwargs | additional parameters to pass to each generated target | none | | <a id="make_directory_paths-kwargs"></a>kwargs | additional parameters to pass to each generated target | none |

6
docs/docs.md generated
View File

@ -21,7 +21,7 @@ This is helpful for minimizing boilerplate in repos with lots of stardoc targets
| Name | Description | Default Value | | Name | Description | Default Value |
| :------------- | :------------- | :------------- | | :------------- | :------------- | :------------- |
| <a id="stardoc_with_diff_test-name"></a>name | the name of the stardoc file to be written to the current source directory (.md will be appended to the name). Call bazel run on this target to update the file. | none | | <a id="stardoc_with_diff_test-name"></a>name | the name of the stardoc file to be written to the current source directory (.md will be appended to the name). Call bazel run on this target to update the file. | none |
| <a id="stardoc_with_diff_test-bzl_library_target"></a>bzl_library_target | the label of the <code>bzl_library</code> target to generate documentation for | none | | <a id="stardoc_with_diff_test-bzl_library_target"></a>bzl_library_target | the label of the `bzl_library` target to generate documentation for | none |
| <a id="stardoc_with_diff_test-kwargs"></a>kwargs | additional attributes passed to the stardoc() rule, such as for overriding the templates | none | | <a id="stardoc_with_diff_test-kwargs"></a>kwargs | additional attributes passed to the stardoc() rule, such as for overriding the templates | none |
@ -54,7 +54,7 @@ bazel build //docs/... && bazel test //docs/... && bazel run //docs:update
| Name | Description | Default Value | | Name | Description | Default Value |
| :------------- | :------------- | :------------- | | :------------- | :------------- | :------------- |
| <a id="update_docs-name"></a>name | the name of executable target | <code>"update"</code> | | <a id="update_docs-name"></a>name | the name of executable target | `"update"` |
| <a id="update_docs-kwargs"></a>kwargs | Other common named parameters such as <code>tags</code> or <code>visibility</code> | none | | <a id="update_docs-kwargs"></a>kwargs | Other common named parameters such as `tags` or `visibility` | none |

10
docs/expand_make_vars.md generated
View File

@ -29,8 +29,8 @@ This is of the format:
- `./file` - `./file`
- `path/to/file` - `path/to/file`
- `external/external_repo/path/to/file` - `external/external_repo/path/to/file`
- `&lt;bin_dir&gt;/path/to/file` - `<bin_dir>/path/to/file`
- `&lt;bin_dir&gt;/external/external_repo/path/to/file` - `<bin_dir>/external/external_repo/path/to/file`
The deprecated `$(location)` and `$(locations)` expansions returns either the execpath or rootpath depending on the context. The deprecated `$(location)` and `$(locations)` expansions returns either the execpath or rootpath depending on the context.
@ -42,7 +42,7 @@ The deprecated `$(location)` and `$(locations)` expansions returns either the ex
| :------------- | :------------- | :------------- | | :------------- | :------------- | :------------- |
| <a id="expand_locations-ctx"></a>ctx | context | none | | <a id="expand_locations-ctx"></a>ctx | context | none |
| <a id="expand_locations-input"></a>input | String to be expanded | none | | <a id="expand_locations-input"></a>input | String to be expanded | none |
| <a id="expand_locations-targets"></a>targets | List of targets for additional lookup information. | <code>[]</code> | | <a id="expand_locations-targets"></a>targets | List of targets for additional lookup information. | `[]` |
**RETURNS** **RETURNS**
@ -103,8 +103,8 @@ for more information of how these special variables are expanded.
| :------------- | :------------- | :------------- | | :------------- | :------------- | :------------- |
| <a id="expand_variables-ctx"></a>ctx | starlark rule context | none | | <a id="expand_variables-ctx"></a>ctx | starlark rule context | none |
| <a id="expand_variables-s"></a>s | expression to expand | none | | <a id="expand_variables-s"></a>s | expression to expand | none |
| <a id="expand_variables-outs"></a>outs | declared outputs of the rule, for expanding references to outputs | <code>[]</code> | | <a id="expand_variables-outs"></a>outs | declared outputs of the rule, for expanding references to outputs | `[]` |
| <a id="expand_variables-attribute_name"></a>attribute_name | name of the attribute containing the expression. Used for error reporting. | <code>"args"</code> | | <a id="expand_variables-attribute_name"></a>attribute_name | name of the attribute containing the expression. Used for error reporting. | `"args"` |
**RETURNS** **RETURNS**

17
docs/expand_template.md generated
View File

@ -7,7 +7,7 @@ Public API for expand template
## expand_template_rule ## expand_template_rule
<pre> <pre>
expand_template_rule(<a href="#expand_template_rule-name">name</a>, <a href="#expand_template_rule-data">data</a>, <a href="#expand_template_rule-is_executable">is_executable</a>, <a href="#expand_template_rule-out">out</a>, <a href="#expand_template_rule-stamp">stamp</a>, <a href="#expand_template_rule-stamp_substitutions">stamp_substitutions</a>, <a href="#expand_template_rule-substitutions">substitutions</a>, expand_template_rule(<a href="#expand_template_rule-name">name</a>, <a href="#expand_template_rule-data">data</a>, <a href="#expand_template_rule-out">out</a>, <a href="#expand_template_rule-is_executable">is_executable</a>, <a href="#expand_template_rule-stamp">stamp</a>, <a href="#expand_template_rule-stamp_substitutions">stamp_substitutions</a>, <a href="#expand_template_rule-substitutions">substitutions</a>,
<a href="#expand_template_rule-template">template</a>) <a href="#expand_template_rule-template">template</a>)
</pre> </pre>
@ -22,19 +22,18 @@ as well as [configuration variables](https://docs.bazel.build/versions/main/skyl
such as `$(BINDIR)`, `$(TARGET_CPU)`, and `$(COMPILATION_MODE)` as documented in such as `$(BINDIR)`, `$(TARGET_CPU)`, and `$(COMPILATION_MODE)` as documented in
[expand_variables](https://github.com/aspect-build/bazel-lib/blob/main/docs/expand_make_vars.md#expand_variables). [expand_variables](https://github.com/aspect-build/bazel-lib/blob/main/docs/expand_make_vars.md#expand_variables).
**ATTRIBUTES** **ATTRIBUTES**
| Name | Description | Type | Mandatory | Default | | Name | Description | Type | Mandatory | Default |
| :------------- | :------------- | :------------- | :------------- | :------------- | | :------------- | :------------- | :------------- | :------------- | :------------- |
| <a id="expand_template_rule-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | | | <a id="expand_template_rule-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | |
| <a id="expand_template_rule-data"></a>data | List of targets for additional lookup information. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | <code>[]</code> | | <a id="expand_template_rule-data"></a>data | List of targets for additional lookup information. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | `[]` |
| <a id="expand_template_rule-is_executable"></a>is_executable | Whether to mark the output file as executable. | Boolean | optional | <code>False</code> | | <a id="expand_template_rule-out"></a>out | Where to write the expanded file.<br><br>If the `template` is a source file, then `out` defaults to be named the same as the template file and outputted to the same workspace-relative path. In this case there will be no pre-declared label for the output file. It can be referenced by the target label instead. This pattern is similar to `copy_to_bin` but with substitutions on the copy.<br><br>Otherwise, `out` defaults to `[name].txt`. | <a href="https://bazel.build/concepts/labels">Label</a> | optional | `None` |
| <a id="expand_template_rule-out"></a>out | Where to write the expanded file.<br><br> If the <code>template</code> is a source file, then <code>out</code> defaults to be named the same as the template file and outputted to the same workspace-relative path. In this case there will be no pre-declared label for the output file. It can be referenced by the target label instead. This pattern is similar to <code>copy_to_bin</code> but with substitutions on the copy.<br><br> Otherwise, <code>out</code> defaults to <code>[name].txt</code>. | <a href="https://bazel.build/concepts/labels">Label</a> | optional | | | <a id="expand_template_rule-is_executable"></a>is_executable | Whether to mark the output file as executable. | Boolean | optional | `False` |
| <a id="expand_template_rule-stamp"></a>stamp | Whether to encode build information into the output. Possible values:<br><br> - <code>stamp = 1</code>: Always stamp the build information into the output, even in [--nostamp](https://docs.bazel.build/versions/main/user-manual.html#flag--stamp) builds. This setting should be avoided, since it is non-deterministic. It potentially causes remote cache misses for the target and any downstream actions that depend on the result. - <code>stamp = 0</code>: Never stamp, instead replace build information by constant values. This gives good build result caching. - <code>stamp = -1</code>: Embedding of build information is controlled by the [--[no]stamp](https://docs.bazel.build/versions/main/user-manual.html#flag--stamp) flag. Stamped targets are not rebuilt unless their dependencies change. | Integer | optional | <code>-1</code> | | <a id="expand_template_rule-stamp"></a>stamp | Whether to encode build information into the output. Possible values:<br><br>- `stamp = 1`: Always stamp the build information into the output, even in [--nostamp](https://docs.bazel.build/versions/main/user-manual.html#flag--stamp) builds. This setting should be avoided, since it is non-deterministic. It potentially causes remote cache misses for the target and any downstream actions that depend on the result. - `stamp = 0`: Never stamp, instead replace build information by constant values. This gives good build result caching. - `stamp = -1`: Embedding of build information is controlled by the [--[no]stamp](https://docs.bazel.build/versions/main/user-manual.html#flag--stamp) flag. Stamped targets are not rebuilt unless their dependencies change. | Integer | optional | `-1` |
| <a id="expand_template_rule-stamp_substitutions"></a>stamp_substitutions | Mapping of strings to substitutions.<br><br> There are overlaid on top of substitutions when stamping is enabled for the target.<br><br> Substitutions can contain $(execpath :target) and $(rootpath :target) expansions, $(MAKEVAR) expansions and {{STAMP_VAR}} expansions when stamping is enabled for the target. | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a> | optional | <code>{}</code> | | <a id="expand_template_rule-stamp_substitutions"></a>stamp_substitutions | Mapping of strings to substitutions.<br><br>There are overlaid on top of substitutions when stamping is enabled for the target.<br><br>Substitutions can contain $(execpath :target) and $(rootpath :target) expansions, $(MAKEVAR) expansions and {{STAMP_VAR}} expansions when stamping is enabled for the target. | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a> | optional | `{}` |
| <a id="expand_template_rule-substitutions"></a>substitutions | Mapping of strings to substitutions.<br><br> Substitutions can contain $(execpath :target) and $(rootpath :target) expansions, $(MAKEVAR) expansions and {{STAMP_VAR}} expansions when stamping is enabled for the target. | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a> | optional | <code>{}</code> | | <a id="expand_template_rule-substitutions"></a>substitutions | Mapping of strings to substitutions.<br><br>Substitutions can contain $(execpath :target) and $(rootpath :target) expansions, $(MAKEVAR) expansions and {{STAMP_VAR}} expansions when stamping is enabled for the target. | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a> | optional | `{}` |
| <a id="expand_template_rule-template"></a>template | The template file to expand. | <a href="https://bazel.build/concepts/labels">Label</a> | required | | | <a id="expand_template_rule-template"></a>template | The template file to expand. | <a href="https://bazel.build/concepts/labels">Label</a> | required | |
@ -55,6 +54,6 @@ Wrapper macro for `expand_template_rule`.
| :------------- | :------------- | :------------- | | :------------- | :------------- | :------------- |
| <a id="expand_template-name"></a>name | name of resulting rule | none | | <a id="expand_template-name"></a>name | name of resulting rule | none |
| <a id="expand_template-template"></a>template | the label of a template file, or a list of strings which are lines representing the content of the template. | none | | <a id="expand_template-template"></a>template | the label of a template file, or a list of strings which are lines representing the content of the template. | none |
| <a id="expand_template-kwargs"></a>kwargs | other named parameters to <code>expand_template_rule</code>. | none | | <a id="expand_template-kwargs"></a>kwargs | other named parameters to `expand_template_rule`. | none |

2
docs/glob_match.md generated
View File

@ -26,7 +26,7 @@ Test if the passed path matches the glob expression.
| :------------- | :------------- | :------------- | | :------------- | :------------- | :------------- |
| <a id="glob_match-expr"></a>expr | the glob expression | none | | <a id="glob_match-expr"></a>expr | the glob expression | none |
| <a id="glob_match-path"></a>path | the path against which to match the glob expression | none | | <a id="glob_match-path"></a>path | the path against which to match the glob expression | none |
| <a id="glob_match-match_path_separator"></a>match_path_separator | whether or not to match the path separator '/' when matching <code>*</code> and <code>?</code> expressions | <code>False</code> | | <a id="glob_match-match_path_separator"></a>match_path_separator | whether or not to match the path separator '/' when matching `*` and `?` expressions | `False` |
**RETURNS** **RETURNS**

2
docs/host_repo.md generated
View File

@ -18,6 +18,6 @@ Exposes information about the host platform
| Name | Description | Type | Mandatory | Default | | Name | Description | Type | Mandatory | Default |
| :------------- | :------------- | :------------- | :------------- | :------------- | | :------------- | :------------- | :------------- | :------------- | :------------- |
| <a id="host_repo-name"></a>name | A unique name for this repository. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | | | <a id="host_repo-name"></a>name | A unique name for this repository. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | |
| <a id="host_repo-repo_mapping"></a>repo_mapping | A dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository.&lt;p&gt;For example, an entry <code>"@foo": "@bar"</code> declares that, for any time this repository depends on <code>@foo</code> (such as a dependency on <code>@foo//some:target</code>, it should actually resolve that dependency within globally-declared <code>@bar</code> (<code>@bar//some:target</code>). | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a> | required | | | <a id="host_repo-repo_mapping"></a>repo_mapping | In `WORKSPACE` context only: a dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository.<br><br>For example, an entry `"@foo": "@bar"` declares that, for any time this repository depends on `@foo` (such as a dependency on `@foo//some:target`, it should actually resolve that dependency within globally-declared `@bar` (`@bar//some:target`).<br><br>This attribute is _not_ supported in `MODULE.bazel` context (when invoking a repository rule inside a module extension's implementation function). | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a> | optional | |

85
docs/jq.md generated
View File

@ -1,41 +1,40 @@
<!-- Generated with Stardoc: http://skydoc.bazel.build --> <!-- Generated with Stardoc: http://skydoc.bazel.build -->
Public API for jq Wrapper rule around the popular `jq` utility.
<a id="jq"></a>
## jq
<pre>
jq(<a href="#jq-name">name</a>, <a href="#jq-srcs">srcs</a>, <a href="#jq-filter">filter</a>, <a href="#jq-filter_file">filter_file</a>, <a href="#jq-args">args</a>, <a href="#jq-out">out</a>, <a href="#jq-data">data</a>, <a href="#jq-expand_args">expand_args</a>, <a href="#jq-kwargs">kwargs</a>)
</pre>
Invoke jq with a filter on a set of json input files.
For jq documentation, see https://stedolan.github.io/jq/. For jq documentation, see https://stedolan.github.io/jq/.
Usage examples: ## Usage examples
```starlark ```starlark
load("@aspect_bazel_lib//lib:jq.bzl", "jq") load("@aspect_bazel_lib//lib:jq.bzl", "jq")
```
# Create a new file bazel-out/.../no_srcs.json Create a new file `bazel-out/.../no_srcs.json` containing some JSON data:
```starlark
jq( jq(
name = "no_srcs", name = "no_srcs",
srcs = [], srcs = [],
filter = ".name = "Alice"", filter = ".name = "Alice"",
) )
```
# Remove fields from package.json. Remove a field from `package.json`:
# Writes to bazel-out/.../package.json which means you must refer to this as ":no_dev_deps"
# since Bazel doesn't allow a label for the output file that collides with the input file. > The output path `bazel-out/.../package.json` matches the path of the source file,
> which means you must refer to the label `:no_dev_deps` to reference the output,
> since Bazel doesn't provide a label for an output file that collides with an input file.
```starlark
jq( jq(
name = "no_dev_deps", name = "no_dev_deps",
srcs = ["package.json"], srcs = ["package.json"],
filter = "del(.devDependencies)", filter = "del(.devDependencies)",
) )
```
# Merge bar.json on top of foo.json, producing foobar.json Merge data from `bar.json` on top of `foo.json`, producing `foobar.json`:
```starlark
jq( jq(
name = "merged", name = "merged",
srcs = ["foo.json", "bar.json"], srcs = ["foo.json", "bar.json"],
@ -43,8 +42,10 @@ jq(
args = ["--slurp"], args = ["--slurp"],
out = "foobar.json", out = "foobar.json",
) )
```
# Long filters can be split over several lines with comments Long filters can be split over several lines with comments:
```starlark
jq( jq(
name = "complex", name = "complex",
srcs = ["a.json", "b.json"], srcs = ["a.json", "b.json"],
@ -61,17 +62,21 @@ jq(
""", """,
args = ["--slurp"], args = ["--slurp"],
) )
```
# Load filter from a file Load filter from a file `filter.jq`, making it easier to edit complex filters:
```starlark
jq( jq(
name = "merged", name = "merged",
srcs = ["foo.json", "bar.json"], srcs = ["foo.json", "bar.json"],
filter_file = "filter.txt", filter_file = "filter.jq",
args = ["--slurp"], args = ["--slurp"],
out = "foobar.json", out = "foobar.json",
) )
```
# Convert genquery output to json Convert [genquery](https://bazel.build/reference/be/general#genquery) output to JSON.
```starlark
genquery( genquery(
name = "deps", name = "deps",
expression = "deps(//some:target)", expression = "deps(//some:target)",
@ -85,10 +90,12 @@ jq(
"--raw-input", "--raw-input",
"--slurp", "--slurp",
], ],
filter = "{ deps: split("\n") | map(select(. | length &gt; 0)) }", filter = "{ deps: split("\n") | map(select(. | length > 0)) }",
) )
```
# With --stamp, causes properties to be replaced by version control info. When Bazel is run with `--stamp`, replace some properties with version control info:
```starlark
jq( jq(
name = "stamped", name = "stamped",
srcs = ["package.json"], srcs = ["package.json"],
@ -97,24 +104,32 @@ jq(
# This 'as' syntax results in $stamp being null in unstamped builds. # This 'as' syntax results in $stamp being null in unstamped builds.
"$ARGS.named.STAMP as $stamp", "$ARGS.named.STAMP as $stamp",
# Provide a default using the "alternative operator" in case $stamp is null. # Provide a default using the "alternative operator" in case $stamp is null.
".version = ($stamp[0].BUILD_EMBED_LABEL // "&lt;unstamped&gt;")", ".version = ($stamp[0].BUILD_EMBED_LABEL // "<unstamped>")",
]), ]),
) )
``` ```
You could also use it directly from a `genrule` by referencing the toolchain, and the `JQ_BIN` jq is exposed as a "Make variable", so you could use it directly from a `genrule` by referencing the toolchain.
"Make variable" it exposes:
``` ```starlark
genrule( genrule(
name = "case_genrule", name = "case_genrule",
srcs = ["a.json"], srcs = ["a.json"],
outs = ["genrule_output.json"], outs = ["genrule_output.json"],
cmd = "$(JQ_BIN) '.' $(location a.json) &gt; $@", cmd = "$(JQ_BIN) '.' $(location a.json) > $@",
toolchains = ["@jq_toolchains//:resolved_toolchain"], toolchains = ["@jq_toolchains//:resolved_toolchain"],
) )
``` ```
<a id="jq"></a>
## jq
<pre>
jq(<a href="#jq-name">name</a>, <a href="#jq-srcs">srcs</a>, <a href="#jq-filter">filter</a>, <a href="#jq-filter_file">filter_file</a>, <a href="#jq-args">args</a>, <a href="#jq-out">out</a>, <a href="#jq-data">data</a>, <a href="#jq-expand_args">expand_args</a>, <a href="#jq-kwargs">kwargs</a>)
</pre>
Invoke jq with a filter on a set of json input files.
**PARAMETERS** **PARAMETERS**
@ -123,12 +138,12 @@ genrule(
| :------------- | :------------- | :------------- | | :------------- | :------------- | :------------- |
| <a id="jq-name"></a>name | Name of the rule | none | | <a id="jq-name"></a>name | Name of the rule | none |
| <a id="jq-srcs"></a>srcs | List of input files. May be empty. | none | | <a id="jq-srcs"></a>srcs | List of input files. May be empty. | none |
| <a id="jq-filter"></a>filter | Filter expression (https://stedolan.github.io/jq/manual/#Basicfilters). Subject to stamp variable replacements, see [Stamping](./stamping.md). When stamping is enabled, a variable named "STAMP" will be available in the filter.<br><br>Be careful to write the filter so that it handles unstamped builds, as in the example above. | <code>None</code> | | <a id="jq-filter"></a>filter | Filter expression (https://stedolan.github.io/jq/manual/#Basicfilters). Subject to stamp variable replacements, see [Stamping](./stamping.md). When stamping is enabled, a variable named "STAMP" will be available in the filter.<br><br>Be careful to write the filter so that it handles unstamped builds, as in the example above. | `None` |
| <a id="jq-filter_file"></a>filter_file | File containing filter expression (alternative to <code>filter</code>) | <code>None</code> | | <a id="jq-filter_file"></a>filter_file | File containing filter expression (alternative to `filter`) | `None` |
| <a id="jq-args"></a>args | Additional args to pass to jq | <code>[]</code> | | <a id="jq-args"></a>args | Additional args to pass to jq | `[]` |
| <a id="jq-out"></a>out | Name of the output json file; defaults to the rule name plus ".json" | <code>None</code> | | <a id="jq-out"></a>out | Name of the output json file; defaults to the rule name plus ".json" | `None` |
| <a id="jq-data"></a>data | List of additional files. May be empty. | <code>[]</code> | | <a id="jq-data"></a>data | List of additional files. May be empty. | `[]` |
| <a id="jq-expand_args"></a>expand_args | Run bazel's location-expansion on the args. | <code>False</code> | | <a id="jq-expand_args"></a>expand_args | Run bazel's location-expansion on the args. | `False` |
| <a id="jq-kwargs"></a>kwargs | Other common named parameters such as <code>tags</code> or <code>visibility</code> | none | | <a id="jq-kwargs"></a>kwargs | Other common named parameters such as `tags` or `visibility` | none |

13
docs/output_files.md generated
View File

@ -1,7 +1,8 @@
<!-- Generated with Stardoc: http://skydoc.bazel.build --> <!-- Generated with Stardoc: http://skydoc.bazel.build -->
A rule that provides file(s) specific via DefaultInfo from a given target's DefaultInfo or OutputGroupInfo A rule that provides file(s) specific via DefaultInfo from a given target's DefaultInfo or OutputGroupInfo.
See also [select_file](https://github.com/bazelbuild/bazel-skylib/blob/main/docs/select_file_doc.md) from bazel-skylib.
<a id="output_files"></a> <a id="output_files"></a>
@ -19,7 +20,7 @@ A rule that provides file(s) specific via DefaultInfo from a given target's Defa
| Name | Description | Type | Mandatory | Default | | Name | Description | Type | Mandatory | Default |
| :------------- | :------------- | :------------- | :------------- | :------------- | | :------------- | :------------- | :------------- | :------------- | :------------- |
| <a id="output_files-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | | | <a id="output_files-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | |
| <a id="output_files-output_group"></a>output_group | if set, we look in the specified output group for paths instead of DefaultInfo | String | optional | <code>""</code> | | <a id="output_files-output_group"></a>output_group | if set, we look in the specified output group for paths instead of DefaultInfo | String | optional | `""` |
| <a id="output_files-paths"></a>paths | the paths of the file(s), relative to their roots, to provide via DefaultInfo from the given target's DefaultInfo or OutputGroupInfo | List of strings | required | | | <a id="output_files-paths"></a>paths | the paths of the file(s), relative to their roots, to provide via DefaultInfo from the given target's DefaultInfo or OutputGroupInfo | List of strings | required | |
| <a id="output_files-target"></a>target | the target to look in for requested paths in its' DefaultInfo or OutputGroupInfo | <a href="https://bazel.build/concepts/labels">Label</a> | required | | | <a id="output_files-target"></a>target | the target to look in for requested paths in its' DefaultInfo or OutputGroupInfo | <a href="https://bazel.build/concepts/labels">Label</a> | required | |
@ -39,10 +40,10 @@ Helper function to generate a output_files target and return its label.
| Name | Description | Default Value | | Name | Description | Default Value |
| :------------- | :------------- | :------------- | | :------------- | :------------- | :------------- |
| <a id="make_output_files-name"></a>name | unique name for the generated <code>output_files</code> target | none | | <a id="make_output_files-name"></a>name | unique name for the generated `output_files` target | none |
| <a id="make_output_files-target"></a>target | <code>target</code> attribute passed to generated <code>output_files</code> target | none | | <a id="make_output_files-target"></a>target | `target` attribute passed to generated `output_files` target | none |
| <a id="make_output_files-paths"></a>paths | <code>paths</code> attribute passed to generated <code>output_files</code> target | none | | <a id="make_output_files-paths"></a>paths | `paths` attribute passed to generated `output_files` target | none |
| <a id="make_output_files-kwargs"></a>kwargs | parameters to pass to generated <code>output_files</code> target | none | | <a id="make_output_files-kwargs"></a>kwargs | parameters to pass to generated `output_files` target | none |
**RETURNS** **RETURNS**

13
docs/params_file.md generated
View File

@ -2,10 +2,7 @@
params_file public API params_file public API
<a id="params_file"></a>
<a id="#params_file"></a>
## params_file ## params_file
@ -18,16 +15,16 @@ Generates a UTF-8 encoded params file from a list of arguments.
Handles variable substitutions for args. Handles variable substitutions for args.
### **Parameters** **PARAMETERS**
| Name | Description | Default Value | | Name | Description | Default Value |
| :------------- | :------------- | :------------- | | :------------- | :------------- | :------------- |
| <a id="params_file-name"></a>name | Name of the rule. | none | | <a id="params_file-name"></a>name | Name of the rule. | none |
| <a id="params_file-out"></a>out | Path of the output file, relative to this package. | none | | <a id="params_file-out"></a>out | Path of the output file, relative to this package. | none |
| <a id="params_file-args"></a>args | Arguments to concatenate into a params file.<br><br>- Subject to 'Make variable' substitution. See https://docs.bazel.build/versions/main/be/make-variables.html.<br><br>- Subject to predefined source/output path variables substitutions.<br><br> The predefined variables <code>execpath</code>, <code>execpaths</code>, <code>rootpath</code>, <code>rootpaths</code>, <code>location</code>, and <code>locations</code> take label parameters (e.g. <code>$(execpath //foo:bar)</code>) and substitute the file paths denoted by that label.<br><br> See https://docs.bazel.build/versions/main/be/make-variables.html#predefined_label_variables for more info.<br><br> NB: This $(location) substitution returns the manifest file path which differs from the <code>*_binary</code> & <code>*_test</code> args and genrule bazel substitutions. This will be fixed in a future major release. See docs string of <code>expand_location_into_runfiles</code> macro in <code>internal/common/expand_into_runfiles.bzl</code> for more info.<br><br>- Subject to predefined variables & custom variable substitutions.<br><br> Predefined "Make" variables such as <code>$(COMPILATION_MODE)</code> and <code>$(TARGET_CPU)</code> are expanded. See https://docs.bazel.build/versions/main/be/make-variables.html#predefined_variables.<br><br> Custom variables are also expanded including variables set through the Bazel CLI with <code>--define=SOME_VAR=SOME_VALUE</code>. See https://docs.bazel.build/versions/main/be/make-variables.html#custom_variables.<br><br> Predefined genrule variables are not supported in this context. | <code>[]</code> | | <a id="params_file-args"></a>args | Arguments to concatenate into a params file.<br><br>- Subject to 'Make variable' substitution. See https://docs.bazel.build/versions/main/be/make-variables.html.<br><br>- Subject to predefined source/output path variables substitutions.<br><br> The predefined variables `execpath`, `execpaths`, `rootpath`, `rootpaths`, `location`, and `locations` take label parameters (e.g. `$(execpath //foo:bar)`) and substitute the file paths denoted by that label.<br><br> See https://docs.bazel.build/versions/main/be/make-variables.html#predefined_label_variables for more info.<br><br> NB: This $(location) substitution returns the manifest file path which differs from the `*_binary` & `*_test` args and genrule bazel substitutions. This will be fixed in a future major release. See docs string of `expand_location_into_runfiles` macro in `internal/common/expand_into_runfiles.bzl` for more info.<br><br>- Subject to predefined variables & custom variable substitutions.<br><br> Predefined "Make" variables such as `$(COMPILATION_MODE)` and `$(TARGET_CPU)` are expanded. See https://docs.bazel.build/versions/main/be/make-variables.html#predefined_variables.<br><br> Custom variables are also expanded including variables set through the Bazel CLI with `--define=SOME_VAR=SOME_VALUE`. See https://docs.bazel.build/versions/main/be/make-variables.html#custom_variables.<br><br> Predefined genrule variables are not supported in this context. | `[]` |
| <a id="params_file-data"></a>data | Data for <code>$(location)</code> expansions in args. | <code>[]</code> | | <a id="params_file-data"></a>data | Data for `$(location)` expansions in args. | `[]` |
| <a id="params_file-newline"></a>newline | Line endings to use. One of [<code>"auto"</code>, <code>"unix"</code>, <code>"windows"</code>].<br><br>- <code>"auto"</code> for platform-determined - <code>"unix"</code> for LF - <code>"windows"</code> for CRLF | <code>"auto"</code> | | <a id="params_file-newline"></a>newline | Line endings to use. One of [`"auto"`, `"unix"`, `"windows"`].<br><br>- `"auto"` for platform-determined - `"unix"` for LF - `"windows"` for CRLF | `"auto"` |
| <a id="params_file-kwargs"></a>kwargs | undocumented named arguments | none | | <a id="params_file-kwargs"></a>kwargs | undocumented named arguments | none |

32
docs/paths.md generated
View File

@ -1,6 +1,6 @@
<!-- Generated with Stardoc: http://skydoc.bazel.build --> <!-- Generated with Stardoc: http://skydoc.bazel.build -->
Public API Utilities for working with file paths.
<a id="relative_file"></a> <a id="relative_file"></a>
@ -40,14 +40,14 @@ The relative path from frm_file to to_file, including the file name
to_output_relative_path(<a href="#to_output_relative_path-file">file</a>) to_output_relative_path(<a href="#to_output_relative_path-file">file</a>)
</pre> </pre>
The relative path from bazel-out/[arch]/bin to the given File object The relative path from bazel-out/[arch]/bin to the given File object
**PARAMETERS** **PARAMETERS**
| Name | Description | Default Value | | Name | Description | Default Value |
| :------------- | :------------- | :------------- | | :------------- | :------------- | :------------- |
| <a id="to_output_relative_path-file"></a>file | a <code>File</code> object | none | | <a id="to_output_relative_path-file"></a>file | a `File` object | none |
**RETURNS** **RETURNS**
@ -75,7 +75,7 @@ rlocation path as it does not include the repository name if the `File` is from
| Name | Description | Default Value | | Name | Description | Default Value |
| :------------- | :------------- | :------------- | | :------------- | :------------- | :------------- |
| <a id="to_repository_relative_path-file"></a>file | a <code>File</code> object | none | | <a id="to_repository_relative_path-file"></a>file | a `File` object | none |
**RETURNS** **RETURNS**
@ -96,20 +96,20 @@ This produces the same value as the `rlocationpath` predefined source/output pat
From https://bazel.build/reference/be/make-variables#predefined_genrule_variables: From https://bazel.build/reference/be/make-variables#predefined_genrule_variables:
&gt; `rlocationpath`: The path a built binary can pass to the `Rlocation` function of a runfiles > `rlocationpath`: The path a built binary can pass to the `Rlocation` function of a runfiles
&gt; library to find a dependency at runtime, either in the runfiles directory (if available) > library to find a dependency at runtime, either in the runfiles directory (if available)
&gt; or using the runfiles manifest. > or using the runfiles manifest.
&gt; This is similar to root path (a.k.a. [short_path](https://bazel.build/rules/lib/File#short_path)) > This is similar to root path (a.k.a. [short_path](https://bazel.build/rules/lib/File#short_path))
&gt; in that it does not contain configuration prefixes, but differs in that it always starts with the > in that it does not contain configuration prefixes, but differs in that it always starts with the
&gt; name of the repository. > name of the repository.
&gt; The rlocation path of a `File` in an external repository repo will start with `repo/`, followed by the > The rlocation path of a `File` in an external repository repo will start with `repo/`, followed by the
&gt; repository-relative path. > repository-relative path.
&gt; Passing this path to a binary and resolving it to a file system path using the runfiles libraries > Passing this path to a binary and resolving it to a file system path using the runfiles libraries
&gt; is the preferred approach to find dependencies at runtime. Compared to root path, it has the > is the preferred approach to find dependencies at runtime. Compared to root path, it has the
&gt; advantage that it works on all platforms and even if the runfiles directory is not available. > advantage that it works on all platforms and even if the runfiles directory is not available.
**PARAMETERS** **PARAMETERS**
@ -118,7 +118,7 @@ From https://bazel.build/reference/be/make-variables#predefined_genrule_variable
| Name | Description | Default Value | | Name | Description | Default Value |
| :------------- | :------------- | :------------- | | :------------- | :------------- | :------------- |
| <a id="to_rlocation_path-ctx"></a>ctx | starlark rule execution context | none | | <a id="to_rlocation_path-ctx"></a>ctx | starlark rule execution context | none |
| <a id="to_rlocation_path-file"></a>file | a <code>File</code> object | none | | <a id="to_rlocation_path-file"></a>file | a `File` object | none |
**RETURNS** **RETURNS**

104
docs/repo_utils.md generated
View File

@ -24,13 +24,55 @@ then they are taken from `ctx.attr`.
| Name | Description | Default Value | | Name | Description | Default Value |
| :------------- | :------------- | :------------- | | :------------- | :------------- | :------------- |
| <a id="patch-ctx"></a>ctx | The repository context of the repository rule calling this utility function. | none | | <a id="patch-ctx"></a>ctx | The repository context of the repository rule calling this utility function. | none |
| <a id="patch-patches"></a>patches | The patch files to apply. List of strings, Labels, or paths. | <code>None</code> | | <a id="patch-patches"></a>patches | The patch files to apply. List of strings, Labels, or paths. | `None` |
| <a id="patch-patch_cmds"></a>patch_cmds | Bash commands to run for patching, passed one at a time to bash -c. List of strings | <code>None</code> | | <a id="patch-patch_cmds"></a>patch_cmds | Bash commands to run for patching, passed one at a time to bash -c. List of strings | `None` |
| <a id="patch-patch_cmds_win"></a>patch_cmds_win | Powershell commands to run for patching, passed one at a time to powershell /c. List of strings. If the boolean value of this parameter is false, patch_cmds will be used and this parameter will be ignored. | <code>None</code> | | <a id="patch-patch_cmds_win"></a>patch_cmds_win | Powershell commands to run for patching, passed one at a time to powershell /c. List of strings. If the boolean value of this parameter is false, patch_cmds will be used and this parameter will be ignored. | `None` |
| <a id="patch-patch_tool"></a>patch_tool | Path of the patch tool to execute for applying patches. String. | <code>None</code> | | <a id="patch-patch_tool"></a>patch_tool | Path of the patch tool to execute for applying patches. String. | `None` |
| <a id="patch-patch_args"></a>patch_args | Arguments to pass to the patch tool. List of strings. | <code>None</code> | | <a id="patch-patch_args"></a>patch_args | Arguments to pass to the patch tool. List of strings. | `None` |
| <a id="patch-auth"></a>auth | An optional dict specifying authentication information for some of the URLs. | <code>None</code> | | <a id="patch-auth"></a>auth | An optional dict specifying authentication information for some of the URLs. | `None` |
| <a id="patch-patch_directory"></a>patch_directory | Directory to apply the patches in | <code>None</code> | | <a id="patch-patch_directory"></a>patch_directory | Directory to apply the patches in | `None` |
<a id="repo_utils.get_env_var"></a>
## repo_utils.get_env_var
<pre>
repo_utils.get_env_var(<a href="#repo_utils.get_env_var-rctx">rctx</a>, <a href="#repo_utils.get_env_var-name">name</a>, <a href="#repo_utils.get_env_var-default">default</a>)
</pre>
Find an environment variable in system. Doesn't %-escape the value!
**PARAMETERS**
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="repo_utils.get_env_var-rctx"></a>rctx | rctx | none |
| <a id="repo_utils.get_env_var-name"></a>name | environment variable name | none |
| <a id="repo_utils.get_env_var-default"></a>default | default value to return if env var is not set in system | none |
**RETURNS**
The environment variable value or the default if it is not set
<a id="repo_utils.get_home_directory"></a>
## repo_utils.get_home_directory
<pre>
repo_utils.get_home_directory(<a href="#repo_utils.get_home_directory-rctx">rctx</a>)
</pre>
**PARAMETERS**
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="repo_utils.get_home_directory-rctx"></a>rctx | <p align="center"> - </p> | none |
<a id="repo_utils.is_darwin"></a> <a id="repo_utils.is_darwin"></a>
@ -87,48 +129,6 @@ Returns true if the host operating system is Windows
| <a id="repo_utils.is_windows-rctx"></a>rctx | <p align="center"> - </p> | none | | <a id="repo_utils.is_windows-rctx"></a>rctx | <p align="center"> - </p> | none |
<a id="repo_utils.get_env_var"></a>
## repo_utils.get_env_var
<pre>
repo_utils.get_env_var(<a href="#repo_utils.get_env_var-rctx">rctx</a>, <a href="#repo_utils.get_env_var-name">name</a>, <a href="#repo_utils.get_env_var-default">default</a>)
</pre>
Find an environment variable in system. Doesn't %-escape the value!
**PARAMETERS**
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="repo_utils.get_env_var-rctx"></a>rctx | rctx | none |
| <a id="repo_utils.get_env_var-name"></a>name | environment variable name | none |
| <a id="repo_utils.get_env_var-default"></a>default | default value to return if env var is not set in system | none |
**RETURNS**
The environment variable value or the default if it is not set
<a id="repo_utils.get_home_directory"></a>
## repo_utils.get_home_directory
<pre>
repo_utils.get_home_directory(<a href="#repo_utils.get_home_directory-rctx">rctx</a>)
</pre>
**PARAMETERS**
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="repo_utils.get_home_directory-rctx"></a>rctx | <p align="center"> - </p> | none |
<a id="repo_utils.os"></a> <a id="repo_utils.os"></a>
## repo_utils.os ## repo_utils.os
@ -163,8 +163,8 @@ Returns a normalized name of the host os and CPU architecture.
Alias archictures names are normalized: Alias archictures names are normalized:
x86_64 =&gt; amd64 x86_64 => amd64
aarch64 =&gt; arm64 aarch64 => arm64
The result can be used to generate repository names for host toolchain The result can be used to generate repository names for host toolchain
repositories for toolchains that use these normalized names. repositories for toolchains that use these normalized names.
@ -189,6 +189,6 @@ Common os & architecture pairs that are returned are,
**RETURNS** **RETURNS**
The normalized "&lt;os&gt;_&lt;arch&gt;" string of the host os and CPU architecture. The normalized "<os>_<arch>" string of the host os and CPU architecture.

52
docs/repositories.md generated
View File

@ -45,13 +45,13 @@ Registers bats toolchain and repositories
| Name | Description | Default Value | | Name | Description | Default Value |
| :------------- | :------------- | :------------- | | :------------- | :------------- | :------------- |
| <a id="register_bats_toolchains-name"></a>name | override the prefix for the generated toolchain repositories | <code>"bats"</code> | | <a id="register_bats_toolchains-name"></a>name | override the prefix for the generated toolchain repositories | `"bats"` |
| <a id="register_bats_toolchains-core_version"></a>core_version | bats-core version to use | <code>"v1.10.0"</code> | | <a id="register_bats_toolchains-core_version"></a>core_version | bats-core version to use | `"v1.10.0"` |
| <a id="register_bats_toolchains-support_version"></a>support_version | bats-support version to use | <code>"v0.3.0"</code> | | <a id="register_bats_toolchains-support_version"></a>support_version | bats-support version to use | `"v0.3.0"` |
| <a id="register_bats_toolchains-assert_version"></a>assert_version | bats-assert version to use | <code>"v2.1.0"</code> | | <a id="register_bats_toolchains-assert_version"></a>assert_version | bats-assert version to use | `"v2.1.0"` |
| <a id="register_bats_toolchains-file_version"></a>file_version | bats-file version to use | <code>"v0.4.0"</code> | | <a id="register_bats_toolchains-file_version"></a>file_version | bats-file version to use | `"v0.4.0"` |
| <a id="register_bats_toolchains-libraries"></a>libraries | additional labels for libraries | <code>[]</code> | | <a id="register_bats_toolchains-libraries"></a>libraries | additional labels for libraries | `[]` |
| <a id="register_bats_toolchains-register"></a>register | whether to call through to native.register_toolchains. Should be True for WORKSPACE users, but false when used under bzlmod extension | <code>True</code> | | <a id="register_bats_toolchains-register"></a>register | whether to call through to native.register_toolchains. Should be True for WORKSPACE users, but false when used under bzlmod extension | `True` |
<a id="register_copy_directory_toolchains"></a> <a id="register_copy_directory_toolchains"></a>
@ -69,8 +69,8 @@ Registers copy_directory toolchain and repositories
| Name | Description | Default Value | | Name | Description | Default Value |
| :------------- | :------------- | :------------- | | :------------- | :------------- | :------------- |
| <a id="register_copy_directory_toolchains-name"></a>name | override the prefix for the generated toolchain repositories | <code>"copy_directory"</code> | | <a id="register_copy_directory_toolchains-name"></a>name | override the prefix for the generated toolchain repositories | `"copy_directory"` |
| <a id="register_copy_directory_toolchains-register"></a>register | whether to call through to native.register_toolchains. Should be True for WORKSPACE users, but false when used under bzlmod extension | <code>True</code> | | <a id="register_copy_directory_toolchains-register"></a>register | whether to call through to native.register_toolchains. Should be True for WORKSPACE users, but false when used under bzlmod extension | `True` |
<a id="register_copy_to_directory_toolchains"></a> <a id="register_copy_to_directory_toolchains"></a>
@ -88,8 +88,8 @@ Registers copy_to_directory toolchain and repositories
| Name | Description | Default Value | | Name | Description | Default Value |
| :------------- | :------------- | :------------- | | :------------- | :------------- | :------------- |
| <a id="register_copy_to_directory_toolchains-name"></a>name | override the prefix for the generated toolchain repositories | <code>"copy_to_directory"</code> | | <a id="register_copy_to_directory_toolchains-name"></a>name | override the prefix for the generated toolchain repositories | `"copy_to_directory"` |
| <a id="register_copy_to_directory_toolchains-register"></a>register | whether to call through to native.register_toolchains. Should be True for WORKSPACE users, but false when used under bzlmod extension | <code>True</code> | | <a id="register_copy_to_directory_toolchains-register"></a>register | whether to call through to native.register_toolchains. Should be True for WORKSPACE users, but false when used under bzlmod extension | `True` |
<a id="register_coreutils_toolchains"></a> <a id="register_coreutils_toolchains"></a>
@ -107,9 +107,9 @@ Registers coreutils toolchain and repositories
| Name | Description | Default Value | | Name | Description | Default Value |
| :------------- | :------------- | :------------- | | :------------- | :------------- | :------------- |
| <a id="register_coreutils_toolchains-name"></a>name | override the prefix for the generated toolchain repositories | <code>"coreutils"</code> | | <a id="register_coreutils_toolchains-name"></a>name | override the prefix for the generated toolchain repositories | `"coreutils"` |
| <a id="register_coreutils_toolchains-version"></a>version | the version of coreutils to execute (see https://github.com/uutils/coreutils/releases) | <code>"0.0.26"</code> | | <a id="register_coreutils_toolchains-version"></a>version | the version of coreutils to execute (see https://github.com/uutils/coreutils/releases) | `"0.0.26"` |
| <a id="register_coreutils_toolchains-register"></a>register | whether to call through to native.register_toolchains. Should be True for WORKSPACE users, but false when used under bzlmod extension | <code>True</code> | | <a id="register_coreutils_toolchains-register"></a>register | whether to call through to native.register_toolchains. Should be True for WORKSPACE users, but false when used under bzlmod extension | `True` |
<a id="register_expand_template_toolchains"></a> <a id="register_expand_template_toolchains"></a>
@ -127,8 +127,8 @@ Registers expand_template toolchain and repositories
| Name | Description | Default Value | | Name | Description | Default Value |
| :------------- | :------------- | :------------- | | :------------- | :------------- | :------------- |
| <a id="register_expand_template_toolchains-name"></a>name | override the prefix for the generated toolchain repositories | <code>"expand_template"</code> | | <a id="register_expand_template_toolchains-name"></a>name | override the prefix for the generated toolchain repositories | `"expand_template"` |
| <a id="register_expand_template_toolchains-register"></a>register | whether to call through to native.register_toolchains. Should be True for WORKSPACE users, but false when used under bzlmod extension | <code>True</code> | | <a id="register_expand_template_toolchains-register"></a>register | whether to call through to native.register_toolchains. Should be True for WORKSPACE users, but false when used under bzlmod extension | `True` |
<a id="register_jq_toolchains"></a> <a id="register_jq_toolchains"></a>
@ -146,9 +146,9 @@ Registers jq toolchain and repositories
| Name | Description | Default Value | | Name | Description | Default Value |
| :------------- | :------------- | :------------- | | :------------- | :------------- | :------------- |
| <a id="register_jq_toolchains-name"></a>name | override the prefix for the generated toolchain repositories | <code>"jq"</code> | | <a id="register_jq_toolchains-name"></a>name | override the prefix for the generated toolchain repositories | `"jq"` |
| <a id="register_jq_toolchains-version"></a>version | the version of jq to execute (see https://github.com/stedolan/jq/releases) | <code>"1.7"</code> | | <a id="register_jq_toolchains-version"></a>version | the version of jq to execute (see https://github.com/stedolan/jq/releases) | `"1.7"` |
| <a id="register_jq_toolchains-register"></a>register | whether to call through to native.register_toolchains. Should be True for WORKSPACE users, but false when used under bzlmod extension | <code>True</code> | | <a id="register_jq_toolchains-register"></a>register | whether to call through to native.register_toolchains. Should be True for WORKSPACE users, but false when used under bzlmod extension | `True` |
<a id="register_tar_toolchains"></a> <a id="register_tar_toolchains"></a>
@ -166,8 +166,8 @@ Registers bsdtar toolchain and repositories
| Name | Description | Default Value | | Name | Description | Default Value |
| :------------- | :------------- | :------------- | | :------------- | :------------- | :------------- |
| <a id="register_tar_toolchains-name"></a>name | override the prefix for the generated toolchain repositories | <code>"bsd_tar"</code> | | <a id="register_tar_toolchains-name"></a>name | override the prefix for the generated toolchain repositories | `"bsd_tar"` |
| <a id="register_tar_toolchains-register"></a>register | whether to call through to native.register_toolchains. Should be True for WORKSPACE users, but false when used under bzlmod extension | <code>True</code> | | <a id="register_tar_toolchains-register"></a>register | whether to call through to native.register_toolchains. Should be True for WORKSPACE users, but false when used under bzlmod extension | `True` |
<a id="register_yq_toolchains"></a> <a id="register_yq_toolchains"></a>
@ -185,9 +185,9 @@ Registers yq toolchain and repositories
| Name | Description | Default Value | | Name | Description | Default Value |
| :------------- | :------------- | :------------- | | :------------- | :------------- | :------------- |
| <a id="register_yq_toolchains-name"></a>name | override the prefix for the generated toolchain repositories | <code>"yq"</code> | | <a id="register_yq_toolchains-name"></a>name | override the prefix for the generated toolchain repositories | `"yq"` |
| <a id="register_yq_toolchains-version"></a>version | the version of yq to execute (see https://github.com/mikefarah/yq/releases) | <code>"4.25.2"</code> | | <a id="register_yq_toolchains-version"></a>version | the version of yq to execute (see https://github.com/mikefarah/yq/releases) | `"4.25.2"` |
| <a id="register_yq_toolchains-register"></a>register | whether to call through to native.register_toolchains. Should be True for WORKSPACE users, but false when used under bzlmod extension | <code>True</code> | | <a id="register_yq_toolchains-register"></a>register | whether to call through to native.register_toolchains. Should be True for WORKSPACE users, but false when used under bzlmod extension | `True` |
<a id="register_zstd_toolchains"></a> <a id="register_zstd_toolchains"></a>
@ -205,7 +205,7 @@ Registers zstd toolchain and repositories
| Name | Description | Default Value | | Name | Description | Default Value |
| :------------- | :------------- | :------------- | | :------------- | :------------- | :------------- |
| <a id="register_zstd_toolchains-name"></a>name | override the prefix for the generated toolchain repositories | <code>"zstd"</code> | | <a id="register_zstd_toolchains-name"></a>name | override the prefix for the generated toolchain repositories | `"zstd"` |
| <a id="register_zstd_toolchains-register"></a>register | whether to call through to native.register_toolchains. Should be True for WORKSPACE users, but false when used under bzlmod extension | <code>True</code> | | <a id="register_zstd_toolchains-register"></a>register | whether to call through to native.register_toolchains. Should be True for WORKSPACE users, but false when used under bzlmod extension | `True` |

1
docs/resource_sets.md generated
View File

@ -10,7 +10,6 @@ Rule authors who are ALSO the BUILD author might know better, and can
write custom resource_set functions for use within their own repository. write custom resource_set functions for use within their own repository.
This seems to be the use case that Google engineers imagined. This seems to be the use case that Google engineers imagined.
<a id="resource_set"></a> <a id="resource_set"></a>
## resource_set ## resource_set

23
docs/run_binary.md generated
View File

@ -4,7 +4,6 @@ Runs a binary as a build action. This rule does not require Bash (unlike native.
This fork of bazel-skylib's run_binary adds directory output support and better makevar expansions. This fork of bazel-skylib's run_binary adds directory output support and better makevar expansions.
<a id="run_binary"></a> <a id="run_binary"></a>
## run_binary ## run_binary
@ -25,17 +24,17 @@ This rule does not require Bash (unlike `native.genrule`).
| Name | Description | Default Value | | Name | Description | Default Value |
| :------------- | :------------- | :------------- | | :------------- | :------------- | :------------- |
| <a id="run_binary-name"></a>name | The target name | none | | <a id="run_binary-name"></a>name | The target name | none |
| <a id="run_binary-tool"></a>tool | The tool to run in the action.<br><br>Must be the label of a *_binary rule of a rule that generates an executable file, or of a file that can be executed as a subprocess (e.g. an .exe or .bat file on Windows or a binary with executable permission on Linux). This label is available for <code>$(location)</code> expansion in <code>args</code> and <code>env</code>. | none | | <a id="run_binary-tool"></a>tool | The tool to run in the action.<br><br>Must be the label of a *_binary rule of a rule that generates an executable file, or of a file that can be executed as a subprocess (e.g. an .exe or .bat file on Windows or a binary with executable permission on Linux). This label is available for `$(location)` expansion in `args` and `env`. | none |
| <a id="run_binary-srcs"></a>srcs | Additional inputs of the action.<br><br>These labels are available for <code>$(location)</code> expansion in <code>args</code> and <code>env</code>. | <code>[]</code> | | <a id="run_binary-srcs"></a>srcs | Additional inputs of the action.<br><br>These labels are available for `$(location)` expansion in `args` and `env`. | `[]` |
| <a id="run_binary-args"></a>args | Command line arguments of the binary.<br><br>Subject to <code>$(location)</code> and make variable expansions via [expand_location](./expand_make_vars#expand_locations) and [expand_make_vars](./expand_make_vars). | <code>[]</code> | | <a id="run_binary-args"></a>args | Command line arguments of the binary.<br><br>Subject to `$(location)` and make variable expansions via [expand_location](./expand_make_vars#expand_locations) and [expand_make_vars](./expand_make_vars). | `[]` |
| <a id="run_binary-env"></a>env | Environment variables of the action.<br><br>Subject to <code>$(location)</code> and make variable expansions via [expand_location](./expand_make_vars#expand_locations) and [expand_make_vars](./expand_make_vars). | <code>{}</code> | | <a id="run_binary-env"></a>env | Environment variables of the action.<br><br>Subject to `$(location)` and make variable expansions via [expand_location](./expand_make_vars#expand_locations) and [expand_make_vars](./expand_make_vars). | `{}` |
| <a id="run_binary-outs"></a>outs | Output files generated by the action.<br><br>These labels are available for <code>$(location)</code> expansion in <code>args</code> and <code>env</code>.<br><br>Output files cannot be nested within output directories in out_dirs. | <code>[]</code> | | <a id="run_binary-outs"></a>outs | Output files generated by the action.<br><br>These labels are available for `$(location)` expansion in `args` and `env`.<br><br>Output files cannot be nested within output directories in out_dirs. | `[]` |
| <a id="run_binary-out_dirs"></a>out_dirs | Output directories generated by the action.<br><br>These labels are _not_ available for <code>$(location)</code> expansion in <code>args</code> and <code>env</code> since they are not pre-declared labels created via <code>attr.output_list()</code>. Output directories are declared instead by <code>ctx.actions.declare_directory</code>.<br><br>Output directories cannot be nested within other output directories in out_dirs. | <code>[]</code> | | <a id="run_binary-out_dirs"></a>out_dirs | Output directories generated by the action.<br><br>These labels are _not_ available for `$(location)` expansion in `args` and `env` since they are not pre-declared labels created via `attr.output_list()`. Output directories are declared instead by `ctx.actions.declare_directory`.<br><br>Output directories cannot be nested within other output directories in out_dirs. | `[]` |
| <a id="run_binary-mnemonic"></a>mnemonic | A one-word description of the action, for example, CppCompile or GoLink. | <code>"RunBinary"</code> | | <a id="run_binary-mnemonic"></a>mnemonic | A one-word description of the action, for example, CppCompile or GoLink. | `"RunBinary"` |
| <a id="run_binary-progress_message"></a>progress_message | Progress message to show to the user during the build, for example, "Compiling foo.cc to create foo.o". The message may contain %{label}, %{input}, or %{output} patterns, which are substituted with label string, first input, or output's path, respectively. Prefer to use patterns instead of static strings, because the former are more efficient. | <code>None</code> | | <a id="run_binary-progress_message"></a>progress_message | Progress message to show to the user during the build, for example, "Compiling foo.cc to create foo.o". The message may contain %{label}, %{input}, or %{output} patterns, which are substituted with label string, first input, or output's path, respectively. Prefer to use patterns instead of static strings, because the former are more efficient. | `None` |
| <a id="run_binary-execution_requirements"></a>execution_requirements | Information for scheduling the action.<br><br>For example,<br><br><pre><code> execution_requirements = { "no-cache": "1", }, </code></pre><br><br>See https://docs.bazel.build/versions/main/be/common-definitions.html#common.tags for useful keys. | <code>None</code> | | <a id="run_binary-execution_requirements"></a>execution_requirements | Information for scheduling the action.<br><br>For example,<br><br><pre><code>execution_requirements = {&#10; "no-cache": "1",&#10;},</code></pre><br><br>See https://docs.bazel.build/versions/main/be/common-definitions.html#common.tags for useful keys. | `None` |
| <a id="run_binary-use_default_shell_env"></a>use_default_shell_env | Passed to the underlying ctx.actions.run.<br><br>May introduce non-determinism when True; use with care! See e.g. https://github.com/bazelbuild/bazel/issues/4912<br><br>Refer to https://bazel.build/rules/lib/builtins/actions#run for more details. | <code>False</code> | | <a id="run_binary-use_default_shell_env"></a>use_default_shell_env | Passed to the underlying ctx.actions.run.<br><br>May introduce non-determinism when True; use with care! See e.g. https://github.com/bazelbuild/bazel/issues/4912<br><br>Refer to https://bazel.build/rules/lib/builtins/actions#run for more details. | `False` |
| <a id="run_binary-stamp"></a>stamp | Whether to include build status files as inputs to the tool. Possible values:<br><br>- <code>stamp = 0</code> (default): Never include build status files as inputs to the tool. This gives good build result caching. Most tools don't use the status files, so including them in <code>--stamp</code> builds makes those builds have many needless cache misses. (Note: this default is different from most rules with an integer-typed <code>stamp</code> attribute.) - <code>stamp = 1</code>: Always include build status files as inputs to the tool, even in [--nostamp](https://docs.bazel.build/versions/main/user-manual.html#flag--stamp) builds. This setting should be avoided, since it is non-deterministic. It potentially causes remote cache misses for the target and any downstream actions that depend on the result. - <code>stamp = -1</code>: Inclusion of build status files as inputs is controlled by the [--[no]stamp](https://docs.bazel.build/versions/main/user-manual.html#flag--stamp) flag. Stamped targets are not rebuilt unless their dependencies change.<br><br>When stamping is enabled, an additional two environment variables will be set for the action: - <code>BAZEL_STABLE_STATUS_FILE</code> - <code>BAZEL_VOLATILE_STATUS_FILE</code><br><br>These files can be read and parsed by the action, for example to pass some values to a linker. | <code>0</code> | | <a id="run_binary-stamp"></a>stamp | Whether to include build status files as inputs to the tool. Possible values:<br><br>- `stamp = 0` (default): Never include build status files as inputs to the tool. This gives good build result caching. Most tools don't use the status files, so including them in `--stamp` builds makes those builds have many needless cache misses. (Note: this default is different from most rules with an integer-typed `stamp` attribute.) - `stamp = 1`: Always include build status files as inputs to the tool, even in [--nostamp](https://docs.bazel.build/versions/main/user-manual.html#flag--stamp) builds. This setting should be avoided, since it is non-deterministic. It potentially causes remote cache misses for the target and any downstream actions that depend on the result. - `stamp = -1`: Inclusion of build status files as inputs is controlled by the [--[no]stamp](https://docs.bazel.build/versions/main/user-manual.html#flag--stamp) flag. Stamped targets are not rebuilt unless their dependencies change.<br><br>When stamping is enabled, an additional two environment variables will be set for the action: - `BAZEL_STABLE_STATUS_FILE` - `BAZEL_VOLATILE_STATUS_FILE`<br><br>These files can be read and parsed by the action, for example to pass some values to a linker. | `0` |
| <a id="run_binary-kwargs"></a>kwargs | Additional arguments | none | | <a id="run_binary-kwargs"></a>kwargs | Additional arguments | none |

13
docs/stamping.md generated
View File

@ -9,8 +9,8 @@ See [the Bazel workspace status docs](https://docs.bazel.build/versions/master/u
To stamp a build, you pass the `--stamp` argument to Bazel. To stamp a build, you pass the `--stamp` argument to Bazel.
&gt; Note: https://github.com/bazelbuild/bazel/issues/14341 proposes that Bazel enforce this by > Note: https://github.com/bazelbuild/bazel/issues/14341 proposes that Bazel enforce this by
&gt; only giving constant values to rule implementations when stamping isn't enabled. > only giving constant values to rule implementations when stamping isn't enabled.
Stamping is typically performed on a later action in the graph, like on a linking or packaging rule (`pkg_*`). Stamping is typically performed on a later action in the graph, like on a linking or packaging rule (`pkg_*`).
This means that a changed status variable only causes that action, not re-compilation and thus does not cause cascading re-builds. This means that a changed status variable only causes that action, not re-compilation and thus does not cause cascading re-builds.
@ -32,13 +32,13 @@ The value of this flag is a path to a script that prints space-separated key/val
#!/usr/bin/env bash #!/usr/bin/env bash
echo STABLE_GIT_COMMIT $(git rev-parse HEAD) echo STABLE_GIT_COMMIT $(git rev-parse HEAD)
``` ```
&gt; For a more full-featured script, take a look at this [example in Angular] > For a more full-featured script, take a look at this [example in Angular]
Make sure you set the executable bit, eg. `chmod +x tools/bazel_stamp_vars.sh`. Make sure you set the executable bit, eg. `chmod +x tools/bazel_stamp_vars.sh`.
&gt; **NOTE** keys that start with `STABLE_` will cause a re-build when they change. > **NOTE** keys that start with `STABLE_` will cause a re-build when they change.
&gt; Other keys will NOT cause a re-build, so stale values can appear in your app. > Other keys will NOT cause a re-build, so stale values can appear in your app.
&gt; Non-stable (volatile) keys should typically be things like timestamps that always vary between builds. > Non-stable (volatile) keys should typically be things like timestamps that always vary between builds.
You might like to encode your setup using an entry in `.bazelrc` such as: You might like to encode your setup using an entry in `.bazelrc` such as:
@ -89,7 +89,6 @@ my_stamp_aware_rule = rule(
) )
``` ```
<a id="maybe_stamp"></a> <a id="maybe_stamp"></a>
## maybe_stamp ## maybe_stamp

81
docs/tar.md generated
View File

@ -53,13 +53,12 @@ tar(
TODO: TODO:
- Provide convenience for rules_pkg users to re-use or replace pkg_files trees - Provide convenience for rules_pkg users to re-use or replace pkg_files trees
<a id="mtree_spec"></a> <a id="mtree_spec"></a>
## mtree_spec ## mtree_spec
<pre> <pre>
mtree_spec(<a href="#mtree_spec-name">name</a>, <a href="#mtree_spec-out">out</a>, <a href="#mtree_spec-srcs">srcs</a>) mtree_spec(<a href="#mtree_spec-name">name</a>, <a href="#mtree_spec-srcs">srcs</a>, <a href="#mtree_spec-out">out</a>)
</pre> </pre>
Create an mtree specification to map a directory hierarchy. See https://man.freebsd.org/cgi/man.cgi?mtree(8) Create an mtree specification to map a directory hierarchy. See https://man.freebsd.org/cgi/man.cgi?mtree(8)
@ -70,8 +69,8 @@ Create an mtree specification to map a directory hierarchy. See https://man.free
| Name | Description | Type | Mandatory | Default | | Name | Description | Type | Mandatory | Default |
| :------------- | :------------- | :------------- | :------------- | :------------- | | :------------- | :------------- | :------------- | :------------- | :------------- |
| <a id="mtree_spec-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | | | <a id="mtree_spec-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | |
| <a id="mtree_spec-out"></a>out | Resulting specification file to write | <a href="https://bazel.build/concepts/labels">Label</a> | optional | | | <a id="mtree_spec-srcs"></a>srcs | Files that are placed into the tar | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | `[]` |
| <a id="mtree_spec-srcs"></a>srcs | Files that are placed into the tar | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | <code>[]</code> | | <a id="mtree_spec-out"></a>out | Resulting specification file to write | <a href="https://bazel.build/concepts/labels">Label</a> | optional | `None` |
<a id="tar_rule"></a> <a id="tar_rule"></a>
@ -79,7 +78,7 @@ Create an mtree specification to map a directory hierarchy. See https://man.free
## tar_rule ## tar_rule
<pre> <pre>
tar_rule(<a href="#tar_rule-name">name</a>, <a href="#tar_rule-args">args</a>, <a href="#tar_rule-compress">compress</a>, <a href="#tar_rule-mode">mode</a>, <a href="#tar_rule-mtree">mtree</a>, <a href="#tar_rule-out">out</a>, <a href="#tar_rule-srcs">srcs</a>) tar_rule(<a href="#tar_rule-name">name</a>, <a href="#tar_rule-srcs">srcs</a>, <a href="#tar_rule-out">out</a>, <a href="#tar_rule-args">args</a>, <a href="#tar_rule-compress">compress</a>, <a href="#tar_rule-mode">mode</a>, <a href="#tar_rule-mtree">mtree</a>)
</pre> </pre>
Rule that executes BSD `tar`. Most users should use the [`tar`](#tar) macro, rather than load this directly. Rule that executes BSD `tar`. Most users should use the [`tar`](#tar) macro, rather than load this directly.
@ -90,12 +89,12 @@ Rule that executes BSD `tar`. Most users should use the [`tar`](#tar) macro, rat
| Name | Description | Type | Mandatory | Default | | Name | Description | Type | Mandatory | Default |
| :------------- | :------------- | :------------- | :------------- | :------------- | | :------------- | :------------- | :------------- | :------------- | :------------- |
| <a id="tar_rule-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | | | <a id="tar_rule-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | |
| <a id="tar_rule-args"></a>args | Additional flags permitted by BSD tar; see the man page. | List of strings | optional | <code>[]</code> | | <a id="tar_rule-srcs"></a>srcs | Files, directories, or other targets whose default outputs are placed into the tar.<br><br>If any of the srcs are binaries with runfiles, those are copied into the resulting tar as well. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | `[]` |
| <a id="tar_rule-compress"></a>compress | Compress the archive file with a supported algorithm. | String | optional | <code>""</code> | | <a id="tar_rule-out"></a>out | Resulting tar file to write. If absent, `[name].tar` is written. | <a href="https://bazel.build/concepts/labels">Label</a> | optional | `None` |
| <a id="tar_rule-mode"></a>mode | A mode indicator from the following list, copied from the tar manpage:<br><br> - create: Create a new archive containing the specified items. - append: Like <code>create</code>, but new entries are appended to the archive. Note that this only works on uncompressed archives stored in regular files. The -f option is required. - list: List archive contents to stdout. - update: Like <code>append</code>, but new entries are added only if they have a modification date newer than the corresponding entry in the archive. Note that this only works on uncompressed archives stored in regular files. The -f option is required. - extract: Extract to disk from the archive. If a file with the same name appears more than once in the archive, each copy will be extracted, with later copies overwriting (replacing) earlier copies. | String | optional | <code>"create"</code> | | <a id="tar_rule-args"></a>args | Additional flags permitted by BSD tar; see the man page. | List of strings | optional | `[]` |
| <a id="tar_rule-compress"></a>compress | Compress the archive file with a supported algorithm. | String | optional | `""` |
| <a id="tar_rule-mode"></a>mode | A mode indicator from the following list, copied from the tar manpage:<br><br>- create: Create a new archive containing the specified items. - append: Like `create`, but new entries are appended to the archive. Note that this only works on uncompressed archives stored in regular files. The -f option is required. - list: List archive contents to stdout. - update: Like `append`, but new entries are added only if they have a modification date newer than the corresponding entry in the archive. Note that this only works on uncompressed archives stored in regular files. The -f option is required. - extract: Extract to disk from the archive. If a file with the same name appears more than once in the archive, each copy will be extracted, with later copies overwriting (replacing) earlier copies. | String | optional | `"create"` |
| <a id="tar_rule-mtree"></a>mtree | An mtree specification file | <a href="https://bazel.build/concepts/labels">Label</a> | required | | | <a id="tar_rule-mtree"></a>mtree | An mtree specification file | <a href="https://bazel.build/concepts/labels">Label</a> | required | |
| <a id="tar_rule-out"></a>out | Resulting tar file to write. If absent, <code>[name].tar</code> is written. | <a href="https://bazel.build/concepts/labels">Label</a> | optional | |
| <a id="tar_rule-srcs"></a>srcs | Files, directories, or other targets whose default outputs are placed into the tar.<br><br> If any of the srcs are binaries with runfiles, those are copied into the resulting tar as well. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | <code>[]</code> |
<a id="mtree_mutate"></a> <a id="mtree_mutate"></a>
@ -113,14 +112,14 @@ Modify metadata in an mtree file.
| Name | Description | Default Value | | Name | Description | Default Value |
| :------------- | :------------- | :------------- | | :------------- | :------------- | :------------- |
| <a id="mtree_mutate-name"></a>name | name of the target, output will be <code>[name].mtree</code>. | none | | <a id="mtree_mutate-name"></a>name | name of the target, output will be `[name].mtree`. | none |
| <a id="mtree_mutate-mtree"></a>mtree | input mtree file, typically created by <code>mtree_spec</code>. | none | | <a id="mtree_mutate-mtree"></a>mtree | input mtree file, typically created by `mtree_spec`. | none |
| <a id="mtree_mutate-strip_prefix"></a>strip_prefix | prefix to remove from all paths in the tar. Files and directories not under this prefix are dropped. | <code>None</code> | | <a id="mtree_mutate-strip_prefix"></a>strip_prefix | prefix to remove from all paths in the tar. Files and directories not under this prefix are dropped. | `None` |
| <a id="mtree_mutate-package_dir"></a>package_dir | directory prefix to add to all paths in the tar. | <code>None</code> | | <a id="mtree_mutate-package_dir"></a>package_dir | directory prefix to add to all paths in the tar. | `None` |
| <a id="mtree_mutate-mtime"></a>mtime | new modification time for all entries. | <code>None</code> | | <a id="mtree_mutate-mtime"></a>mtime | new modification time for all entries. | `None` |
| <a id="mtree_mutate-owner"></a>owner | new uid for all entries. | <code>None</code> | | <a id="mtree_mutate-owner"></a>owner | new uid for all entries. | `None` |
| <a id="mtree_mutate-ownername"></a>ownername | new uname for all entries. | <code>None</code> | | <a id="mtree_mutate-ownername"></a>ownername | new uname for all entries. | `None` |
| <a id="mtree_mutate-awk_script"></a>awk_script | may be overridden to change the script containing the modification logic. | <code>"@aspect_bazel_lib//lib/private:modify_mtree.awk"</code> | | <a id="mtree_mutate-awk_script"></a>awk_script | may be overridden to change the script containing the modification logic. | `"@aspect_bazel_lib//lib/private:modify_mtree.awk"` |
| <a id="mtree_mutate-kwargs"></a>kwargs | additional named parameters to genrule | none | | <a id="mtree_mutate-kwargs"></a>kwargs | additional named parameters to genrule | none |
@ -164,10 +163,29 @@ https://man.freebsd.org/cgi/man.cgi?mtree(8)
| Name | Description | Default Value | | Name | Description | Default Value |
| :------------- | :------------- | :------------- | | :------------- | :------------- | :------------- |
| <a id="tar-name"></a>name | name of resulting <code>tar_rule</code> | none | | <a id="tar-name"></a>name | name of resulting `tar_rule` | none |
| <a id="tar-mtree"></a>mtree | "auto", or an array of specification lines, or a label of a file that contains the lines. Subject to [$(location)](https://bazel.build/reference/be/make-variables#predefined_label_variables) and ["Make variable"](https://bazel.build/reference/be/make-variables) substitution. | <code>"auto"</code> | | <a id="tar-mtree"></a>mtree | "auto", or an array of specification lines, or a label of a file that contains the lines. Subject to [$(location)](https://bazel.build/reference/be/make-variables#predefined_label_variables) and ["Make variable"](https://bazel.build/reference/be/make-variables) substitution. | `"auto"` |
| <a id="tar-stamp"></a>stamp | should mtree attribute be stamped | <code>0</code> | | <a id="tar-stamp"></a>stamp | should mtree attribute be stamped | `0` |
| <a id="tar-kwargs"></a>kwargs | additional named parameters to pass to <code>tar_rule</code> | none | | <a id="tar-kwargs"></a>kwargs | additional named parameters to pass to `tar_rule` | none |
<a id="tar_lib.common.add_compression_args"></a>
## tar_lib.common.add_compression_args
<pre>
tar_lib.common.add_compression_args(<a href="#tar_lib.common.add_compression_args-compress">compress</a>, <a href="#tar_lib.common.add_compression_args-args">args</a>)
</pre>
**PARAMETERS**
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="tar_lib.common.add_compression_args-compress"></a>compress | <p align="center"> - </p> | none |
| <a id="tar_lib.common.add_compression_args-args"></a>args | <p align="center"> - </p> | none |
<a id="tar_lib.implementation"></a> <a id="tar_lib.implementation"></a>
@ -206,22 +224,3 @@ tar_lib.mtree_implementation(<a href="#tar_lib.mtree_implementation-ctx">ctx</a>
| <a id="tar_lib.mtree_implementation-ctx"></a>ctx | <p align="center"> - </p> | none | | <a id="tar_lib.mtree_implementation-ctx"></a>ctx | <p align="center"> - </p> | none |
<a id="tar_lib.common.add_compression_args"></a>
## tar_lib.common.add_compression_args
<pre>
tar_lib.common.add_compression_args(<a href="#tar_lib.common.add_compression_args-compress">compress</a>, <a href="#tar_lib.common.add_compression_args-args">args</a>)
</pre>
**PARAMETERS**
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="tar_lib.common.add_compression_args-compress"></a>compress | <p align="center"> - </p> | none |
| <a id="tar_lib.common.add_compression_args-args"></a>args | <p align="center"> - </p> | none |

4
docs/templates/BUILD.bazel vendored
View File

@ -1,4 +0,0 @@
exports_files([
"func_html.vm",
"rule_html.vm",
])

49
docs/templates/func_html.vm vendored
View File

@ -1,49 +0,0 @@
#**
This func template is used for rendering HTML in parameter table cells
*#
#*
Workaround for markdownCellFormat() not allowing HTML (specifically lists) to be rendered in attribute table cells.
TODO: Once https://github.com/bazelbuild/bazel/pull/14230 is merged, remove this macro and replace with call to
util.markdownCellFormatWithHtml($attribute.docString, true)
*#
#macro( markdownCellFormatNoEscapeHtml $docString )#*
*##if ($docString.contains("<ul>") || $docString.contains("<ol>"))#*
*#${docString.trim().replaceAll("\n(\\s*\n)+", "<br><br>").replaceAll("\n", " ")}#*
*##else#*
*#${util.markdownCellFormat($docString)}#*
*##end#*
*##end
<a id="#${funcInfo.functionName}"></a>
#[[##]]# ${funcInfo.functionName}
<pre>
${util.funcSummary($funcInfo)}
</pre>
${funcInfo.docString}
#if (!$funcInfo.getParameterList().isEmpty())
#[[###]]# **Parameters**
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
#foreach ($param in $funcInfo.getParameterList())
| <a id="${funcInfo.functionName}-${param.name}"></a>$param.name | #if(!$param.docString.isEmpty()) #markdownCellFormatNoEscapeHtml( $param.docString ) #else <p align="center"> - </p> #end | #if(!$param.getDefaultValue().isEmpty()) <code>$param.getDefaultValue()</code> #else none #end|
#end
#end
#if (!$funcInfo.getReturn().docString.isEmpty())
#[[###]]# **Returns**
${funcInfo.getReturn().docString}
#end
#if (!$funcInfo.getDeprecated().docString.isEmpty())
#[[###]]# **Deprecated**
${funcInfo.getDeprecated().docString}
#end

37
docs/templates/rule_html.vm vendored
View File

@ -1,37 +0,0 @@
#**
This rule template is used for rendering HTML in attribute table cells
*#
#*
Workaround for markdownCellFormat() not allowing HTML (specifically lists) to be rendered in attribute table cells.
TODO: Once https://github.com/bazelbuild/bazel/pull/14230 is merged, remove this macro and replace with call to
util.markdownCellFormatWithHtml($attribute.docString, true)
*#
#macro( markdownCellFormatNoEscapeHtml $docString )#*
*##if ($docString.contains("<ul>") || $docString.contains("<ol>"))#*
*#${docString.trim().replaceAll("\n(\\s*\n)+", "<br><br>").replaceAll("\n", " ")}#*
*##else#*
*#${util.markdownCellFormat($docString)}#*
*##end#*
*##end
<a id="#${ruleName}"></a>
#[[##]]# ${ruleName}
<pre>
${util.ruleSummary($ruleName, $ruleInfo)}
</pre>
${ruleInfo.docString}
#[[###]]# **Attributes**
#if (!$ruleInfo.getAttributeList().isEmpty())
| Name | Description | Type | Mandatory | Default |
| :------------- | :------------- | :------------- | :------------- | :------------- |
#foreach ($attribute in $ruleInfo.getAttributeList())
| <a id="${ruleName}-${attribute.name}"></a>$attribute.name | #if(!$attribute.docString.isEmpty()) #markdownCellFormatNoEscapeHtml( $attribute.docString ) #else - #end | ${util.attributeTypeString($attribute)} | ${util.mandatoryString($attribute)} | $attribute.defaultValue |
#end
#end

8
docs/testing.md generated
View File

@ -20,7 +20,7 @@ Assert that an archive file contains at least the given file entries.
| <a id="assert_archive_contains-name"></a>name | name of the resulting sh_test target | none | | <a id="assert_archive_contains-name"></a>name | name of the resulting sh_test target | none |
| <a id="assert_archive_contains-archive"></a>archive | Label of the the .tar or .zip file | none | | <a id="assert_archive_contains-archive"></a>archive | Label of the the .tar or .zip file | none |
| <a id="assert_archive_contains-expected"></a>expected | a (partial) file listing, either as a Label of a file containing it, or a list of strings | none | | <a id="assert_archive_contains-expected"></a>expected | a (partial) file listing, either as a Label of a file containing it, or a list of strings | none |
| <a id="assert_archive_contains-type"></a>type | "tar" or "zip". If None, a type will be inferred from the filename. | <code>None</code> | | <a id="assert_archive_contains-type"></a>type | "tar" or "zip". If None, a type will be inferred from the filename. | `None` |
| <a id="assert_archive_contains-kwargs"></a>kwargs | additional named arguments for the resulting sh_test | none | | <a id="assert_archive_contains-kwargs"></a>kwargs | additional named arguments for the resulting sh_test | none |
@ -45,7 +45,7 @@ Depends on bash, as it creates an sh_test target.
| <a id="assert_contains-name"></a>name | target to create | none | | <a id="assert_contains-name"></a>name | target to create | none |
| <a id="assert_contains-actual"></a>actual | Label of a file | none | | <a id="assert_contains-actual"></a>actual | Label of a file | none |
| <a id="assert_contains-expected"></a>expected | a string which should appear in the file | none | | <a id="assert_contains-expected"></a>expected | a string which should appear in the file | none |
| <a id="assert_contains-size"></a>size | standard attribute for tests | <code>"small"</code> | | <a id="assert_contains-size"></a>size | standard attribute for tests | `"small"` |
| <a id="assert_contains-kwargs"></a>kwargs | additional named arguments for the resulting sh_test | none | | <a id="assert_contains-kwargs"></a>kwargs | additional named arguments for the resulting sh_test | none |
@ -95,8 +95,8 @@ setup notes for the `jq` toolchain.
| <a id="assert_json_matches-name"></a>name | name of resulting diff_test target | none | | <a id="assert_json_matches-name"></a>name | name of resulting diff_test target | none |
| <a id="assert_json_matches-file1"></a>file1 | a json file | none | | <a id="assert_json_matches-file1"></a>file1 | a json file | none |
| <a id="assert_json_matches-file2"></a>file2 | another json file | none | | <a id="assert_json_matches-file2"></a>file2 | another json file | none |
| <a id="assert_json_matches-filter1"></a>filter1 | a jq filter to apply to file1 | <code>"."</code> | | <a id="assert_json_matches-filter1"></a>filter1 | a jq filter to apply to file1 | `"."` |
| <a id="assert_json_matches-filter2"></a>filter2 | a jq filter to apply to file2 | <code>"."</code> | | <a id="assert_json_matches-filter2"></a>filter2 | a jq filter to apply to file2 | `"."` |
| <a id="assert_json_matches-kwargs"></a>kwargs | additional named arguments for the resulting diff_test | none | | <a id="assert_json_matches-kwargs"></a>kwargs | additional named arguments for the resulting diff_test | none |

10
docs/transitions.md generated
View File

@ -18,8 +18,8 @@ Transitions the binary to use the provided platform.
| Name | Description | Type | Mandatory | Default | | Name | Description | Type | Mandatory | Default |
| :------------- | :------------- | :------------- | :------------- | :------------- | | :------------- | :------------- | :------------- | :------------- | :------------- |
| <a id="platform_transition_binary-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | | | <a id="platform_transition_binary-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | |
| <a id="platform_transition_binary-basename"></a>basename | - | String | optional | <code>""</code> | | <a id="platform_transition_binary-basename"></a>basename | - | String | optional | `""` |
| <a id="platform_transition_binary-binary"></a>binary | - | <a href="https://bazel.build/concepts/labels">Label</a> | optional | <code>None</code> | | <a id="platform_transition_binary-binary"></a>binary | - | <a href="https://bazel.build/concepts/labels">Label</a> | optional | `None` |
| <a id="platform_transition_binary-target_platform"></a>target_platform | The target platform to transition the binary. | <a href="https://bazel.build/concepts/labels">Label</a> | required | | | <a id="platform_transition_binary-target_platform"></a>target_platform | The target platform to transition the binary. | <a href="https://bazel.build/concepts/labels">Label</a> | required | |
@ -39,7 +39,7 @@ Transitions the srcs to use the provided platform. The filegroup will contain ar
| Name | Description | Type | Mandatory | Default | | Name | Description | Type | Mandatory | Default |
| :------------- | :------------- | :------------- | :------------- | :------------- | | :------------- | :------------- | :------------- | :------------- | :------------- |
| <a id="platform_transition_filegroup-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | | | <a id="platform_transition_filegroup-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | |
| <a id="platform_transition_filegroup-srcs"></a>srcs | The input to be transitioned to the target platform. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | <code>[]</code> | | <a id="platform_transition_filegroup-srcs"></a>srcs | The input to be transitioned to the target platform. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | `[]` |
| <a id="platform_transition_filegroup-target_platform"></a>target_platform | The target platform to transition the srcs. | <a href="https://bazel.build/concepts/labels">Label</a> | required | | | <a id="platform_transition_filegroup-target_platform"></a>target_platform | The target platform to transition the srcs. | <a href="https://bazel.build/concepts/labels">Label</a> | required | |
@ -59,8 +59,8 @@ Transitions the test to use the provided platform.
| Name | Description | Type | Mandatory | Default | | Name | Description | Type | Mandatory | Default |
| :------------- | :------------- | :------------- | :------------- | :------------- | | :------------- | :------------- | :------------- | :------------- | :------------- |
| <a id="platform_transition_test-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | | | <a id="platform_transition_test-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | |
| <a id="platform_transition_test-basename"></a>basename | - | String | optional | <code>""</code> | | <a id="platform_transition_test-basename"></a>basename | - | String | optional | `""` |
| <a id="platform_transition_test-binary"></a>binary | - | <a href="https://bazel.build/concepts/labels">Label</a> | optional | <code>None</code> | | <a id="platform_transition_test-binary"></a>binary | - | <a href="https://bazel.build/concepts/labels">Label</a> | optional | `None` |
| <a id="platform_transition_test-target_platform"></a>target_platform | The target platform to transition the binary. | <a href="https://bazel.build/concepts/labels">Label</a> | required | | | <a id="platform_transition_test-target_platform"></a>target_platform | The target platform to transition the binary. | <a href="https://bazel.build/concepts/labels">Label</a> | required | |

128
docs/utils.md generated
View File

@ -1,6 +1,14 @@
<!-- Generated with Stardoc: http://skydoc.bazel.build --> <!-- Generated with Stardoc: http://skydoc.bazel.build -->
Public API General-purpose Starlark utility functions
## Usage example
```starlark
load("@aspect_bazel_lib//lib:utils.bzl", "utils")
out_label = utils.to_label(out_file)
```
<a id="consistent_label_str"></a> <a id="consistent_label_str"></a>
@ -46,15 +54,15 @@ Provide a sane default for *_test timeout attribute.
The [test-encyclopedia](https://bazel.build/reference/test-encyclopedia) says: The [test-encyclopedia](https://bazel.build/reference/test-encyclopedia) says:
&gt; Tests may return arbitrarily fast regardless of timeout. > Tests may return arbitrarily fast regardless of timeout.
&gt; A test is not penalized for an overgenerous timeout, although a warning may be issued: > A test is not penalized for an overgenerous timeout, although a warning may be issued:
&gt; you should generally set your timeout as tight as you can without incurring any flakiness. > you should generally set your timeout as tight as you can without incurring any flakiness.
However Bazel's default for timeout is medium, which is dumb given this guidance. However Bazel's default for timeout is medium, which is dumb given this guidance.
It also says: It also says:
&gt; Tests which do not explicitly specify a timeout have one implied based on the test's size as follows > Tests which do not explicitly specify a timeout have one implied based on the test's size as follows
Therefore if size is specified, we should allow timeout to take its implied default. Therefore if size is specified, we should allow timeout to take its implied default.
If neither is set, then we can fix Bazel's wrong default here to avoid warnings under If neither is set, then we can fix Bazel's wrong default here to avoid warnings under
@ -287,7 +295,7 @@ maybe(
path_to_workspace_root() path_to_workspace_root()
</pre> </pre>
Returns the path to the workspace root under bazel Returns the path to the workspace root under bazel
**RETURNS** **RETURNS**
@ -395,7 +403,7 @@ https://docs.bazel.build/versions/main/be/common-definitions.html#common-attribu
| Name | Description | Default Value | | Name | Description | Default Value |
| :------------- | :------------- | :------------- | | :------------- | :------------- | :------------- |
| <a id="propagate_well_known_tags-tags"></a>tags | List of tags to filter | <code>[]</code> | | <a id="propagate_well_known_tags-tags"></a>tags | List of tags to filter | `[]` |
**RETURNS** **RETURNS**
@ -424,6 +432,38 @@ Converts a string to a Label. If Label is supplied, the same label is returned.
a Label a Label
<a id="utils.consistent_label_str"></a>
## utils.consistent_label_str
<pre>
utils.consistent_label_str(<a href="#utils.consistent_label_str-ctx">ctx</a>, <a href="#utils.consistent_label_str-label">label</a>)
</pre>
Generate a consistent label string for all Bazel versions.
Starting in Bazel 6, the workspace name is empty for the local workspace and there's no other
way to determine it. This behavior differs from Bazel 5 where the local workspace name was fully
qualified in str(label).
This utility function is meant for use in rules and requires the rule context to determine the
user's workspace name (`ctx.workspace_name`).
**PARAMETERS**
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="utils.consistent_label_str-ctx"></a>ctx | The rule context. | none |
| <a id="utils.consistent_label_str-label"></a>label | A Label. | none |
**RETURNS**
String representation of the label including the repository name if the label is from an
external repository. For labels in the user's repository the label will start with `@//`.
<a id="utils.default_timeout"></a> <a id="utils.default_timeout"></a>
## utils.default_timeout ## utils.default_timeout
@ -436,15 +476,15 @@ Provide a sane default for *_test timeout attribute.
The [test-encyclopedia](https://bazel.build/reference/test-encyclopedia) says: The [test-encyclopedia](https://bazel.build/reference/test-encyclopedia) says:
&gt; Tests may return arbitrarily fast regardless of timeout. > Tests may return arbitrarily fast regardless of timeout.
&gt; A test is not penalized for an overgenerous timeout, although a warning may be issued: > A test is not penalized for an overgenerous timeout, although a warning may be issued:
&gt; you should generally set your timeout as tight as you can without incurring any flakiness. > you should generally set your timeout as tight as you can without incurring any flakiness.
However Bazel's default for timeout is medium, which is dumb given this guidance. However Bazel's default for timeout is medium, which is dumb given this guidance.
It also says: It also says:
&gt; Tests which do not explicitly specify a timeout have one implied based on the test's size as follows > Tests which do not explicitly specify a timeout have one implied based on the test's size as follows
Therefore if size is specified, we should allow timeout to take its implied default. Therefore if size is specified, we should allow timeout to take its implied default.
If neither is set, then we can fix Bazel's wrong default here to avoid warnings under If neither is set, then we can fix Bazel's wrong default here to avoid warnings under
@ -677,7 +717,7 @@ maybe(
utils.path_to_workspace_root() utils.path_to_workspace_root()
</pre> </pre>
Returns the path to the workspace root under bazel Returns the path to the workspace root under bazel
**RETURNS** **RETURNS**
@ -685,19 +725,19 @@ utils.path_to_workspace_root()
Path to the workspace root Path to the workspace root
<a id="utils.propagate_well_known_tags"></a> <a id="utils.propagate_common_binary_rule_attributes"></a>
## utils.propagate_well_known_tags ## utils.propagate_common_binary_rule_attributes
<pre> <pre>
utils.propagate_well_known_tags(<a href="#utils.propagate_well_known_tags-tags">tags</a>) utils.propagate_common_binary_rule_attributes(<a href="#utils.propagate_common_binary_rule_attributes-attrs">attrs</a>)
</pre> </pre>
Returns a list of tags filtered from the input set that only contains the ones that are considered "well known" Returns a dict of rule parameters filtered from the input dict that only contains the ones that are common to all binary rules
These are listed in Bazel's documentation: These are listed in Bazel's documentation:
https://docs.bazel.build/versions/main/test-encyclopedia.html#tag-conventions https://bazel.build/reference/be/common-definitions#common-attributes
https://docs.bazel.build/versions/main/be/common-definitions.html#common-attributes https://bazel.build/reference/be/common-definitions#common-attributes-binary
**PARAMETERS** **PARAMETERS**
@ -705,11 +745,11 @@ https://docs.bazel.build/versions/main/be/common-definitions.html#common-attribu
| Name | Description | Default Value | | Name | Description | Default Value |
| :------------- | :------------- | :------------- | | :------------- | :------------- | :------------- |
| <a id="utils.propagate_well_known_tags-tags"></a>tags | List of tags to filter | <code>[]</code> | | <a id="utils.propagate_common_binary_rule_attributes-attrs"></a>attrs | Dict of parameters to filter | none |
**RETURNS** **RETURNS**
List of tags that only contains the well known set The dict of parameters, containing only common binary attributes
<a id="utils.propagate_common_rule_attributes"></a> <a id="utils.propagate_common_rule_attributes"></a>
@ -765,19 +805,19 @@ https://bazel.build/reference/be/common-definitions#common-attributes-tests
The dict of parameters, containing only common test attributes The dict of parameters, containing only common test attributes
<a id="utils.propagate_common_binary_rule_attributes"></a> <a id="utils.propagate_well_known_tags"></a>
## utils.propagate_common_binary_rule_attributes ## utils.propagate_well_known_tags
<pre> <pre>
utils.propagate_common_binary_rule_attributes(<a href="#utils.propagate_common_binary_rule_attributes-attrs">attrs</a>) utils.propagate_well_known_tags(<a href="#utils.propagate_well_known_tags-tags">tags</a>)
</pre> </pre>
Returns a dict of rule parameters filtered from the input dict that only contains the ones that are common to all binary rules Returns a list of tags filtered from the input set that only contains the ones that are considered "well known"
These are listed in Bazel's documentation: These are listed in Bazel's documentation:
https://bazel.build/reference/be/common-definitions#common-attributes https://docs.bazel.build/versions/main/test-encyclopedia.html#tag-conventions
https://bazel.build/reference/be/common-definitions#common-attributes-binary https://docs.bazel.build/versions/main/be/common-definitions.html#common-attributes
**PARAMETERS** **PARAMETERS**
@ -785,11 +825,11 @@ https://bazel.build/reference/be/common-definitions#common-attributes-binary
| Name | Description | Default Value | | Name | Description | Default Value |
| :------------- | :------------- | :------------- | | :------------- | :------------- | :------------- |
| <a id="utils.propagate_common_binary_rule_attributes-attrs"></a>attrs | Dict of parameters to filter | none | | <a id="utils.propagate_well_known_tags-tags"></a>tags | List of tags to filter | `[]` |
**RETURNS** **RETURNS**
The dict of parameters, containing only common binary attributes List of tags that only contains the well known set
<a id="utils.to_label"></a> <a id="utils.to_label"></a>
@ -814,35 +854,3 @@ Converts a string to a Label. If Label is supplied, the same label is returned.
a Label a Label
<a id="utils.consistent_label_str"></a>
## utils.consistent_label_str
<pre>
utils.consistent_label_str(<a href="#utils.consistent_label_str-ctx">ctx</a>, <a href="#utils.consistent_label_str-label">label</a>)
</pre>
Generate a consistent label string for all Bazel versions.
Starting in Bazel 6, the workspace name is empty for the local workspace and there's no other
way to determine it. This behavior differs from Bazel 5 where the local workspace name was fully
qualified in str(label).
This utility function is meant for use in rules and requires the rule context to determine the
user's workspace name (`ctx.workspace_name`).
**PARAMETERS**
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="utils.consistent_label_str-ctx"></a>ctx | The rule context. | none |
| <a id="utils.consistent_label_str-label"></a>label | A Label. | none |
**RETURNS**
String representation of the label including the repository name if the label is from an
external repository. For labels in the user's repository the label will start with `@//`.

158
docs/write_source_files.md generated
View File

@ -1,77 +1,10 @@
<!-- Generated with Stardoc: http://skydoc.bazel.build --> <!-- Generated with Stardoc: http://skydoc.bazel.build -->
Public API for write_source_files write_source_files provides a workaround for the restriction that `bazel build` cannot write to the source tree.
<a id="WriteSourceFileInfo"></a> Read more about the philosophy of writing to the source tree: <https://blog.aspect.build/bazel-can-write-to-the-source-folder>
## WriteSourceFileInfo ## Usage
<pre>
WriteSourceFileInfo(<a href="#WriteSourceFileInfo-executable">executable</a>)
</pre>
Provider for write_source_file targets
**FIELDS**
| Name | Description |
| :------------- | :------------- |
| <a id="WriteSourceFileInfo-executable"></a>executable | Executable that updates the source files |
<a id="write_source_file"></a>
## write_source_file
<pre>
write_source_file(<a href="#write_source_file-name">name</a>, <a href="#write_source_file-in_file">in_file</a>, <a href="#write_source_file-out_file">out_file</a>, <a href="#write_source_file-executable">executable</a>, <a href="#write_source_file-additional_update_targets">additional_update_targets</a>,
<a href="#write_source_file-suggested_update_target">suggested_update_target</a>, <a href="#write_source_file-diff_test">diff_test</a>, <a href="#write_source_file-check_that_out_file_exists">check_that_out_file_exists</a>, <a href="#write_source_file-kwargs">kwargs</a>)
</pre>
Write a file or directory to the source tree.
By default, a `diff_test` target ("{name}_test") is generated that ensure the source tree file or directory to be written to
is up to date and the rule also checks that the source tree file or directory to be written to exists.
To disable the exists check and up-to-date test set `diff_test` to `False`.
**PARAMETERS**
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="write_source_file-name"></a>name | Name of the runnable target that creates or updates the source tree file or directory. | none |
| <a id="write_source_file-in_file"></a>in_file | File or directory to use as the desired content to write to <code>out_file</code>.<br><br>This is typically a file or directory output of another target. If <code>in_file</code> is a directory then entire directory contents are copied. | <code>None</code> |
| <a id="write_source_file-out_file"></a>out_file | The file or directory to write to in the source tree.<br><br>The output file or directory must be within the same containing Bazel package as this target if <code>check_that_out_file_exists</code> is <code>True</code>. See <code>check_that_out_file_exists</code> docstring for more info. | <code>None</code> |
| <a id="write_source_file-executable"></a>executable | Whether source tree file or files within the source tree directory written should be made executable. | <code>False</code> |
| <a id="write_source_file-additional_update_targets"></a>additional_update_targets | List of other <code>write_source_files</code> or <code>write_source_file</code> targets to call in the same run. | <code>[]</code> |
| <a id="write_source_file-suggested_update_target"></a>suggested_update_target | Label of the <code>write_source_files</code> or <code>write_source_file</code> target to suggest running when files are out of date. | <code>None</code> |
| <a id="write_source_file-diff_test"></a>diff_test | Test that the source tree file or directory exist and is up to date. | <code>True</code> |
| <a id="write_source_file-check_that_out_file_exists"></a>check_that_out_file_exists | Test that the output file exists and print a helpful error message if it doesn't.<br><br>If <code>True</code>, the output file or directory must be in the same containing Bazel package as the target since the underlying mechanism for this check is limited to files in the same Bazel package. | <code>True</code> |
| <a id="write_source_file-kwargs"></a>kwargs | Other common named parameters such as <code>tags</code> or <code>visibility</code> | none |
**RETURNS**
Name of the generated test target if requested, otherwise None.
<a id="write_source_files"></a>
## write_source_files
<pre>
write_source_files(<a href="#write_source_files-name">name</a>, <a href="#write_source_files-files">files</a>, <a href="#write_source_files-executable">executable</a>, <a href="#write_source_files-additional_update_targets">additional_update_targets</a>, <a href="#write_source_files-suggested_update_target">suggested_update_target</a>,
<a href="#write_source_files-diff_test">diff_test</a>, <a href="#write_source_files-check_that_out_file_exists">check_that_out_file_exists</a>, <a href="#write_source_files-kwargs">kwargs</a>)
</pre>
Write one or more files and/or directories to the source tree.
By default, `diff_test` targets are generated that ensure the source tree files and/or directories to be written to
are up to date and the rule also checks that all source tree files and/or directories to be written to exist.
To disable the exists check and up-to-date tests set `diff_test` to `False`.
Usage:
```starlark ```starlark
load("@aspect_bazel_lib//lib:write_source_files.bzl", "write_source_files") load("@aspect_bazel_lib//lib:write_source_files.bzl", "write_source_files")
@ -146,7 +79,76 @@ If you have many `write_source_files` targets that you want to update as a group
`write_source_files` in a macro that defaults `suggested_update_target` to the umbrella update target. `write_source_files` in a macro that defaults `suggested_update_target` to the umbrella update target.
NOTE: If you run formatters or linters on your codebase, it is advised that you exclude/ignore the outputs of this NOTE: If you run formatters or linters on your codebase, it is advised that you exclude/ignore the outputs of this
rule from those formatters/linters so as to avoid causing collisions and failing tests. rule from those formatters/linters so as to avoid causing collisions and failing tests.
<a id="WriteSourceFileInfo"></a>
## WriteSourceFileInfo
<pre>
WriteSourceFileInfo(<a href="#WriteSourceFileInfo-executable">executable</a>)
</pre>
Provider for write_source_file targets
**FIELDS**
| Name | Description |
| :------------- | :------------- |
| <a id="WriteSourceFileInfo-executable"></a>executable | Executable that updates the source files |
<a id="write_source_file"></a>
## write_source_file
<pre>
write_source_file(<a href="#write_source_file-name">name</a>, <a href="#write_source_file-in_file">in_file</a>, <a href="#write_source_file-out_file">out_file</a>, <a href="#write_source_file-executable">executable</a>, <a href="#write_source_file-additional_update_targets">additional_update_targets</a>,
<a href="#write_source_file-suggested_update_target">suggested_update_target</a>, <a href="#write_source_file-diff_test">diff_test</a>, <a href="#write_source_file-check_that_out_file_exists">check_that_out_file_exists</a>, <a href="#write_source_file-kwargs">kwargs</a>)
</pre>
Write a file or directory to the source tree.
By default, a `diff_test` target ("{name}_test") is generated that ensure the source tree file or directory to be written to
is up to date and the rule also checks that the source tree file or directory to be written to exists.
To disable the exists check and up-to-date test set `diff_test` to `False`.
**PARAMETERS**
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="write_source_file-name"></a>name | Name of the runnable target that creates or updates the source tree file or directory. | none |
| <a id="write_source_file-in_file"></a>in_file | File or directory to use as the desired content to write to `out_file`.<br><br>This is typically a file or directory output of another target. If `in_file` is a directory then entire directory contents are copied. | `None` |
| <a id="write_source_file-out_file"></a>out_file | The file or directory to write to in the source tree.<br><br>The output file or directory must be within the same containing Bazel package as this target if `check_that_out_file_exists` is `True`. See `check_that_out_file_exists` docstring for more info. | `None` |
| <a id="write_source_file-executable"></a>executable | Whether source tree file or files within the source tree directory written should be made executable. | `False` |
| <a id="write_source_file-additional_update_targets"></a>additional_update_targets | List of other `write_source_files` or `write_source_file` targets to call in the same run. | `[]` |
| <a id="write_source_file-suggested_update_target"></a>suggested_update_target | Label of the `write_source_files` or `write_source_file` target to suggest running when files are out of date. | `None` |
| <a id="write_source_file-diff_test"></a>diff_test | Test that the source tree file or directory exist and is up to date. | `True` |
| <a id="write_source_file-check_that_out_file_exists"></a>check_that_out_file_exists | Test that the output file exists and print a helpful error message if it doesn't.<br><br>If `True`, the output file or directory must be in the same containing Bazel package as the target since the underlying mechanism for this check is limited to files in the same Bazel package. | `True` |
| <a id="write_source_file-kwargs"></a>kwargs | Other common named parameters such as `tags` or `visibility` | none |
**RETURNS**
Name of the generated test target if requested, otherwise None.
<a id="write_source_files"></a>
## write_source_files
<pre>
write_source_files(<a href="#write_source_files-name">name</a>, <a href="#write_source_files-files">files</a>, <a href="#write_source_files-executable">executable</a>, <a href="#write_source_files-additional_update_targets">additional_update_targets</a>, <a href="#write_source_files-suggested_update_target">suggested_update_target</a>,
<a href="#write_source_files-diff_test">diff_test</a>, <a href="#write_source_files-check_that_out_file_exists">check_that_out_file_exists</a>, <a href="#write_source_files-kwargs">kwargs</a>)
</pre>
Write one or more files and/or directories to the source tree.
By default, `diff_test` targets are generated that ensure the source tree files and/or directories to be written to
are up to date and the rule also checks that all source tree files and/or directories to be written to exist.
To disable the exists check and up-to-date tests set `diff_test` to `False`.
**PARAMETERS** **PARAMETERS**
@ -155,12 +157,12 @@ NOTE: If you run formatters or linters on your codebase, it is advised that you
| Name | Description | Default Value | | Name | Description | Default Value |
| :------------- | :------------- | :------------- | | :------------- | :------------- | :------------- |
| <a id="write_source_files-name"></a>name | Name of the runnable target that creates or updates the source tree files and/or directories. | none | | <a id="write_source_files-name"></a>name | Name of the runnable target that creates or updates the source tree files and/or directories. | none |
| <a id="write_source_files-files"></a>files | A dict where the keys are files or directories in the source tree to write to and the values are labels pointing to the desired content, typically file or directory outputs of other targets.<br><br>Destination files and directories must be within the same containing Bazel package as this target if <code>check_that_out_file_exists</code> is True. See <code>check_that_out_file_exists</code> docstring for more info. | <code>{}</code> | | <a id="write_source_files-files"></a>files | A dict where the keys are files or directories in the source tree to write to and the values are labels pointing to the desired content, typically file or directory outputs of other targets.<br><br>Destination files and directories must be within the same containing Bazel package as this target if `check_that_out_file_exists` is True. See `check_that_out_file_exists` docstring for more info. | `{}` |
| <a id="write_source_files-executable"></a>executable | Whether source tree files written should be made executable.<br><br>This applies to all source tree files written by this target. This attribute is not propagated to <code>additional_update_targets</code>.<br><br>To set different executable permissions on different source tree files use multiple <code>write_source_files</code> targets. | <code>False</code> | | <a id="write_source_files-executable"></a>executable | Whether source tree files written should be made executable.<br><br>This applies to all source tree files written by this target. This attribute is not propagated to `additional_update_targets`.<br><br>To set different executable permissions on different source tree files use multiple `write_source_files` targets. | `False` |
| <a id="write_source_files-additional_update_targets"></a>additional_update_targets | List of other <code>write_source_files</code> or <code>write_source_file</code> targets to call in the same run. | <code>[]</code> | | <a id="write_source_files-additional_update_targets"></a>additional_update_targets | List of other `write_source_files` or `write_source_file` targets to call in the same run. | `[]` |
| <a id="write_source_files-suggested_update_target"></a>suggested_update_target | Label of the <code>write_source_files</code> or <code>write_source_file</code> target to suggest running when files are out of date. | <code>None</code> | | <a id="write_source_files-suggested_update_target"></a>suggested_update_target | Label of the `write_source_files` or `write_source_file` target to suggest running when files are out of date. | `None` |
| <a id="write_source_files-diff_test"></a>diff_test | Test that the source tree files and/or directories exist and are up to date. | <code>True</code> | | <a id="write_source_files-diff_test"></a>diff_test | Test that the source tree files and/or directories exist and are up to date. | `True` |
| <a id="write_source_files-check_that_out_file_exists"></a>check_that_out_file_exists | Test that each output file exists and print a helpful error message if it doesn't.<br><br>If <code>True</code>, destination files and directories must be in the same containing Bazel package as the target since the underlying mechanism for this check is limited to files in the same Bazel package. | <code>True</code> | | <a id="write_source_files-check_that_out_file_exists"></a>check_that_out_file_exists | Test that each output file exists and print a helpful error message if it doesn't.<br><br>If `True`, destination files and directories must be in the same containing Bazel package as the target since the underlying mechanism for this check is limited to files in the same Bazel package. | `True` |
| <a id="write_source_files-kwargs"></a>kwargs | Other common named parameters such as <code>tags</code> or <code>visibility</code> | none | | <a id="write_source_files-kwargs"></a>kwargs | Other common named parameters such as `tags` or `visibility` | none |

39
docs/yq.md generated
View File

@ -1,20 +1,13 @@
<!-- Generated with Stardoc: http://skydoc.bazel.build --> <!-- Generated with Stardoc: http://skydoc.bazel.build -->
Public API for yq Wrapper rule around the `yq` tool
<a id="yq"></a> From the documentation at https://mikefarah.gitbook.io/yq:
## yq > yq is a a lightweight and portable command-line YAML processor.
> yq uses jq like syntax but works with yaml files as well as json.
<pre> ## Usage examples
yq(<a href="#yq-name">name</a>, <a href="#yq-srcs">srcs</a>, <a href="#yq-expression">expression</a>, <a href="#yq-args">args</a>, <a href="#yq-outs">outs</a>, <a href="#yq-kwargs">kwargs</a>)
</pre>
Invoke yq with an expression on a set of input files.
For yq documentation, see https://mikefarah.gitbook.io/yq.
Usage examples:
```starlark ```starlark
load("@aspect_bazel_lib//lib:yq.bzl", "yq") load("@aspect_bazel_lib//lib:yq.bzl", "yq")
@ -83,7 +76,7 @@ genrule(
name = "generate", name = "generate",
srcs = ["farm.yaml"], srcs = ["farm.yaml"],
outs = ["genrule_output.yaml"], outs = ["genrule_output.yaml"],
cmd = "$(YQ_BIN) '.moo = "cow"' $(location farm.yaml) &gt; $@", cmd = "$(YQ_BIN) '.moo = "cow"' $(location farm.yaml) > $@",
toolchains = ["@yq_toolchains//:resolved_toolchain"], toolchains = ["@yq_toolchains//:resolved_toolchain"],
) )
``` ```
@ -96,11 +89,21 @@ yq(
expression = "|".join([ expression = "|".join([
"load(strenv(STAMP)) as $stamp", "load(strenv(STAMP)) as $stamp",
# Provide a default using the "alternative operator" in case $stamp is empty dict. # Provide a default using the "alternative operator" in case $stamp is empty dict.
".version = ($stamp.BUILD_EMBED_LABEL // "&lt;unstamped&gt;")", ".version = ($stamp.BUILD_EMBED_LABEL // "<unstamped>")",
]), ]),
) )
``` ```
<a id="yq"></a>
## yq
<pre>
yq(<a href="#yq-name">name</a>, <a href="#yq-srcs">srcs</a>, <a href="#yq-expression">expression</a>, <a href="#yq-args">args</a>, <a href="#yq-outs">outs</a>, <a href="#yq-kwargs">kwargs</a>)
</pre>
Invoke yq with an expression on a set of input files.
yq is capable of parsing and outputting to other formats. See their [docs](https://mikefarah.gitbook.io/yq) for more examples. yq is capable of parsing and outputting to other formats. See their [docs](https://mikefarah.gitbook.io/yq) for more examples.
@ -111,9 +114,9 @@ yq is capable of parsing and outputting to other formats. See their [docs](https
| :------------- | :------------- | :------------- | | :------------- | :------------- | :------------- |
| <a id="yq-name"></a>name | Name of the rule | none | | <a id="yq-name"></a>name | Name of the rule | none |
| <a id="yq-srcs"></a>srcs | List of input file labels | none | | <a id="yq-srcs"></a>srcs | List of input file labels | none |
| <a id="yq-expression"></a>expression | yq expression (https://mikefarah.gitbook.io/yq/commands/evaluate). Defaults to the identity expression ".". Subject to stamp variable replacements, see [Stamping](./stamping.md). When stamping is enabled, an environment variable named "STAMP" will be available in the expression.<br><br>Be careful to write the filter so that it handles unstamped builds, as in the example above. | <code>"."</code> | | <a id="yq-expression"></a>expression | yq expression (https://mikefarah.gitbook.io/yq/commands/evaluate).<br><br>Defaults to the identity expression ".". Subject to stamp variable replacements, see [Stamping](./stamping.md). When stamping is enabled, an environment variable named "STAMP" will be available in the expression.<br><br>Be careful to write the filter so that it handles unstamped builds, as in the example above. | `"."` |
| <a id="yq-args"></a>args | Additional args to pass to yq. Note that you do not need to pass _eval_ or _eval-all_ as this is handled automatically based on the number <code>srcs</code>. Passing the output format or the parse format is optional as these can be guessed based on the file extensions in <code>srcs</code> and <code>outs</code>. | <code>[]</code> | | <a id="yq-args"></a>args | Additional args to pass to yq.<br><br>Note that you do not need to pass _eval_ or _eval-all_ as this is handled automatically based on the number `srcs`. Passing the output format or the parse format is optional as these can be guessed based on the file extensions in `srcs` and `outs`. | `[]` |
| <a id="yq-outs"></a>outs | Name of the output files. Defaults to a single output with the name plus a ".yaml" extension, or the extension corresponding to a passed output argument (e.g., "-o=json"). For split operations you must declare all outputs as the name of the output files depends on the expression. | <code>None</code> | | <a id="yq-outs"></a>outs | Name of the output files.<br><br>Defaults to a single output with the name plus a ".yaml" extension, or the extension corresponding to a passed output argument (e.g., "-o=json"). For split operations you must declare all outputs as the name of the output files depends on the expression. | `None` |
| <a id="yq-kwargs"></a>kwargs | Other common named parameters such as <code>tags</code> or <code>visibility</code> | none | | <a id="yq-kwargs"></a>kwargs | Other common named parameters such as `tags` or `visibility` | none |

7
internal_deps.bzl
View File

@ -36,11 +36,8 @@ def bazel_lib_internal_deps():
http_archive( http_archive(
name = "io_bazel_stardoc", name = "io_bazel_stardoc",
sha256 = "ec57139e466faae563f2fc39609da4948a479bb51b6d67aedd7d9b1b8059c433", sha256 = "62bd2e60216b7a6fec3ac79341aa201e0956477e7c8f6ccc286f279ad1d96432",
urls = [ urls = ["https://github.com/bazelbuild/stardoc/releases/download/0.6.2/stardoc-0.6.2.tar.gz"],
"https://mirror.bazel.build/github.com/bazelbuild/stardoc/releases/download/0.5.4/stardoc-0.5.4.tar.gz",
"https://github.com/bazelbuild/stardoc/releases/download/0.5.4/stardoc-0.5.4.tar.gz",
],
) )
http_archive( http_archive(

5
lib/base64.bzl
View File

@ -1,4 +1,7 @@
"Public API" """Utility functions for encoding and decoding strings with base64.
See https://en.wikipedia.org/wiki/Base64.
"""
load("//lib/private:base64.bzl", _decode = "decode", _encode = "encode") load("//lib/private:base64.bzl", _decode = "decode", _encode = "encode")

29
lib/bazelrc_presets.bzl
View File

@ -1,4 +1,7 @@
"Aspect bazelrc presets; see https://docs.aspect.build/guides/bazelrc" """'Presets' for bazelrc
See https://docs.aspect.build/guides/bazelrc
"""
load("@aspect_bazel_lib//lib:write_source_files.bzl", "write_source_files") load("@aspect_bazel_lib//lib:write_source_files.bzl", "write_source_files")
@ -23,33 +26,11 @@ def write_aspect_bazelrc_presets(
rule under the hood to keep your presets up-to-date. rule under the hood to keep your presets up-to-date.
By default all presets are vendored but this list can be customized using By default all presets are vendored but this list can be customized using
the 'presets' attribute. the `presets` attribute.
See https://docs.aspect.build/guides/bazelrc for more info.
Args: Args:
name: a unique name for this target name: a unique name for this target
presets: a list of preset names to keep up-to-date presets: a list of preset names to keep up-to-date
For example,
```
write_aspect_bazelrc_presets(
name = "update_aspect_bazelrc_presets",
presets = [
"bazel6",
"bazel7",
"ci",
"convenience",
"correctness",
"debug",
"javascript",
"performance",
],
)
```
**kwargs: Additional arguments to pass to `write_source_files` **kwargs: Additional arguments to pass to `write_source_files`
""" """

10
lib/copy_file.bzl
View File

@ -19,14 +19,14 @@
"""A rule that copies a file to another place. """A rule that copies a file to another place.
native.genrule() is sometimes used to copy files (often wishing to rename them). `native.genrule()` is sometimes used to copy files (often wishing to rename them).
The 'copy_file' rule does this with a simpler interface than genrule. The `copy_file` rule does this with a simpler interface than genrule.
The rule uses a Bash command on Linux/macOS/non-Windows, and a cmd.exe command The rule uses a Bash command on Linux/macOS/non-Windows, and a `cmd.exe` command
on Windows (no Bash is required). on Windows (no Bash is required).
This fork of bazel-skylib's copy_file adds DirectoryPathInfo support and allows multiple This fork of bazel-skylib's copy_file adds `DirectoryPathInfo` support and allows multiple
copy_file in the same package. `copy_file` rules in the same package.
""" """
load( load(

2
lib/diff_test.bzl
View File

@ -19,6 +19,8 @@ but also supports comparing directories.
The rule uses a Bash command (diff) on Linux/macOS/non-Windows, and a cmd.exe The rule uses a Bash command (diff) on Linux/macOS/non-Windows, and a cmd.exe
command (fc.exe) on Windows (no Bash is required). command (fc.exe) on Windows (no Bash is required).
See also: [rules_diff](https://gitlab.arm.com/bazel/rules_diff)
""" """
load( load(

225
lib/jq.bzl
View File

@ -1,4 +1,124 @@
"""Public API for jq""" """Wrapper rule around the popular `jq` utility.
For jq documentation, see https://stedolan.github.io/jq/.
## Usage examples
```starlark
load("@aspect_bazel_lib//lib:jq.bzl", "jq")
```
Create a new file `bazel-out/.../no_srcs.json` containing some JSON data:
```starlark
jq(
name = "no_srcs",
srcs = [],
filter = ".name = \"Alice\"",
)
```
Remove a field from `package.json`:
> The output path `bazel-out/.../package.json` matches the path of the source file,
> which means you must refer to the label `:no_dev_deps` to reference the output,
> since Bazel doesn't provide a label for an output file that collides with an input file.
```starlark
jq(
name = "no_dev_deps",
srcs = ["package.json"],
filter = "del(.devDependencies)",
)
```
Merge data from `bar.json` on top of `foo.json`, producing `foobar.json`:
```starlark
jq(
name = "merged",
srcs = ["foo.json", "bar.json"],
filter = ".[0] * .[1]",
args = ["--slurp"],
out = "foobar.json",
)
```
Long filters can be split over several lines with comments:
```starlark
jq(
name = "complex",
srcs = ["a.json", "b.json"],
filter = \"\"\"
.[0] as $a
# Take select fields from b.json
| (.[1] | {foo, bar, tags}) as $b
# Merge b onto a
| ($a * $b)
# Combine 'tags' array from both
| .tags = ($a.tags + $b.tags)
# Add new field
+ {\\\"aspect_is_cool\\\": true}
\"\"\",
args = ["--slurp"],
)
```
Load filter from a file `filter.jq`, making it easier to edit complex filters:
```starlark
jq(
name = "merged",
srcs = ["foo.json", "bar.json"],
filter_file = "filter.jq",
args = ["--slurp"],
out = "foobar.json",
)
```
Convert [genquery](https://bazel.build/reference/be/general#genquery) output to JSON.
```starlark
genquery(
name = "deps",
expression = "deps(//some:target)",
scope = ["//some:target"],
)
jq(
name = "deps_json",
srcs = [":deps"],
args = [
"--raw-input",
"--slurp",
],
filter = "{ deps: split(\"\\n\") | map(select(. | length > 0)) }",
)
```
When Bazel is run with `--stamp`, replace some properties with version control info:
```starlark
jq(
name = "stamped",
srcs = ["package.json"],
filter = "|".join([
# Don't directly reference $STAMP as it's only set when stamping
# This 'as' syntax results in $stamp being null in unstamped builds.
"$ARGS.named.STAMP as $stamp",
# Provide a default using the "alternative operator" in case $stamp is null.
".version = ($stamp[0].BUILD_EMBED_LABEL // \"<unstamped>\")",
]),
)
```
jq is exposed as a "Make variable", so you could use it directly from a `genrule` by referencing the toolchain.
```starlark
genrule(
name = "case_genrule",
srcs = ["a.json"],
outs = ["genrule_output.json"],
cmd = "$(JQ_BIN) '.' $(location a.json) > $@",
toolchains = ["@jq_toolchains//:resolved_toolchain"],
)
```
"""
load("//lib/private:jq.bzl", _jq_lib = "jq_lib") load("//lib/private:jq.bzl", _jq_lib = "jq_lib")
@ -11,109 +131,6 @@ _jq_rule = rule(
def jq(name, srcs, filter = None, filter_file = None, args = [], out = None, data = [], expand_args = False, **kwargs): def jq(name, srcs, filter = None, filter_file = None, args = [], out = None, data = [], expand_args = False, **kwargs):
"""Invoke jq with a filter on a set of json input files. """Invoke jq with a filter on a set of json input files.
For jq documentation, see https://stedolan.github.io/jq/.
Usage examples:
```starlark
load("@aspect_bazel_lib//lib:jq.bzl", "jq")
# Create a new file bazel-out/.../no_srcs.json
jq(
name = "no_srcs",
srcs = [],
filter = ".name = \"Alice\"",
)
# Remove fields from package.json.
# Writes to bazel-out/.../package.json which means you must refer to this as ":no_dev_deps"
# since Bazel doesn't allow a label for the output file that collides with the input file.
jq(
name = "no_dev_deps",
srcs = ["package.json"],
filter = "del(.devDependencies)",
)
# Merge bar.json on top of foo.json, producing foobar.json
jq(
name = "merged",
srcs = ["foo.json", "bar.json"],
filter = ".[0] * .[1]",
args = ["--slurp"],
out = "foobar.json",
)
# Long filters can be split over several lines with comments
jq(
name = "complex",
srcs = ["a.json", "b.json"],
filter = \"\"\"
.[0] as $a
# Take select fields from b.json
| (.[1] | {foo, bar, tags}) as $b
# Merge b onto a
| ($a * $b)
# Combine 'tags' array from both
| .tags = ($a.tags + $b.tags)
# Add new field
+ {\\\"aspect_is_cool\\\": true}
\"\"\",
args = ["--slurp"],
)
# Load filter from a file
jq(
name = "merged",
srcs = ["foo.json", "bar.json"],
filter_file = "filter.txt",
args = ["--slurp"],
out = "foobar.json",
)
# Convert genquery output to json
genquery(
name = "deps",
expression = "deps(//some:target)",
scope = ["//some:target"],
)
jq(
name = "deps_json",
srcs = [":deps"],
args = [
"--raw-input",
"--slurp",
],
filter = "{ deps: split(\"\\n\") | map(select(. | length > 0)) }",
)
# With --stamp, causes properties to be replaced by version control info.
jq(
name = "stamped",
srcs = ["package.json"],
filter = "|".join([
# Don't directly reference $STAMP as it's only set when stamping
# This 'as' syntax results in $stamp being null in unstamped builds.
"$ARGS.named.STAMP as $stamp",
# Provide a default using the "alternative operator" in case $stamp is null.
".version = ($stamp[0].BUILD_EMBED_LABEL // \"<unstamped>\")",
]),
)
```
You could also use it directly from a `genrule` by referencing the toolchain, and the `JQ_BIN`
"Make variable" it exposes:
```
genrule(
name = "case_genrule",
srcs = ["a.json"],
outs = ["genrule_output.json"],
cmd = "$(JQ_BIN) '.' $(location a.json) > $@",
toolchains = ["@jq_toolchains//:resolved_toolchain"],
)
```
Args: Args:
name: Name of the rule name: Name of the rule
srcs: List of input files. May be empty. srcs: List of input files. May be empty.

4
lib/output_files.bzl
View File

@ -1,4 +1,6 @@
"""A rule that provides file(s) specific via DefaultInfo from a given target's DefaultInfo or OutputGroupInfo """A rule that provides file(s) specific via DefaultInfo from a given target's DefaultInfo or OutputGroupInfo.
See also [select_file](https://github.com/bazelbuild/bazel-skylib/blob/main/docs/select_file_doc.md) from bazel-skylib.
""" """
load( load(

2
lib/paths.bzl
View File

@ -1,4 +1,4 @@
"Public API" "Utilities for working with file paths."
load("//lib/private:paths.bzl", "paths") load("//lib/private:paths.bzl", "paths")

10
lib/private/base64.bzl
View File

@ -9,12 +9,10 @@ the subset of python available in Starlark.
load(":strings.bzl", "chr", "ord") load(":strings.bzl", "chr", "ord")
def decode(data): def decode(data):
"""Decode a Base64 encoded string. """Decode a base64 encoded string.
See https://en.wikipedia.org/wiki/Base64.
Args: Args:
data: base64 encoded string data: base64-encoded string
Returns: Returns:
A string containing the decoded data A string containing the decoded data
@ -40,13 +38,11 @@ def decode(data):
def encode(data): def encode(data):
"""Base64 encode a string. """Base64 encode a string.
See https://en.wikipedia.org/wiki/Base64.
Args: Args:
data: string to encode data: string to encode
Returns: Returns:
The base64 encoded string The base64-encoded string
""" """
padding = 0 padding = 0
if len(data) % 3 != 0: if len(data) % 3 != 0:

12
lib/utils.bzl
View File

@ -1,4 +1,14 @@
"Public API" """General-purpose Starlark utility functions
## Usage example
```starlark
load("@aspect_bazel_lib//lib:utils.bzl", "utils")
out_label = utils.to_label(out_file)
```
"""
load("//lib/private:utils.bzl", _utils = "utils") load("//lib/private:utils.bzl", _utils = "utils")

160
lib/write_source_files.bzl
View File

@ -1,4 +1,85 @@
"Public API for write_source_files" """write_source_files provides a workaround for the restriction that `bazel build` cannot write to the source tree.
Read more about the philosophy of writing to the source tree: <https://blog.aspect.build/bazel-can-write-to-the-source-folder>
## Usage
```starlark
load("@aspect_bazel_lib//lib:write_source_files.bzl", "write_source_files")
write_source_files(
name = "write_foobar",
files = {
"foobar.json": "//some/generated:file",
},
)
```
To update the source file, run:
```bash
bazel run //:write_foobar
```
The generated `diff_test` will fail if the file is out of date and print out instructions on
how to update it.
If the file does not exist, Bazel will fail at analysis time and print out instructions on
how to create it.
You can declare a tree of generated source file targets:
```starlark
load("@aspect_bazel_lib//lib:write_source_files.bzl", "write_source_files")
write_source_files(
name = "write_all",
additional_update_targets = [
# Other write_source_files targets to run when this target is run
"//a/b/c:write_foo",
"//a/b:write_bar",
]
)
```
And update them with a single run:
```bash
bazel run //:write_all
```
When a file is out of date, you can leave a suggestion to run a target further up in the tree by specifying `suggested_update_target`.
For example,
```starlark
write_source_files(
name = "write_foo",
files = {
"foo.json": ":generated-foo",
},
suggested_update_target = "//:write_all"
)
```
A test failure from `foo.json` being out of date will yield the following message:
```
//a/b:c:foo.json is out of date. To update this and other generated files, run:
bazel run //:write_all
To update *only* this file, run:
bazel run //a/b/c:write_foo
```
If you have many `write_source_files` targets that you want to update as a group, we recommend wrapping
`write_source_files` in a macro that defaults `suggested_update_target` to the umbrella update target.
NOTE: If you run formatters or linters on your codebase, it is advised that you exclude/ignore the outputs of this
rule from those formatters/linters so as to avoid causing collisions and failing tests.
"""
load( load(
"//lib/private:write_source_file.bzl", "//lib/private:write_source_file.bzl",
@ -23,83 +104,6 @@ def write_source_files(
are up to date and the rule also checks that all source tree files and/or directories to be written to exist. are up to date and the rule also checks that all source tree files and/or directories to be written to exist.
To disable the exists check and up-to-date tests set `diff_test` to `False`. To disable the exists check and up-to-date tests set `diff_test` to `False`.
Usage:
```starlark
load("@aspect_bazel_lib//lib:write_source_files.bzl", "write_source_files")
write_source_files(
name = "write_foobar",
files = {
"foobar.json": "//some/generated:file",
},
)
```
To update the source file, run:
```bash
bazel run //:write_foobar
```
The generated `diff_test` will fail if the file is out of date and print out instructions on
how to update it.
If the file does not exist, Bazel will fail at analysis time and print out instructions on
how to create it.
You can declare a tree of generated source file targets:
```starlark
load("@aspect_bazel_lib//lib:write_source_files.bzl", "write_source_files")
write_source_files(
name = "write_all",
additional_update_targets = [
# Other write_source_files targets to run when this target is run
"//a/b/c:write_foo",
"//a/b:write_bar",
]
)
```
And update them with a single run:
```bash
bazel run //:write_all
```
When a file is out of date, you can leave a suggestion to run a target further up in the tree by specifying `suggested_update_target`.
For example,
```starlark
write_source_files(
name = "write_foo",
files = {
"foo.json": ":generated-foo",
},
suggested_update_target = "//:write_all"
)
```
A test failure from `foo.json` being out of date will yield the following message:
```
//a/b:c:foo.json is out of date. To update this and other generated files, run:
bazel run //:write_all
To update *only* this file, run:
bazel run //a/b/c:write_foo
```
If you have many `write_source_files` targets that you want to update as a group, we recommend wrapping
`write_source_files` in a macro that defaults `suggested_update_target` to the umbrella update target.
NOTE: If you run formatters or linters on your codebase, it is advised that you exclude/ignore the outputs of this
rule from those formatters/linters so as to avoid causing collisions and failing tests.
Args: Args:
name: Name of the runnable target that creates or updates the source tree files and/or directories. name: Name of the runnable target that creates or updates the source tree files and/or directories.

198
lib/yq.bzl
View File

@ -1,4 +1,97 @@
"""Public API for yq""" """Wrapper rule around the `yq` tool
From the documentation at https://mikefarah.gitbook.io/yq:
> yq is a a lightweight and portable command-line YAML processor.
> yq uses jq like syntax but works with yaml files as well as json.
## Usage examples
```starlark
load("@aspect_bazel_lib//lib:yq.bzl", "yq")
```
```starlark
# Remove fields
yq(
name = "safe-config",
srcs = ["config.yaml"],
expression = "del(.credentials)",
)
```
```starlark
# Merge two yaml documents
yq(
name = "ab",
srcs = [
"a.yaml",
"b.yaml",
],
expression = ". as $item ireduce ({}; . * $item )",
)
```
```starlark
# Split a yaml file into several files
yq(
name = "split",
srcs = ["multidoc.yaml"],
outs = [
"first.yml",
"second.yml",
],
args = [
"-s '.a'", # Split expression
"--no-doc", # Exclude document separator --
],
)
```
```starlark
# Convert a yaml file to json
yq(
name = "convert-to-json",
srcs = ["foo.yaml"],
args = ["-o=json"],
outs = ["foo.json"],
)
```
```starlark
# Convert a json file to yaml
yq(
name = "convert-to-yaml",
srcs = ["bar.json"],
args = ["-P"],
outs = ["bar.yaml"],
)
```
```starlark
# Call yq in a genrule
genrule(
name = "generate",
srcs = ["farm.yaml"],
outs = ["genrule_output.yaml"],
cmd = "$(YQ_BIN) '.moo = \"cow\"' $(location farm.yaml) > $@",
toolchains = ["@yq_toolchains//:resolved_toolchain"],
)
```
```starlark
# With --stamp, causes properties to be replaced by version control info.
yq(
name = "stamped",
srcs = ["package.yaml"],
expression = "|".join([
"load(strenv(STAMP)) as $stamp",
# Provide a default using the "alternative operator" in case $stamp is empty dict.
".version = ($stamp.BUILD_EMBED_LABEL // "<unstamped>")",
]),
)
```
"""
load("//lib/private:yq.bzl", _is_split_operation = "is_split_operation", _yq_lib = "yq_lib") load("//lib/private:yq.bzl", _is_split_operation = "is_split_operation", _yq_lib = "yq_lib")
@ -11,112 +104,31 @@ _yq_rule = rule(
def yq(name, srcs, expression = ".", args = [], outs = None, **kwargs): def yq(name, srcs, expression = ".", args = [], outs = None, **kwargs):
"""Invoke yq with an expression on a set of input files. """Invoke yq with an expression on a set of input files.
For yq documentation, see https://mikefarah.gitbook.io/yq.
Usage examples:
```starlark
load("@aspect_bazel_lib//lib:yq.bzl", "yq")
```
```starlark
# Remove fields
yq(
name = "safe-config",
srcs = ["config.yaml"],
expression = "del(.credentials)",
)
```
```starlark
# Merge two yaml documents
yq(
name = "ab",
srcs = [
"a.yaml",
"b.yaml",
],
expression = ". as $item ireduce ({}; . * $item )",
)
```
```starlark
# Split a yaml file into several files
yq(
name = "split",
srcs = ["multidoc.yaml"],
outs = [
"first.yml",
"second.yml",
],
args = [
"-s '.a'", # Split expression
"--no-doc", # Exclude document separator --
],
)
```
```starlark
# Convert a yaml file to json
yq(
name = "convert-to-json",
srcs = ["foo.yaml"],
args = ["-o=json"],
outs = ["foo.json"],
)
```
```starlark
# Convert a json file to yaml
yq(
name = "convert-to-yaml",
srcs = ["bar.json"],
args = ["-P"],
outs = ["bar.yaml"],
)
```
```starlark
# Call yq in a genrule
genrule(
name = "generate",
srcs = ["farm.yaml"],
outs = ["genrule_output.yaml"],
cmd = "$(YQ_BIN) '.moo = \"cow\"' $(location farm.yaml) > $@",
toolchains = ["@yq_toolchains//:resolved_toolchain"],
)
```
```starlark
# With --stamp, causes properties to be replaced by version control info.
yq(
name = "stamped",
srcs = ["package.yaml"],
expression = "|".join([
"load(strenv(STAMP)) as $stamp",
# Provide a default using the "alternative operator" in case $stamp is empty dict.
".version = ($stamp.BUILD_EMBED_LABEL // "<unstamped>")",
]),
)
```
yq is capable of parsing and outputting to other formats. See their [docs](https://mikefarah.gitbook.io/yq) for more examples. yq is capable of parsing and outputting to other formats. See their [docs](https://mikefarah.gitbook.io/yq) for more examples.
Args: Args:
name: Name of the rule name: Name of the rule
srcs: List of input file labels srcs: List of input file labels
expression: yq expression (https://mikefarah.gitbook.io/yq/commands/evaluate). Defaults to the identity expression: yq expression (https://mikefarah.gitbook.io/yq/commands/evaluate).
Defaults to the identity
expression ".". Subject to stamp variable replacements, see [Stamping](./stamping.md). expression ".". Subject to stamp variable replacements, see [Stamping](./stamping.md).
When stamping is enabled, an environment variable named "STAMP" will be available in the expression. When stamping is enabled, an environment variable named "STAMP" will be available in the expression.
Be careful to write the filter so that it handles unstamped builds, as in the example above. Be careful to write the filter so that it handles unstamped builds, as in the example above.
args: Additional args to pass to yq. Note that you do not need to pass _eval_ or _eval-all_ as this args: Additional args to pass to yq.
Note that you do not need to pass _eval_ or _eval-all_ as this
is handled automatically based on the number `srcs`. Passing the output format or the parse format is handled automatically based on the number `srcs`. Passing the output format or the parse format
is optional as these can be guessed based on the file extensions in `srcs` and `outs`. is optional as these can be guessed based on the file extensions in `srcs` and `outs`.
outs: Name of the output files. Defaults to a single output with the name plus a ".yaml" extension, or
outs: Name of the output files.
Defaults to a single output with the name plus a ".yaml" extension, or
the extension corresponding to a passed output argument (e.g., "-o=json"). For split operations you the extension corresponding to a passed output argument (e.g., "-o=json"). For split operations you
must declare all outputs as the name of the output files depends on the expression. must declare all outputs as the name of the output files depends on the expression.
**kwargs: Other common named parameters such as `tags` or `visibility` **kwargs: Other common named parameters such as `tags` or `visibility`
""" """
args = args[:] args = args[:]