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

Prepare release 1.6.0 (#496) 

And take the opportunity to reformat docs using a more modern Stardoc release
This commit is contained in:
Alexandre Rostovtsev 2024-04-24 17:40:06 -04:00 committed by GitHub
parent 1969278310
commit 99ffbbf8a4
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
29 changed files with 786 additions and 775 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
CHANGELOG.md
View File

@ -1,3 +1,19 @@
Release 1.6.0
## What's Changed
* Add helper functions for module extensions as `modules` by @fmeum in https://github.com/bazelbuild/bazel-skylib/pull/457
* Make `out` on `native_binary` optional by @tpudlik in https://github.com/bazelbuild/bazel-skylib/pull/474
* Remove outdated rules_cc dependency @cpsauer in https://github.com/bazelbuild/bazel-skylib/pull/476
* Add toolchains argument to unittests.make by @jylinv0 in https://github.com/bazelbuild/bazel-skylib/pull/483
* Allow `bzl_library` to depend on non-`bzl_library` targets by @Wyverald in https://github.com/bazelbuild/bazel-skylib/pull/495
## New Contributors
* @jylinv0 made their first contribution in https://github.com/bazelbuild/bazel-skylib/pull/483
* @tpudlik made their first contribution in https://github.com/bazelbuild/bazel-skylib/pull/474
**Full Changelog**: https://github.com/bazelbuild/bazel-skylib/compare/1.5.0...1.6.0
Release 1.5.0
## What's Changed

4
MODULE.bazel
View File

@ -1,7 +1,7 @@
module(
name = "bazel_skylib",
# Keep in sync with version.bzl and @bazel_skylib_gazelle_plugin//:MODULE.bazel
version = "1.5.0",
version = "1.6.0",
compatibility_level = 1,
)
@ -15,7 +15,7 @@ bazel_dep(name = "platforms", version = "0.0.4")
### INTERNAL ONLY - lines after this are not included in the release packaging.
# Build-only / test-only dependencies
bazel_dep(name = "stardoc", version = "0.5.6", dev_dependency = True, repo_name = "io_bazel_stardoc")
bazel_dep(name = "stardoc", version = "0.6.2", dev_dependency = True, repo_name = "io_bazel_stardoc")
bazel_dep(name = "rules_pkg", version = "0.9.1", dev_dependency = True)
# Needed for bazelci and for building distribution tarballs.

22
WORKSPACE
View File

@ -27,10 +27,10 @@ bazel_skylib_gazelle_plugin_setup()
maybe(
http_archive,
name = "io_bazel_stardoc",
sha256 = "dfbc364aaec143df5e6c52faf1f1166775a5b4408243f445f44b661cfdc3134f",
sha256 = "62bd2e60216b7a6fec3ac79341aa201e0956477e7c8f6ccc286f279ad1d96432",
urls = [
"https://mirror.bazel.build/github.com/bazelbuild/stardoc/releases/download/0.5.6/stardoc-0.5.6.tar.gz",
"https://github.com/bazelbuild/stardoc/releases/download/0.5.6/stardoc-0.5.6.tar.gz",
"https://mirror.bazel.build/github.com/bazelbuild/stardoc/releases/download/0.6.2/stardoc-0.6.2.tar.gz",
"https://github.com/bazelbuild/stardoc/releases/download/0.6.2/stardoc-0.6.2.tar.gz",
],
)
@ -38,6 +38,22 @@ load("@io_bazel_stardoc//:setup.bzl", "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()
maybe(
http_archive,
name = "rules_pkg",

40
docs/analysis_test_doc.md
View File

@ -12,30 +12,30 @@ analysis_test(<a href="#analysis_test-name">name</a>, <a href="#analysis_test-ta
Test rule checking that other targets can be successfully analyzed.
This rule essentially verifies that all targets under `targets` would
generate no errors when analyzed with `bazel build [targets] --nobuild`.
Action success/failure for the targets and their transitive dependencies
are not verified. An analysis test simply ensures that each target in the transitive
dependencies propagate providers appropriately and register actions for their outputs
appropriately.
This rule essentially verifies that all targets under `targets` would
generate no errors when analyzed with `bazel build [targets] --nobuild`.
Action success/failure for the targets and their transitive dependencies
are not verified. An analysis test simply ensures that each target in the transitive
dependencies propagate providers appropriately and register actions for their outputs
appropriately.
NOTE: If the targets fail to analyze, instead of the analysis_test failing, the analysis_test
will fail to build. Ideally, it would instead result in a test failure. This is a current
infrastructure limitation that may be fixed in the future.
NOTE: If the targets fail to analyze, instead of the analysis_test failing, the analysis_test
will fail to build. Ideally, it would instead result in a test failure. This is a current
infrastructure limitation that may be fixed in the future.
Typical usage:
Typical usage:
load("@bazel_skylib//rules:analysis_test.bzl", "analysis_test")
analysis_test(
name = "my_analysis_test",
targets = [
"//some/package:rule",
],
)
load("@bazel_skylib//rules:analysis_test.bzl", "analysis_test")
analysis_test(
name = "my_analysis_test",
targets = [
"//some/package:rule",
],
)
Args:
name: The name of the test rule.
targets: A list of targets to ensure build.
Args:
name: The name of the test rule.
targets: A list of targets to ensure build.
**ATTRIBUTES**

5
docs/bzl_library.md
View File

@ -56,15 +56,14 @@ Example:
)
```
**ATTRIBUTES**
| Name | Description | Type | Mandatory | Default |
| :------------- | :------------- | :------------- | :------------- | :------------- |
| <a id="bzl_library-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | |
| <a id="bzl_library-deps"></a>deps | List of other <code>bzl_library</code> or <code>filegroup</code> targets that are required by the Starlark files listed in <code>srcs</code>. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | <code>[]</code> |
| <a id="bzl_library-srcs"></a>srcs | List of <code>.bzl</code> and <code>.scl</code> files that are processed to create this target. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | <code>[]</code> |
| <a id="bzl_library-deps"></a>deps | List of other `bzl_library` or `filegroup` targets that are required by the Starlark files listed in `srcs`. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | `[]` |
| <a id="bzl_library-srcs"></a>srcs | List of `.bzl` and `.scl` files that are processed to create this target. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | `[]` |
<a id="StarlarkLibraryInfo"></a>

4
docs/collections_doc.md
View File

@ -17,7 +17,7 @@ Inserts `separator` after each item in `iterable`.
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="collections.after_each-separator"></a>separator | The value to insert after each item in <code>iterable</code>. | none |
| <a id="collections.after_each-separator"></a>separator | The value to insert after each item in `iterable`. | none |
| <a id="collections.after_each-iterable"></a>iterable | The list into which to intersperse the separator. | none |
**RETURNS**
@ -40,7 +40,7 @@ Inserts `separator` before each item in `iterable`.
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="collections.before_each-separator"></a>separator | The value to insert before each item in <code>iterable</code>. | none |
| <a id="collections.before_each-separator"></a>separator | The value to insert before each item in `iterable`. | none |
| <a id="collections.before_each-iterable"></a>iterable | The list into which to intersperse the separator. | none |
**RETURNS**

13
docs/common_settings_doc.md
View File

@ -8,7 +8,6 @@ For label-typed settings, use the native label_flag and label_setting rules.
More documentation on how to use build settings at
https://bazel.build/extending/config#user-defined-build-settings
<a id="bool_flag"></a>
## bool_flag
@ -61,7 +60,7 @@ An int-typed build setting that can be set on the command line
| Name | Description | Type | Mandatory | Default |
| :------------- | :------------- | :------------- | :------------- | :------------- |
| <a id="int_flag-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | |
| <a id="int_flag-make_variable"></a>make_variable | If set, the build setting's value will be available as a Make variable with this name in the attributes of rules that list this build setting in their 'toolchains' attribute. | String | optional | <code>""</code> |
| <a id="int_flag-make_variable"></a>make_variable | If set, the build setting's value will be available as a Make variable with this name in the attributes of rules that list this build setting in their 'toolchains' attribute. | String | optional | `""` |
<a id="int_setting"></a>
@ -80,7 +79,7 @@ An int-typed build setting that cannot be set on the command line
| Name | Description | Type | Mandatory | Default |
| :------------- | :------------- | :------------- | :------------- | :------------- |
| <a id="int_setting-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | |
| <a id="int_setting-make_variable"></a>make_variable | If set, the build setting's value will be available as a Make variable with this name in the attributes of rules that list this build setting in their 'toolchains' attribute. | String | optional | <code>""</code> |
| <a id="int_setting-make_variable"></a>make_variable | If set, the build setting's value will be available as a Make variable with this name in the attributes of rules that list this build setting in their 'toolchains' attribute. | String | optional | `""` |
<a id="string_flag"></a>
@ -99,8 +98,8 @@ A string-typed build setting that can be set on the command line
| Name | Description | Type | Mandatory | Default |
| :------------- | :------------- | :------------- | :------------- | :------------- |
| <a id="string_flag-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | |
| <a id="string_flag-make_variable"></a>make_variable | If set, the build setting's value will be available as a Make variable with this name in the attributes of rules that list this build setting in their 'toolchains' attribute. | String | optional | <code>""</code> |
| <a id="string_flag-values"></a>values | The list of allowed values for this setting. An error is raised if any other value is given. | List of strings | optional | <code>[]</code> |
| <a id="string_flag-make_variable"></a>make_variable | If set, the build setting's value will be available as a Make variable with this name in the attributes of rules that list this build setting in their 'toolchains' attribute. | String | optional | `""` |
| <a id="string_flag-values"></a>values | The list of allowed values for this setting. An error is raised if any other value is given. | List of strings | optional | `[]` |
<a id="string_list_flag"></a>
@ -155,8 +154,8 @@ A string-typed build setting that cannot be set on the command line
| Name | Description | Type | Mandatory | Default |
| :------------- | :------------- | :------------- | :------------- | :------------- |
| <a id="string_setting-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | |
| <a id="string_setting-make_variable"></a>make_variable | If set, the build setting's value will be available as a Make variable with this name in the attributes of rules that list this build setting in their 'toolchains' attribute. | String | optional | <code>""</code> |
| <a id="string_setting-values"></a>values | The list of allowed values for this setting. An error is raised if any other value is given. | List of strings | optional | <code>[]</code> |
| <a id="string_setting-make_variable"></a>make_variable | If set, the build setting's value will be available as a Make variable with this name in the attributes of rules that list this build setting in their 'toolchains' attribute. | String | optional | `""` |
| <a id="string_setting-values"></a>values | The list of allowed values for this setting. An error is raised if any other value is given. | List of strings | optional | `[]` |
<a id="BuildSettingInfo"></a>

5
docs/copy_directory_doc.md
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
on Windows (no Bash is required).
<a id="copy_directory"></a>
## copy_directory
@ -33,7 +32,7 @@ for more context.
| <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-out"></a>out | Path of the output directory, relative to this package. | none |
| <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_action"></a>
@ -58,6 +57,6 @@ other rule implementations.
| <a id="copy_directory_action-ctx"></a>ctx | The rule context. | none |
| <a id="copy_directory_action-src"></a>src | The directory to make a copy of. Can be a source directory or TreeArtifact. | none |
| <a id="copy_directory_action-dst"></a>dst | The directory to copy to. Must be a TreeArtifact. | none |
| <a id="copy_directory_action-is_windows"></a>is_windows | If true, an cmd.exe action is created so there is no bash dependency. | <code>False</code> |
| <a id="copy_directory_action-is_windows"></a>is_windows | If true, an cmd.exe action is created so there is no bash dependency. | `False` |

7
docs/copy_file_doc.md
View File

@ -8,7 +8,6 @@ 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
on Windows (no Bash is required).
<a id="copy_file"></a>
## copy_file
@ -32,8 +31,8 @@ This rule uses a Bash command on Linux/macOS/non-Windows, and a cmd.exe command
| <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-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-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-kwargs"></a>kwargs | further keyword arguments, e.g. <code>visibility</code> | 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 `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). | `False` |
| <a id="copy_file-kwargs"></a>kwargs | further keyword arguments, e.g. `visibility` | none |

4
docs/dicts_doc.md
View File

@ -49,7 +49,7 @@ Returns a new `dict` that has all the entries of `dictionary` with keys not in `
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="dicts.omit-dictionary"></a>dictionary | A <code>dict</code>. | none |
| <a id="dicts.omit-dictionary"></a>dictionary | A `dict`. | none |
| <a id="dicts.omit-keys"></a>keys | A sequence. | none |
**RETURNS**
@ -72,7 +72,7 @@ Returns a new `dict` that has all the entries of `dictionary` with keys in `keys
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="dicts.pick-dictionary"></a>dictionary | A <code>dict</code>. | none |
| <a id="dicts.pick-dictionary"></a>dictionary | A `dict`. | none |
| <a id="dicts.pick-keys"></a>keys | A sequence. | none |
**RETURNS**

7
docs/diff_test_doc.md
View File

@ -5,7 +5,6 @@ A test rule that compares two binary files.
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).
<a id="diff_test"></a>
## diff_test
@ -25,9 +24,9 @@ The test succeeds if the files' contents match.
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <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 <code>file2</code>. | none |
| <a id="diff_test-file2"></a>file2 | Label of the file to compare to <code>file1</code>. | none |
| <a id="diff_test-failure_message"></a>failure_message | Additional message to log if the files' contents do not match. | <code>None</code> |
| <a id="diff_test-file1"></a>file1 | Label of the file to compare to `file2`. | none |
| <a id="diff_test-file2"></a>file2 | Label of the file to compare to `file1`. | none |
| <a id="diff_test-failure_message"></a>failure_message | Additional message to log if the files' contents do not match. | `None` |
| <a id="diff_test-kwargs"></a>kwargs | The [common attributes for tests](https://bazel.build/reference/be/common-definitions#common-attributes-tests). | none |

1
docs/expand_template_doc.md
View File

@ -2,7 +2,6 @@
A rule that performs template expansion.
<a id="expand_template"></a>
## expand_template

6
docs/modules_doc.md
View File

@ -28,7 +28,7 @@ rules_foo_deps_ext = modules.as_extension(rules_foo_deps)
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="modules.as_extension-macro"></a>macro | A [WORKSPACE dependency macro](https://bazel.build/rules/deploying#dependencies), i.e., a function with no required parameters that instantiates one or more repository rules. | none |
| <a id="modules.as_extension-doc"></a>doc | A description of the module extension that can be extracted by documentation generating tools. | <code>None</code> |
| <a id="modules.as_extension-doc"></a>doc | A description of the module extension that can be extracted by documentation generating tools. | `None` |
**RETURNS**
@ -64,8 +64,8 @@ ext = module_extension(_ext_impl)
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="modules.use_all_repos-module_ctx"></a>module_ctx | The [<code>module_ctx</code>](https://bazel.build/rules/lib/builtins/module_ctx) object passed to the module extension's implementation function. | none |
| <a id="modules.use_all_repos-reproducible"></a>reproducible | The value of the <code>reproducible</code> parameter to pass to the [<code>extension_metadata</code>](https://bazel.build/rules/lib/builtins/extension_metadata.html) object returned by this function. This is safe to set with Bazel versions that don't support this parameter and will be ignored in that case. | <code>False</code> |
| <a id="modules.use_all_repos-module_ctx"></a>module_ctx | The [`module_ctx`](https://bazel.build/rules/lib/builtins/module_ctx) object passed to the module extension's implementation function. | none |
| <a id="modules.use_all_repos-reproducible"></a>reproducible | The value of the `reproducible` parameter to pass to the [`extension_metadata`](https://bazel.build/rules/lib/builtins/extension_metadata.html) object returned by this function. This is safe to set with Bazel versions that don't support this parameter and will be ignored in that case. | `False` |
**RETURNS**

17
docs/native_binary_doc.md
View File

@ -7,31 +7,28 @@ and test rule respectively. They fulfill the same goal as sh_binary and sh_test
do, but they run the wrapped binary directly, instead of through Bash, so they
don't depend on Bash and work with --shell_executable="".
<a id="native_binary"></a>
## native_binary
<pre>
native_binary(<a href="#native_binary-name">name</a>, <a href="#native_binary-data">data</a>, <a href="#native_binary-out">out</a>, <a href="#native_binary-src">src</a>)
native_binary(<a href="#native_binary-name">name</a>, <a href="#native_binary-src">src</a>, <a href="#native_binary-data">data</a>, <a href="#native_binary-out">out</a>)
</pre>
Wraps a pre-built binary or script with a binary rule.
You can "bazel run" this rule like any other binary rule, and use it as a tool
in genrule.tools for example. You can also augment the binary with runfiles.
**ATTRIBUTES**
| Name | Description | Type | Mandatory | Default |
| :------------- | :------------- | :------------- | :------------- | :------------- |
| <a id="native_binary-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | |
| <a id="native_binary-data"></a>data | data dependencies. See https://bazel.build/reference/be/common-definitions#typical.data | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | <code>[]</code> |
| <a id="native_binary-out"></a>out | An output name for the copy of the binary. Defaults to name.exe. (We add .exe to the name by default because it's required on Windows and tolerated on other platforms.) | String | optional | <code>""</code> |
| <a id="native_binary-src"></a>src | path of the pre-built executable | <a href="https://bazel.build/concepts/labels">Label</a> | required | |
| <a id="native_binary-data"></a>data | data dependencies. See https://bazel.build/reference/be/common-definitions#typical.data | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | `[]` |
| <a id="native_binary-out"></a>out | An output name for the copy of the binary. Defaults to name.exe. (We add .exe to the name by default because it's required on Windows and tolerated on other platforms.) | String | optional | `""` |
<a id="native_test"></a>
@ -39,24 +36,22 @@ in genrule.tools for example. You can also augment the binary with runfiles.
## native_test
<pre>
native_test(<a href="#native_test-name">name</a>, <a href="#native_test-data">data</a>, <a href="#native_test-out">out</a>, <a href="#native_test-src">src</a>)
native_test(<a href="#native_test-name">name</a>, <a href="#native_test-src">src</a>, <a href="#native_test-data">data</a>, <a href="#native_test-out">out</a>)
</pre>
Wraps a pre-built binary or script with a test rule.
You can "bazel test" this rule like any other test rule. You can also augment
the binary with runfiles.
**ATTRIBUTES**
| Name | Description | Type | Mandatory | Default |
| :------------- | :------------- | :------------- | :------------- | :------------- |
| <a id="native_test-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | |
| <a id="native_test-data"></a>data | data dependencies. See https://bazel.build/reference/be/common-definitions#typical.data | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | <code>[]</code> |
| <a id="native_test-out"></a>out | An output name for the copy of the binary. Defaults to name.exe. (We add .exe to the name by default because it's required on Windows and tolerated on other platforms.) | String | optional | <code>""</code> |
| <a id="native_test-src"></a>src | path of the pre-built executable | <a href="https://bazel.build/concepts/labels">Label</a> | required | |
| <a id="native_test-data"></a>data | data dependencies. See https://bazel.build/reference/be/common-definitions#typical.data | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | `[]` |
| <a id="native_test-out"></a>out | An output name for the copy of the binary. Defaults to name.exe. (We add .exe to the name by default because it's required on Windows and tolerated on other platforms.) | String | optional | `""` |

329
docs/new_sets_doc.md
View File

@ -2,38 +2,35 @@
Skylib module containing common hash-set algorithms.
An empty set can be created using: `sets.make()`, or it can be created with some starting values
if you pass it an sequence: `sets.make([1, 2, 3])`. This returns a struct containing all of the
values as keys in a dictionary - this means that all passed in values must be hashable. The
values in the set can be retrieved using `sets.to_list(my_set)`.
An empty set can be created using: `sets.make()`, or it can be created with some starting values
if you pass it an sequence: `sets.make([1, 2, 3])`. This returns a struct containing all of the
values as keys in a dictionary - this means that all passed in values must be hashable. The
values in the set can be retrieved using `sets.to_list(my_set)`.
An arbitrary object can be tested whether it is a set generated by `sets.make()` or not with the
`types.is_set()` method in types.bzl.
An arbitrary object can be tested whether it is a set generated by `sets.make()` or not with the
`types.is_set()` method in types.bzl.
<a id="sets.contains"></a>
<a id="sets.make"></a>
## sets.make
## sets.contains
<pre>
sets.make(<a href="#sets.make-elements">elements</a>)
sets.contains(<a href="#sets.contains-a">a</a>, <a href="#sets.contains-e">e</a>)
</pre>
Creates a new set.
All elements must be hashable.
Checks for the existence of an element in a set.
**PARAMETERS**
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="sets.make-elements"></a>elements | Optional sequence to construct the set out of. | <code>None</code> |
| <a id="sets.contains-a"></a>a | A set, as returned by `sets.make()`. | none |
| <a id="sets.contains-e"></a>e | The element to look for. | none |
**RETURNS**
A set containing the passed in values.
True if the element exists in the set, False if the element does not.
<a id="sets.copy"></a>
@ -51,33 +48,60 @@ Creates a new set from another set.
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="sets.copy-s"></a>s | A set, as returned by <code>sets.make()</code>. | none |
| <a id="sets.copy-s"></a>s | A set, as returned by `sets.make()`. | none |
**RETURNS**
A new set containing the same elements as `s`.
<a id="sets.to_list"></a>
<a id="sets.difference"></a>
## sets.to_list
## sets.difference
<pre>
sets.to_list(<a href="#sets.to_list-s">s</a>)
sets.difference(<a href="#sets.difference-a">a</a>, <a href="#sets.difference-b">b</a>)
</pre>
Creates a list from the values in the set.
Returns the elements in `a` that are not in `b`.
**PARAMETERS**
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="sets.to_list-s"></a>s | A set, as returned by <code>sets.make()</code>. | none |
| <a id="sets.difference-a"></a>a | A set, as returned by `sets.make()`. | none |
| <a id="sets.difference-b"></a>b | A set, as returned by `sets.make()`. | none |
**RETURNS**
A list of values inserted into the set.
A set containing the elements that are in `a` but not in `b`.
<a id="sets.disjoint"></a>
## sets.disjoint
<pre>
sets.disjoint(<a href="#sets.disjoint-a">a</a>, <a href="#sets.disjoint-b">b</a>)
</pre>
Returns whether two sets are disjoint.
Two sets are disjoint if they have no elements in common.
**PARAMETERS**
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="sets.disjoint-a"></a>a | A set, as returned by `sets.make()`. | none |
| <a id="sets.disjoint-b"></a>b | A set, as returned by `sets.make()`. | none |
**RETURNS**
True if `a` and `b` are disjoint, False otherwise.
<a id="sets.insert"></a>
@ -98,7 +122,7 @@ Element must be hashable. This mutates the original set.
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="sets.insert-s"></a>s | A set, as returned by <code>sets.make()</code>. | none |
| <a id="sets.insert-s"></a>s | A set, as returned by `sets.make()`. | none |
| <a id="sets.insert-e"></a>e | The element to be inserted. | none |
**RETURNS**
@ -106,27 +130,27 @@ Element must be hashable. This mutates the original set.
The set `s` with `e` included.
<a id="sets.contains"></a>
<a id="sets.intersection"></a>
## sets.contains
## sets.intersection
<pre>
sets.contains(<a href="#sets.contains-a">a</a>, <a href="#sets.contains-e">e</a>)
sets.intersection(<a href="#sets.intersection-a">a</a>, <a href="#sets.intersection-b">b</a>)
</pre>
Checks for the existence of an element in a set.
Returns the intersection of two sets.
**PARAMETERS**
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="sets.contains-a"></a>a | A set, as returned by <code>sets.make()</code>. | none |
| <a id="sets.contains-e"></a>e | The element to look for. | none |
| <a id="sets.intersection-a"></a>a | A set, as returned by `sets.make()`. | none |
| <a id="sets.intersection-b"></a>b | A set, as returned by `sets.make()`. | none |
**RETURNS**
True if the element exists in the set, False if the element does not.
A set containing the elements that are in both `a` and `b`.
<a id="sets.is_equal"></a>
@ -144,8 +168,8 @@ Returns whether two sets are equal.
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="sets.is_equal-a"></a>a | A set, as returned by <code>sets.make()</code>. | none |
| <a id="sets.is_equal-b"></a>b | A set, as returned by <code>sets.make()</code>. | none |
| <a id="sets.is_equal-a"></a>a | A set, as returned by `sets.make()`. | none |
| <a id="sets.is_equal-b"></a>b | A set, as returned by `sets.make()`. | none |
**RETURNS**
@ -167,25 +191,47 @@ Returns whether `a` is a subset of `b`.
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="sets.is_subset-a"></a>a | A set, as returned by <code>sets.make()</code>. | none |
| <a id="sets.is_subset-b"></a>b | A set, as returned by <code>sets.make()</code>. | none |
| <a id="sets.is_subset-a"></a>a | A set, as returned by `sets.make()`. | none |
| <a id="sets.is_subset-b"></a>b | A set, as returned by `sets.make()`. | none |
**RETURNS**
True if `a` is a subset of `b`, False otherwise.
<a id="sets.disjoint"></a>
<a id="sets.length"></a>
## sets.disjoint
## sets.length
<pre>
sets.disjoint(<a href="#sets.disjoint-a">a</a>, <a href="#sets.disjoint-b">b</a>)
sets.length(<a href="#sets.length-s">s</a>)
</pre>
Returns whether two sets are disjoint.
Returns the number of elements in a set.
Two sets are disjoint if they have no elements in common.
**PARAMETERS**
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="sets.length-s"></a>s | A set, as returned by `sets.make()`. | none |
**RETURNS**
An integer representing the number of elements in the set.
<a id="sets.make"></a>
## sets.make
<pre>
sets.make(<a href="#sets.make-elements">elements</a>)
</pre>
Creates a new set.
All elements must be hashable.
**PARAMETERS**
@ -193,35 +239,103 @@ Two sets are disjoint if they have no elements in common.
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="sets.disjoint-a"></a>a | A set, as returned by <code>sets.make()</code>. | none |
| <a id="sets.disjoint-b"></a>b | A set, as returned by <code>sets.make()</code>. | none |
| <a id="sets.make-elements"></a>elements | Optional sequence to construct the set out of. | `None` |
**RETURNS**
True if `a` and `b` are disjoint, False otherwise.
A set containing the passed in values.
<a id="sets.intersection"></a>
<a id="sets.remove"></a>
## sets.intersection
## sets.remove
<pre>
sets.intersection(<a href="#sets.intersection-a">a</a>, <a href="#sets.intersection-b">b</a>)
sets.remove(<a href="#sets.remove-s">s</a>, <a href="#sets.remove-e">e</a>)
</pre>
Returns the intersection of two sets.
Removes an element from the set.
Element must be hashable. This mutates the original set.
**PARAMETERS**
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="sets.intersection-a"></a>a | A set, as returned by <code>sets.make()</code>. | none |
| <a id="sets.intersection-b"></a>b | A set, as returned by <code>sets.make()</code>. | none |
| <a id="sets.remove-s"></a>s | A set, as returned by `sets.make()`. | none |
| <a id="sets.remove-e"></a>e | The element to be removed. | none |
**RETURNS**
A set containing the elements that are in both `a` and `b`.
The set `s` with `e` removed.
<a id="sets.repr"></a>
## sets.repr
<pre>
sets.repr(<a href="#sets.repr-s">s</a>)
</pre>
Returns a string value representing the set.
**PARAMETERS**
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="sets.repr-s"></a>s | A set, as returned by `sets.make()`. | none |
**RETURNS**
A string representing the set.
<a id="sets.str"></a>
## sets.str
<pre>
sets.str(<a href="#sets.str-s">s</a>)
</pre>
Returns a string value representing the set.
**PARAMETERS**
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="sets.str-s"></a>s | A set, as returned by `sets.make()`. | none |
**RETURNS**
A string representing the set.
<a id="sets.to_list"></a>
## sets.to_list
<pre>
sets.to_list(<a href="#sets.to_list-s">s</a>)
</pre>
Creates a list from the values in the set.
**PARAMETERS**
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="sets.to_list-s"></a>s | A set, as returned by `sets.make()`. | none |
**RETURNS**
A list of values inserted into the set.
<a id="sets.union"></a>
@ -246,118 +360,3 @@ Returns the union of several sets.
The set union of all sets in `*args`.
<a id="sets.difference"></a>
## sets.difference
<pre>
sets.difference(<a href="#sets.difference-a">a</a>, <a href="#sets.difference-b">b</a>)
</pre>
Returns the elements in `a` that are not in `b`.
**PARAMETERS**
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="sets.difference-a"></a>a | A set, as returned by <code>sets.make()</code>. | none |
| <a id="sets.difference-b"></a>b | A set, as returned by <code>sets.make()</code>. | none |
**RETURNS**
A set containing the elements that are in `a` but not in `b`.
<a id="sets.length"></a>
## sets.length
<pre>
sets.length(<a href="#sets.length-s">s</a>)
</pre>
Returns the number of elements in a set.
**PARAMETERS**
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="sets.length-s"></a>s | A set, as returned by <code>sets.make()</code>. | none |
**RETURNS**
An integer representing the number of elements in the set.
<a id="sets.remove"></a>
## sets.remove
<pre>
sets.remove(<a href="#sets.remove-s">s</a>, <a href="#sets.remove-e">e</a>)
</pre>
Removes an element from the set.
Element must be hashable. This mutates the original set.
**PARAMETERS**
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="sets.remove-s"></a>s | A set, as returned by <code>sets.make()</code>. | none |
| <a id="sets.remove-e"></a>e | The element to be removed. | none |
**RETURNS**
The set `s` with `e` removed.
<a id="sets.repr"></a>
## sets.repr
<pre>
sets.repr(<a href="#sets.repr-s">s</a>)
</pre>
Returns a string value representing the set.
**PARAMETERS**
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="sets.repr-s"></a>s | A set, as returned by <code>sets.make()</code>. | none |
**RETURNS**
A string representing the set.
<a id="sets.str"></a>
## sets.str
<pre>
sets.str(<a href="#sets.str-s">s</a>)
</pre>
Returns a string value representing the set.
**PARAMETERS**
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="sets.str-s"></a>s | A set, as returned by <code>sets.make()</code>. | none |
**RETURNS**
A string representing the set.

91
docs/partial_doc.md
View File

@ -6,6 +6,51 @@ Partial function objects allow some parameters are bound before the call.
Similar to https://docs.python.org/3/library/functools.html#functools.partial.
<a id="partial.call"></a>
## partial.call
<pre>
partial.call(<a href="#partial.call-partial">partial</a>, <a href="#partial.call-args">args</a>, <a href="#partial.call-kwargs">kwargs</a>)
</pre>
Calls a partial created using `make`.
**PARAMETERS**
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="partial.call-partial"></a>partial | The partial to be called. | none |
| <a id="partial.call-args"></a>args | Additional positional arguments to be appended to the ones given to make. | none |
| <a id="partial.call-kwargs"></a>kwargs | Additional keyword arguments to augment and override the ones given to make. | none |
**RETURNS**
Whatever the function in the partial returns.
<a id="partial.is_instance"></a>
## partial.is_instance
<pre>
partial.is_instance(<a href="#partial.is_instance-v">v</a>)
</pre>
Returns True if v is a partial created using `make`.
**PARAMETERS**
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="partial.is_instance-v"></a>v | The value to check. | none |
**RETURNS**
True if v was created by `make`, False otherwise.
<a id="partial.make"></a>
@ -123,49 +168,3 @@ partial.call(func, x=2)
A new `partial` that can be called using `call`
<a id="partial.call"></a>
## partial.call
<pre>
partial.call(<a href="#partial.call-partial">partial</a>, <a href="#partial.call-args">args</a>, <a href="#partial.call-kwargs">kwargs</a>)
</pre>
Calls a partial created using `make`.
**PARAMETERS**
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="partial.call-partial"></a>partial | The partial to be called. | none |
| <a id="partial.call-args"></a>args | Additional positional arguments to be appended to the ones given to make. | none |
| <a id="partial.call-kwargs"></a>kwargs | Additional keyword arguments to augment and override the ones given to make. | none |
**RETURNS**
Whatever the function in the partial returns.
<a id="partial.is_instance"></a>
## partial.is_instance
<pre>
partial.is_instance(<a href="#partial.is_instance-v">v</a>)
</pre>
Returns True if v is a partial created using `make`.
**PARAMETERS**
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="partial.is_instance-v"></a>v | The value to check. | none |
**RETURNS**
True if v was created by `make`, False otherwise.

1
docs/paths_doc.md
View File

@ -6,7 +6,6 @@ NOTE: The functions in this module currently only support paths with Unix-style
path separators (forward slash, "/"); they do not handle Windows-style paths
with backslash separators or drive letters.
<a id="paths.basename"></a>
## paths.basename

2
docs/private/stardoc_with_diff_test.bzl
View File

@ -89,7 +89,7 @@ def update_docs(
content = ["#!/usr/bin/env bash", "cd ${BUILD_WORKSPACE_DIRECTORY}"]
data = []
for r in native.existing_rules().values():
if r["kind"] == "stardoc":
if r["kind"] == "stardoc_markdown_renderer":
doc_gen = r["out"]
if doc_gen.startswith(":"):
doc_gen = doc_gen[1:]

14
docs/run_binary_doc.md
View File

@ -1,17 +1,15 @@
<!-- Generated with Stardoc: http://skydoc.bazel.build -->
run_binary() build rule implementation.
Runs a binary as a build action. This rule does not require Bash (unlike native.genrule()).
<a id="run_binary"></a>
## run_binary
<pre>
run_binary(<a href="#run_binary-name">name</a>, <a href="#run_binary-args">args</a>, <a href="#run_binary-env">env</a>, <a href="#run_binary-outs">outs</a>, <a href="#run_binary-srcs">srcs</a>, <a href="#run_binary-tool">tool</a>)
run_binary(<a href="#run_binary-name">name</a>, <a href="#run_binary-srcs">srcs</a>, <a href="#run_binary-outs">outs</a>, <a href="#run_binary-args">args</a>, <a href="#run_binary-env">env</a>, <a href="#run_binary-tool">tool</a>)
</pre>
Runs a binary as a build action.
@ -24,10 +22,10 @@ This rule does not require Bash (unlike `native.genrule`).
| Name | Description | Type | Mandatory | Default |
| :------------- | :------------- | :------------- | :------------- | :------------- |
| <a id="run_binary-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | |
| <a id="run_binary-args"></a>args | Command line arguments of the binary.<br><br>Subject to [<code>$(location)</code>](https://bazel.build/reference/be/make-variables#predefined_label_variables) expansion. | List of strings | optional | <code>[]</code> |
| <a id="run_binary-env"></a>env | Environment variables of the action.<br><br>Subject to [<code>$(location)</code>](https://bazel.build/reference/be/make-variables#predefined_label_variables) expansion. | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a> | optional | <code>{}</code> |
| <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>. | List of labels | required | |
| <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>. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | <code>[]</code> |
| <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>. | <a href="https://bazel.build/concepts/labels">Label</a> | required | |
| <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 href="https://bazel.build/concepts/labels">List of labels</a> | optional | `[]` |
| <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`. | List of labels | required | |
| <a id="run_binary-args"></a>args | Command line arguments of the binary.<br><br>Subject to [`$(location)`](https://bazel.build/reference/be/make-variables#predefined_label_variables) expansion. | List of strings | optional | `[]` |
| <a id="run_binary-env"></a>env | Environment variables of the action.<br><br>Subject to [`$(location)`](https://bazel.build/reference/be/make-variables#predefined_label_variables) expansion. | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a> | optional | `{}` |
| <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`. | <a href="https://bazel.build/concepts/labels">Label</a> | required | |

2
docs/select_file_doc.md
View File

@ -1,11 +1,9 @@
<!-- Generated with Stardoc: http://skydoc.bazel.build -->
select_file() build rule implementation.
Selects a single file from the outputs of a target by given relative path.
<a id="select_file"></a>
## select_file

152
docs/selects_doc.md
View File

@ -2,78 +2,6 @@
Skylib module containing convenience interfaces for select().
<a id="selects.with_or"></a>
## selects.with_or
<pre>
selects.with_or(<a href="#selects.with_or-input_dict">input_dict</a>, <a href="#selects.with_or-no_match_error">no_match_error</a>)
</pre>
Drop-in replacement for `select()` that supports ORed keys.
Example:
```build
deps = selects.with_or({
"//configs:one": [":dep1"],
("//configs:two", "//configs:three"): [":dep2or3"],
"//configs:four": [":dep4"],
"//conditions:default": [":default"]
})
```
Key labels may appear at most once anywhere in the input.
**PARAMETERS**
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="selects.with_or-input_dict"></a>input_dict | The same dictionary <code>select()</code> takes, except keys may take either the usual form <code>"//foo:config1"</code> or <code>("//foo:config1", "//foo:config2", ...)</code> to signify <code>//foo:config1</code> OR <code>//foo:config2</code> OR <code>...</code>. | none |
| <a id="selects.with_or-no_match_error"></a>no_match_error | Optional custom error to report if no condition matches. | <code>""</code> |
**RETURNS**
A native `select()` that expands
`("//configs:two", "//configs:three"): [":dep2or3"]`
to
```build
"//configs:two": [":dep2or3"],
"//configs:three": [":dep2or3"],
```
<a id="selects.with_or_dict"></a>
## selects.with_or_dict
<pre>
selects.with_or_dict(<a href="#selects.with_or_dict-input_dict">input_dict</a>)
</pre>
Variation of `with_or` that returns the dict of the `select()`.
Unlike `select()`, the contents of the dict can be inspected by Starlark
macros.
**PARAMETERS**
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="selects.with_or_dict-input_dict"></a>input_dict | Same as <code>with_or</code>. | none |
**RETURNS**
A dictionary usable by a native `select()`.
<a id="selects.config_setting_group"></a>
## selects.config_setting_group
@ -111,9 +39,81 @@ Example:
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="selects.config_setting_group-name"></a>name | The group's name. This is how <code>select()</code>s reference it. | none |
| <a id="selects.config_setting_group-match_any"></a>match_any | A list of <code>config_settings</code>. This group matches if *any* member in the list matches. If this is set, <code>match_all</code> must not be set. | <code>[]</code> |
| <a id="selects.config_setting_group-match_all"></a>match_all | A list of <code>config_settings</code>. This group matches if *every* member in the list matches. If this is set, <code>match_any</code> must be not set. | <code>[]</code> |
| <a id="selects.config_setting_group-visibility"></a>visibility | Visibility of the config_setting_group. | <code>None</code> |
| <a id="selects.config_setting_group-name"></a>name | The group's name. This is how `select()`s reference it. | none |
| <a id="selects.config_setting_group-match_any"></a>match_any | A list of `config_settings`. This group matches if *any* member in the list matches. If this is set, `match_all` must not be set. | `[]` |
| <a id="selects.config_setting_group-match_all"></a>match_all | A list of `config_settings`. This group matches if *every* member in the list matches. If this is set, `match_any` must be not set. | `[]` |
| <a id="selects.config_setting_group-visibility"></a>visibility | Visibility of the config_setting_group. | `None` |
<a id="selects.with_or"></a>
## selects.with_or
<pre>
selects.with_or(<a href="#selects.with_or-input_dict">input_dict</a>, <a href="#selects.with_or-no_match_error">no_match_error</a>)
</pre>
Drop-in replacement for `select()` that supports ORed keys.
Example:
```build
deps = selects.with_or({
"//configs:one": [":dep1"],
("//configs:two", "//configs:three"): [":dep2or3"],
"//configs:four": [":dep4"],
"//conditions:default": [":default"]
})
```
Key labels may appear at most once anywhere in the input.
**PARAMETERS**
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="selects.with_or-input_dict"></a>input_dict | The same dictionary `select()` takes, except keys may take either the usual form `"//foo:config1"` or `("//foo:config1", "//foo:config2", ...)` to signify `//foo:config1` OR `//foo:config2` OR `...`. | none |
| <a id="selects.with_or-no_match_error"></a>no_match_error | Optional custom error to report if no condition matches. | `""` |
**RETURNS**
A native `select()` that expands
`("//configs:two", "//configs:three"): [":dep2or3"]`
to
```build
"//configs:two": [":dep2or3"],
"//configs:three": [":dep2or3"],
```
<a id="selects.with_or_dict"></a>
## selects.with_or_dict
<pre>
selects.with_or_dict(<a href="#selects.with_or_dict-input_dict">input_dict</a>)
</pre>
Variation of `with_or` that returns the dict of the `select()`.
Unlike `select()`, the contents of the dict can be inspected by Starlark
macros.
**PARAMETERS**
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="selects.with_or_dict-input_dict"></a>input_dict | Same as `with_or`. | none |
**RETURNS**
A dictionary usable by a native `select()`.

2
docs/shell_doc.md
View File

@ -25,7 +25,7 @@ safety, even if they do not need to be.
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="shell.array_literal-iterable"></a>iterable | A sequence of elements. Elements that are not strings will be converted to strings first, by calling <code>str()</code>. | none |
| <a id="shell.array_literal-iterable"></a>iterable | A sequence of elements. Elements that are not strings will be converted to strings first, by calling `str()`. | none |
**RETURNS**

2
docs/structs_doc.md
View File

@ -17,7 +17,7 @@ Converts a `struct` to a `dict`.
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="structs.to_dict-s"></a>s | A <code>struct</code>. | none |
| <a id="structs.to_dict-s"></a>s | A `struct`. | none |
**RETURNS**

7
docs/subpackages_doc.md
View File

@ -2,7 +2,6 @@
Skylib module containing common functions for working with native.subpackages()
<a id="subpackages.all"></a>
## subpackages.all
@ -36,9 +35,9 @@ NOTE: fail()s if native.subpackages() is not supported.
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="subpackages.all-exclude"></a>exclude | see native.subpackages(exclude) | <code>[]</code> |
| <a id="subpackages.all-allow_empty"></a>allow_empty | see native.subpackages(allow_empty) | <code>False</code> |
| <a id="subpackages.all-fully_qualified"></a>fully_qualified | It true return fully qualified Labels for subpackages, otherwise returns subpackage path relative to current package. | <code>True</code> |
| <a id="subpackages.all-exclude"></a>exclude | see native.subpackages(exclude) | `[]` |
| <a id="subpackages.all-allow_empty"></a>allow_empty | see native.subpackages(allow_empty) | `False` |
| <a id="subpackages.all-fully_qualified"></a>fully_qualified | It true return fully qualified Labels for subpackages, otherwise returns subpackage path relative to current package. | `True` |
**RETURNS**

200
docs/types_doc.md
View File

@ -2,50 +2,6 @@
Skylib module containing functions checking types.
<a id="types.is_list"></a>
## types.is_list
<pre>
types.is_list(<a href="#types.is_list-v">v</a>)
</pre>
Returns True if v is an instance of a list.
**PARAMETERS**
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="types.is_list-v"></a>v | The value whose type should be checked. | none |
**RETURNS**
True if v is an instance of a list, False otherwise.
<a id="types.is_string"></a>
## types.is_string
<pre>
types.is_string(<a href="#types.is_string-v">v</a>)
</pre>
Returns True if v is an instance of a string.
**PARAMETERS**
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="types.is_string-v"></a>v | The value whose type should be checked. | none |
**RETURNS**
True if v is an instance of a string, False otherwise.
<a id="types.is_bool"></a>
## types.is_bool
@ -68,70 +24,26 @@ Returns True if v is an instance of a bool.
True if v is an instance of a bool, False otherwise.
<a id="types.is_none"></a>
<a id="types.is_depset"></a>
## types.is_none
## types.is_depset
<pre>
types.is_none(<a href="#types.is_none-v">v</a>)
types.is_depset(<a href="#types.is_depset-v">v</a>)
</pre>
Returns True if v has the type of None.
Returns True if v is an instance of a `depset`.
**PARAMETERS**
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="types.is_none-v"></a>v | The value whose type should be checked. | none |
| <a id="types.is_depset-v"></a>v | The value whose type should be checked. | none |
**RETURNS**
True if v is None, False otherwise.
<a id="types.is_int"></a>
## types.is_int
<pre>
types.is_int(<a href="#types.is_int-v">v</a>)
</pre>
Returns True if v is an instance of a signed integer.
**PARAMETERS**
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="types.is_int-v"></a>v | The value whose type should be checked. | none |
**RETURNS**
True if v is an instance of a signed integer, False otherwise.
<a id="types.is_tuple"></a>
## types.is_tuple
<pre>
types.is_tuple(<a href="#types.is_tuple-v">v</a>)
</pre>
Returns True if v is an instance of a tuple.
**PARAMETERS**
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="types.is_tuple-v"></a>v | The value whose type should be checked. | none |
**RETURNS**
True if v is an instance of a tuple, False otherwise.
True if v is an instance of a `depset`, False otherwise.
<a id="types.is_dict"></a>
@ -178,26 +90,70 @@ Returns True if v is an instance of a function.
True if v is an instance of a function, False otherwise.
<a id="types.is_depset"></a>
<a id="types.is_int"></a>
## types.is_depset
## types.is_int
<pre>
types.is_depset(<a href="#types.is_depset-v">v</a>)
types.is_int(<a href="#types.is_int-v">v</a>)
</pre>
Returns True if v is an instance of a `depset`.
Returns True if v is an instance of a signed integer.
**PARAMETERS**
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="types.is_depset-v"></a>v | The value whose type should be checked. | none |
| <a id="types.is_int-v"></a>v | The value whose type should be checked. | none |
**RETURNS**
True if v is an instance of a `depset`, False otherwise.
True if v is an instance of a signed integer, False otherwise.
<a id="types.is_list"></a>
## types.is_list
<pre>
types.is_list(<a href="#types.is_list-v">v</a>)
</pre>
Returns True if v is an instance of a list.
**PARAMETERS**
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="types.is_list-v"></a>v | The value whose type should be checked. | none |
**RETURNS**
True if v is an instance of a list, False otherwise.
<a id="types.is_none"></a>
## types.is_none
<pre>
types.is_none(<a href="#types.is_none-v">v</a>)
</pre>
Returns True if v has the type of None.
**PARAMETERS**
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="types.is_none-v"></a>v | The value whose type should be checked. | none |
**RETURNS**
True if v is None, False otherwise.
<a id="types.is_set"></a>
@ -222,3 +178,47 @@ Returns True if v is a set created by sets.make().
True if v was created by sets.make(), False otherwise.
<a id="types.is_string"></a>
## types.is_string
<pre>
types.is_string(<a href="#types.is_string-v">v</a>)
</pre>
Returns True if v is an instance of a string.
**PARAMETERS**
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="types.is_string-v"></a>v | The value whose type should be checked. | none |
**RETURNS**
True if v is an instance of a string, False otherwise.
<a id="types.is_tuple"></a>
## types.is_tuple
<pre>
types.is_tuple(<a href="#types.is_tuple-v">v</a>)
</pre>
Returns True if v is an instance of a tuple.
**PARAMETERS**
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="types.is_tuple-v"></a>v | The value whose type should be checked. | none |
**RETURNS**
True if v is an instance of a tuple, False otherwise.

481
docs/unittest_doc.md
View File

@ -15,7 +15,6 @@ Unlike most Skylib files, this exports four modules:
See https://bazel.build/extending/concepts for background about macros, rules,
and the different phases of a build.
<a id="unittest_toolchain"></a>
## unittest_toolchain
@ -33,14 +32,89 @@ unittest_toolchain(<a href="#unittest_toolchain-name">name</a>, <a href="#unitte
| Name | Description | Type | Mandatory | Default |
| :------------- | :------------- | :------------- | :------------- | :------------- |
| <a id="unittest_toolchain-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | |
| <a id="unittest_toolchain-escape_chars_with"></a>escape_chars_with | Dictionary of characters that need escaping in test failure message to prefix appended to escape those characters. For example, <code>{"%": "%", "&gt;": "^"}</code> would replace <code>%</code> with <code>%%</code> and <code>&gt;</code> with <code>^&gt;</code> in the failure message before that is included in <code>success_templ</code>. | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a> | optional | <code>{}</code> |
| <a id="unittest_toolchain-escape_other_chars_with"></a>escape_other_chars_with | String to prefix every character in test failure message which is not a key in <code>escape_chars_with</code> before including that in <code>success_templ</code>. For example, <code>""</code> would prefix every character in the failure message (except those in the keys of <code>escape_chars_with</code>) with <code>\</code>. | String | optional | <code>""</code> |
| <a id="unittest_toolchain-failure_templ"></a>failure_templ | Test script template with a single <code>%s</code>. That placeholder is replaced with the lines in the failure message joined with the string specified in <code>join_with</code>. The resulting script should print the failure message and exit with non-zero status. | String | required | |
| <a id="unittest_toolchain-escape_chars_with"></a>escape_chars_with | Dictionary of characters that need escaping in test failure message to prefix appended to escape those characters. For example, `{"%": "%", ">": "^"}` would replace `%` with `%%` and `>` with `^>` in the failure message before that is included in `success_templ`. | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a> | optional | `{}` |
| <a id="unittest_toolchain-escape_other_chars_with"></a>escape_other_chars_with | String to prefix every character in test failure message which is not a key in `escape_chars_with` before including that in `success_templ`. For example, `""` would prefix every character in the failure message (except those in the keys of `escape_chars_with`) with `\`. | String | optional | `""` |
| <a id="unittest_toolchain-failure_templ"></a>failure_templ | Test script template with a single `%s`. That placeholder is replaced with the lines in the failure message joined with the string specified in `join_with`. The resulting script should print the failure message and exit with non-zero status. | String | required | |
| <a id="unittest_toolchain-file_ext"></a>file_ext | File extension for test script, including leading dot. | String | required | |
| <a id="unittest_toolchain-join_on"></a>join_on | String used to join the lines in the failure message before including the resulting string in the script specified in <code>failure_templ</code>. | String | required | |
| <a id="unittest_toolchain-join_on"></a>join_on | String used to join the lines in the failure message before including the resulting string in the script specified in `failure_templ`. | String | required | |
| <a id="unittest_toolchain-success_templ"></a>success_templ | Test script generated when the test passes. Should exit with status 0. | String | required | |
<a id="analysistest.begin"></a>
## analysistest.begin
<pre>
analysistest.begin(<a href="#analysistest.begin-ctx">ctx</a>)
</pre>
Begins an analysis test.
This should be the first function called in an analysis test implementation
function. It initializes a "test environment" that is used to collect
assertion failures so that they can be reported and logged at the end of the
test.
**PARAMETERS**
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="analysistest.begin-ctx"></a>ctx | The Starlark context. Pass the implementation function's `ctx` argument in verbatim. | none |
**RETURNS**
A test environment struct that must be passed to assertions and finally to
`analysistest.end`. Do not rely on internal details about the fields in this
struct as it may change.
<a id="analysistest.end"></a>
## analysistest.end
<pre>
analysistest.end(<a href="#analysistest.end-env">env</a>)
</pre>
Ends an analysis test and logs the results.
This must be called and returned at the end of an analysis test implementation function so
that the results are reported.
**PARAMETERS**
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="analysistest.end-env"></a>env | The test environment returned by `analysistest.begin`. | none |
**RETURNS**
A list of providers needed to automatically register the analysis test result.
<a id="analysistest.fail"></a>
## analysistest.fail
<pre>
analysistest.fail(<a href="#analysistest.fail-env">env</a>, <a href="#analysistest.fail-msg">msg</a>)
</pre>
Unconditionally causes the current test to fail.
**PARAMETERS**
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="analysistest.fail-env"></a>env | The test environment returned by `unittest.begin`. | none |
| <a id="analysistest.fail-msg"></a>msg | The message to log describing the failure. | none |
<a id="analysistest.make"></a>
## analysistest.make
@ -82,12 +156,12 @@ Recall that names of test rules must end in `_test`.
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="analysistest.make-impl"></a>impl | The implementation function of the unit test. | none |
| <a id="analysistest.make-expect_failure"></a>expect_failure | If true, the analysis test will expect the target_under_test to fail. Assertions can be made on the underlying failure using asserts.expect_failure | <code>False</code> |
| <a id="analysistest.make-attrs"></a>attrs | An optional dictionary to supplement the attrs passed to the unit test's <code>rule()</code> constructor. | <code>{}</code> |
| <a id="analysistest.make-fragments"></a>fragments | An optional list of fragment names that can be used to give rules access to language-specific parts of configuration. | <code>[]</code> |
| <a id="analysistest.make-config_settings"></a>config_settings | A dictionary of configuration settings to change for the target under test and its dependencies. This may be used to essentially change 'build flags' for the target under test, and may thus be utilized to test multiple targets with different flags in a single build | <code>{}</code> |
| <a id="analysistest.make-extra_target_under_test_aspects"></a>extra_target_under_test_aspects | An optional list of aspects to apply to the target_under_test in addition to those set up by default for the test harness itself. | <code>[]</code> |
| <a id="analysistest.make-doc"></a>doc | A description of the rule that can be extracted by documentation generating tools. | <code>""</code> |
| <a id="analysistest.make-expect_failure"></a>expect_failure | If true, the analysis test will expect the target_under_test to fail. Assertions can be made on the underlying failure using asserts.expect_failure | `False` |
| <a id="analysistest.make-attrs"></a>attrs | An optional dictionary to supplement the attrs passed to the unit test's `rule()` constructor. | `{}` |
| <a id="analysistest.make-fragments"></a>fragments | An optional list of fragment names that can be used to give rules access to language-specific parts of configuration. | `[]` |
| <a id="analysistest.make-config_settings"></a>config_settings | A dictionary of configuration settings to change for the target under test and its dependencies. This may be used to essentially change 'build flags' for the target under test, and may thus be utilized to test multiple targets with different flags in a single build | `{}` |
| <a id="analysistest.make-extra_target_under_test_aspects"></a>extra_target_under_test_aspects | An optional list of aspects to apply to the target_under_test in addition to those set up by default for the test harness itself. | `[]` |
| <a id="analysistest.make-doc"></a>doc | A description of the rule that can be extracted by documentation generating tools. | `""` |
**RETURNS**
@ -95,81 +169,6 @@ A rule definition that should be stored in a global whose name ends in
`_test`.
<a id="analysistest.begin"></a>
## analysistest.begin
<pre>
analysistest.begin(<a href="#analysistest.begin-ctx">ctx</a>)
</pre>
Begins an analysis test.
This should be the first function called in an analysis test implementation
function. It initializes a "test environment" that is used to collect
assertion failures so that they can be reported and logged at the end of the
test.
**PARAMETERS**
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="analysistest.begin-ctx"></a>ctx | The Starlark context. Pass the implementation function's <code>ctx</code> argument in verbatim. | none |
**RETURNS**
A test environment struct that must be passed to assertions and finally to
`analysistest.end`. Do not rely on internal details about the fields in this
struct as it may change.
<a id="analysistest.end"></a>
## analysistest.end
<pre>
analysistest.end(<a href="#analysistest.end-env">env</a>)
</pre>
Ends an analysis test and logs the results.
This must be called and returned at the end of an analysis test implementation function so
that the results are reported.
**PARAMETERS**
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="analysistest.end-env"></a>env | The test environment returned by <code>analysistest.begin</code>. | none |
**RETURNS**
A list of providers needed to automatically register the analysis test result.
<a id="analysistest.fail"></a>
## analysistest.fail
<pre>
analysistest.fail(<a href="#analysistest.fail-env">env</a>, <a href="#analysistest.fail-msg">msg</a>)
</pre>
Unconditionally causes the current test to fail.
**PARAMETERS**
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="analysistest.fail-env"></a>env | The test environment returned by <code>unittest.begin</code>. | none |
| <a id="analysistest.fail-msg"></a>msg | The message to log describing the failure. | none |
<a id="analysistest.target_actions"></a>
## analysistest.target_actions
@ -185,7 +184,7 @@ Returns a list of actions registered by the target under test.
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="analysistest.target_actions-env"></a>env | The test environment returned by <code>analysistest.begin</code>. | none |
| <a id="analysistest.target_actions-env"></a>env | The test environment returned by `analysistest.begin`. | none |
**RETURNS**
@ -207,7 +206,7 @@ Returns ctx.bin_dir.path for the target under test.
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="analysistest.target_bin_dir_path-env"></a>env | The test environment returned by <code>analysistest.begin</code>. | none |
| <a id="analysistest.target_bin_dir_path-env"></a>env | The test environment returned by `analysistest.begin`. | none |
**RETURNS**
@ -229,13 +228,34 @@ Returns the target under test.
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="analysistest.target_under_test-env"></a>env | The test environment returned by <code>analysistest.begin</code>. | none |
| <a id="analysistest.target_under_test-env"></a>env | The test environment returned by `analysistest.begin`. | none |
**RETURNS**
The target under test.
<a id="asserts.equals"></a>
## asserts.equals
<pre>
asserts.equals(<a href="#asserts.equals-env">env</a>, <a href="#asserts.equals-expected">expected</a>, <a href="#asserts.equals-actual">actual</a>, <a href="#asserts.equals-msg">msg</a>)
</pre>
Asserts that the given `expected` and `actual` values are equal.
**PARAMETERS**
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="asserts.equals-env"></a>env | The test environment returned by `unittest.begin`. | none |
| <a id="asserts.equals-expected"></a>expected | The expected value of some computation. | none |
| <a id="asserts.equals-actual"></a>actual | The actual value returned by some computation. | none |
| <a id="asserts.equals-msg"></a>msg | An optional message that will be printed that describes the failure. If omitted, a default will be used. | `None` |
<a id="asserts.expect_failure"></a>
## asserts.expect_failure
@ -255,29 +275,8 @@ This requires that the analysis test is created with `analysistest.make()` and
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="asserts.expect_failure-env"></a>env | The test environment returned by <code>analysistest.begin</code>. | none |
| <a id="asserts.expect_failure-expected_failure_msg"></a>expected_failure_msg | The error message to expect as a result of analysis failures. | <code>""</code> |
<a id="asserts.equals"></a>
## asserts.equals
<pre>
asserts.equals(<a href="#asserts.equals-env">env</a>, <a href="#asserts.equals-expected">expected</a>, <a href="#asserts.equals-actual">actual</a>, <a href="#asserts.equals-msg">msg</a>)
</pre>
Asserts that the given `expected` and `actual` values are equal.
**PARAMETERS**
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="asserts.equals-env"></a>env | The test environment returned by <code>unittest.begin</code>. | none |
| <a id="asserts.equals-expected"></a>expected | The expected value of some computation. | none |
| <a id="asserts.equals-actual"></a>actual | The actual value returned by some computation. | none |
| <a id="asserts.equals-msg"></a>msg | An optional message that will be printed that describes the failure. If omitted, a default will be used. | <code>None</code> |
| <a id="asserts.expect_failure-env"></a>env | The test environment returned by `analysistest.begin`. | none |
| <a id="asserts.expect_failure-expected_failure_msg"></a>expected_failure_msg | The error message to expect as a result of analysis failures. | `""` |
<a id="asserts.false"></a>
@ -295,30 +294,9 @@ Asserts that the given `condition` is false.
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="asserts.false-env"></a>env | The test environment returned by <code>unittest.begin</code>. | none |
| <a id="asserts.false-env"></a>env | The test environment returned by `unittest.begin`. | none |
| <a id="asserts.false-condition"></a>condition | A value that will be evaluated in a Boolean context. | none |
| <a id="asserts.false-msg"></a>msg | An optional message that will be printed that describes the failure. If omitted, a default will be used. | <code>"Expected condition to be false, but was true."</code> |
<a id="asserts.set_equals"></a>
## asserts.set_equals
<pre>
asserts.set_equals(<a href="#asserts.set_equals-env">env</a>, <a href="#asserts.set_equals-expected">expected</a>, <a href="#asserts.set_equals-actual">actual</a>, <a href="#asserts.set_equals-msg">msg</a>)
</pre>
Asserts that the given `expected` and `actual` sets are equal.
**PARAMETERS**
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="asserts.set_equals-env"></a>env | The test environment returned by <code>unittest.begin</code>. | none |
| <a id="asserts.set_equals-expected"></a>expected | The expected set resulting from some computation. | none |
| <a id="asserts.set_equals-actual"></a>actual | The actual set returned by some computation. | none |
| <a id="asserts.set_equals-msg"></a>msg | An optional message that will be printed that describes the failure. If omitted, a default will be used. | <code>None</code> |
| <a id="asserts.false-msg"></a>msg | An optional message that will be printed that describes the failure. If omitted, a default will be used. | `"Expected condition to be false, but was true."` |
<a id="asserts.new_set_equals"></a>
@ -336,10 +314,31 @@ Asserts that the given `expected` and `actual` sets are equal.
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="asserts.new_set_equals-env"></a>env | The test environment returned by <code>unittest.begin</code>. | none |
| <a id="asserts.new_set_equals-env"></a>env | The test environment returned by `unittest.begin`. | none |
| <a id="asserts.new_set_equals-expected"></a>expected | The expected set resulting from some computation. | none |
| <a id="asserts.new_set_equals-actual"></a>actual | The actual set returned by some computation. | none |
| <a id="asserts.new_set_equals-msg"></a>msg | An optional message that will be printed that describes the failure. If omitted, a default will be used. | <code>None</code> |
| <a id="asserts.new_set_equals-msg"></a>msg | An optional message that will be printed that describes the failure. If omitted, a default will be used. | `None` |
<a id="asserts.set_equals"></a>
## asserts.set_equals
<pre>
asserts.set_equals(<a href="#asserts.set_equals-env">env</a>, <a href="#asserts.set_equals-expected">expected</a>, <a href="#asserts.set_equals-actual">actual</a>, <a href="#asserts.set_equals-msg">msg</a>)
</pre>
Asserts that the given `expected` and `actual` sets are equal.
**PARAMETERS**
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="asserts.set_equals-env"></a>env | The test environment returned by `unittest.begin`. | none |
| <a id="asserts.set_equals-expected"></a>expected | The expected set resulting from some computation. | none |
| <a id="asserts.set_equals-actual"></a>actual | The actual set returned by some computation. | none |
| <a id="asserts.set_equals-msg"></a>msg | An optional message that will be printed that describes the failure. If omitted, a default will be used. | `None` |
<a id="asserts.true"></a>
@ -357,31 +356,9 @@ Asserts that the given `condition` is true.
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="asserts.true-env"></a>env | The test environment returned by <code>unittest.begin</code>. | none |
| <a id="asserts.true-env"></a>env | The test environment returned by `unittest.begin`. | none |
| <a id="asserts.true-condition"></a>condition | A value that will be evaluated in a Boolean context. | none |
| <a id="asserts.true-msg"></a>msg | An optional message that will be printed that describes the failure. If omitted, a default will be used. | <code>"Expected condition to be true, but was false."</code> |
<a id="loadingtest.make"></a>
## loadingtest.make
<pre>
loadingtest.make(<a href="#loadingtest.make-name">name</a>)
</pre>
Creates a loading phase test environment and test_suite.
**PARAMETERS**
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="loadingtest.make-name"></a>name | name of the suite of tests to create | none |
**RETURNS**
loading phase environment passed to other loadingtest functions
| <a id="asserts.true-msg"></a>msg | An optional message that will be printed that describes the failure. If omitted, a default will be used. | `"Expected condition to be true, but was false."` |
<a id="loadingtest.equals"></a>
@ -409,6 +386,28 @@ Creates a test case for asserting state at LOADING phase.
None, creates test case
<a id="loadingtest.make"></a>
## loadingtest.make
<pre>
loadingtest.make(<a href="#loadingtest.make-name">name</a>)
</pre>
Creates a loading phase test environment and test_suite.
**PARAMETERS**
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="loadingtest.make-name"></a>name | name of the suite of tests to create | none |
**RETURNS**
loading phase environment passed to other loadingtest functions
<a id="register_unittest_toolchains"></a>
## register_unittest_toolchains
@ -421,6 +420,81 @@ Registers the toolchains for unittest users.
<a id="unittest.begin"></a>
## unittest.begin
<pre>
unittest.begin(<a href="#unittest.begin-ctx">ctx</a>)
</pre>
Begins a unit test.
This should be the first function called in a unit test implementation
function. It initializes a "test environment" that is used to collect
assertion failures so that they can be reported and logged at the end of the
test.
**PARAMETERS**
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="unittest.begin-ctx"></a>ctx | The Starlark context. Pass the implementation function's `ctx` argument in verbatim. | none |
**RETURNS**
A test environment struct that must be passed to assertions and finally to
`unittest.end`. Do not rely on internal details about the fields in this
struct as it may change.
<a id="unittest.end"></a>
## unittest.end
<pre>
unittest.end(<a href="#unittest.end-env">env</a>)
</pre>
Ends a unit test and logs the results.
This must be called and returned at the end of a unit test implementation function so
that the results are reported.
**PARAMETERS**
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="unittest.end-env"></a>env | The test environment returned by `unittest.begin`. | none |
**RETURNS**
A list of providers needed to automatically register the test result.
<a id="unittest.fail"></a>
## unittest.fail
<pre>
unittest.fail(<a href="#unittest.fail-env">env</a>, <a href="#unittest.fail-msg">msg</a>)
</pre>
Unconditionally causes the current test to fail.
**PARAMETERS**
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="unittest.fail-env"></a>env | The test environment returned by `unittest.begin`. | none |
| <a id="unittest.fail-msg"></a>msg | The message to log describing the failure. | none |
<a id="unittest.make"></a>
## unittest.make
@ -464,9 +538,9 @@ Recall that names of test rules must end in `_test`.
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="unittest.make-impl"></a>impl | The implementation function of the unit test. | none |
| <a id="unittest.make-attrs"></a>attrs | An optional dictionary to supplement the attrs passed to the unit test's <code>rule()</code> constructor. | <code>{}</code> |
| <a id="unittest.make-doc"></a>doc | A description of the rule that can be extracted by documentation generating tools. | <code>""</code> |
| <a id="unittest.make-toolchains"></a>toolchains | An optional list to supplement the toolchains passed to the unit test's <code>rule()</code> constructor. | <code>[]</code> |
| <a id="unittest.make-attrs"></a>attrs | An optional dictionary to supplement the attrs passed to the unit test's `rule()` constructor. | `{}` |
| <a id="unittest.make-doc"></a>doc | A description of the rule that can be extracted by documentation generating tools. | `""` |
| <a id="unittest.make-toolchains"></a>toolchains | An optional list to supplement the toolchains passed to the unit test's `rule()` constructor. | `[]` |
**RETURNS**
@ -526,82 +600,7 @@ name each target.
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="unittest.suite-name"></a>name | The name of the <code>test_suite</code> target, and the prefix of all the test target names. | none |
| <a id="unittest.suite-test_rules"></a>test_rules | A list of test rules defines by <code>unittest.test</code>. | none |
<a id="unittest.begin"></a>
## unittest.begin
<pre>
unittest.begin(<a href="#unittest.begin-ctx">ctx</a>)
</pre>
Begins a unit test.
This should be the first function called in a unit test implementation
function. It initializes a "test environment" that is used to collect
assertion failures so that they can be reported and logged at the end of the
test.
**PARAMETERS**
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="unittest.begin-ctx"></a>ctx | The Starlark context. Pass the implementation function's <code>ctx</code> argument in verbatim. | none |
**RETURNS**
A test environment struct that must be passed to assertions and finally to
`unittest.end`. Do not rely on internal details about the fields in this
struct as it may change.
<a id="unittest.end"></a>
## unittest.end
<pre>
unittest.end(<a href="#unittest.end-env">env</a>)
</pre>
Ends a unit test and logs the results.
This must be called and returned at the end of a unit test implementation function so
that the results are reported.
**PARAMETERS**
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="unittest.end-env"></a>env | The test environment returned by <code>unittest.begin</code>. | none |
**RETURNS**
A list of providers needed to automatically register the test result.
<a id="unittest.fail"></a>
## unittest.fail
<pre>
unittest.fail(<a href="#unittest.fail-env">env</a>, <a href="#unittest.fail-msg">msg</a>)
</pre>
Unconditionally causes the current test to fail.
**PARAMETERS**
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="unittest.fail-env"></a>env | The test environment returned by <code>unittest.begin</code>. | none |
| <a id="unittest.fail-msg"></a>msg | The message to log describing the failure. | none |
| <a id="unittest.suite-name"></a>name | The name of the `test_suite` target, and the prefix of all the test target names. | none |
| <a id="unittest.suite-test_rules"></a>test_rules | A list of test rules defines by `unittest.test`. | none |

116
docs/versions_doc.md
View File

@ -2,46 +2,6 @@
Skylib module containing functions for checking Bazel versions.
<a id="versions.get"></a>
## versions.get
<pre>
versions.get()
</pre>
Returns the current Bazel version
<a id="versions.parse"></a>
## versions.parse
<pre>
versions.parse(<a href="#versions.parse-bazel_version">bazel_version</a>)
</pre>
Parses a version string into a 3-tuple of ints
int tuples can be compared directly using binary operators (&lt;, &gt;).
For a development build of Bazel, this returns an unspecified version tuple
that compares higher than any released version.
**PARAMETERS**
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="versions.parse-bazel_version"></a>bazel_version | the Bazel version string | none |
**RETURNS**
An int 3-tuple of a (major, minor, patch) version.
<a id="versions.check"></a>
## versions.check
@ -58,31 +18,20 @@ Check that the version of Bazel is valid within the specified range.
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="versions.check-minimum_bazel_version"></a>minimum_bazel_version | minimum version of Bazel expected | none |
| <a id="versions.check-maximum_bazel_version"></a>maximum_bazel_version | maximum version of Bazel expected | <code>None</code> |
| <a id="versions.check-bazel_version"></a>bazel_version | the version of Bazel to check. Used for testing, defaults to native.bazel_version | <code>None</code> |
| <a id="versions.check-maximum_bazel_version"></a>maximum_bazel_version | maximum version of Bazel expected | `None` |
| <a id="versions.check-bazel_version"></a>bazel_version | the version of Bazel to check. Used for testing, defaults to native.bazel_version | `None` |
<a id="versions.is_at_most"></a>
<a id="versions.get"></a>
## versions.is_at_most
## versions.get
<pre>
versions.is_at_most(<a href="#versions.is_at_most-threshold">threshold</a>, <a href="#versions.is_at_most-version">version</a>)
versions.get()
</pre>
Check that a version is lower or equals to a threshold.
Returns the current Bazel version
**PARAMETERS**
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="versions.is_at_most-threshold"></a>threshold | the maximum version string | none |
| <a id="versions.is_at_most-version"></a>version | the version string to be compared to the threshold | none |
**RETURNS**
True if version &lt;= threshold.
<a id="versions.is_at_least"></a>
@ -105,6 +54,57 @@ Check that a version is higher or equals to a threshold.
**RETURNS**
True if version &gt;= threshold.
True if version >= threshold.
<a id="versions.is_at_most"></a>
## versions.is_at_most
<pre>
versions.is_at_most(<a href="#versions.is_at_most-threshold">threshold</a>, <a href="#versions.is_at_most-version">version</a>)
</pre>
Check that a version is lower or equals to a threshold.
**PARAMETERS**
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="versions.is_at_most-threshold"></a>threshold | the maximum version string | none |
| <a id="versions.is_at_most-version"></a>version | the version string to be compared to the threshold | none |
**RETURNS**
True if version <= threshold.
<a id="versions.parse"></a>
## versions.parse
<pre>
versions.parse(<a href="#versions.parse-bazel_version">bazel_version</a>)
</pre>
Parses a version string into a 3-tuple of ints
int tuples can be compared directly using binary operators (<, >).
For a development build of Bazel, this returns an unspecified version tuple
that compares higher than any released version.
**PARAMETERS**
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="versions.parse-bazel_version"></a>bazel_version | the Bazel version string | none |
**RETURNS**
An int 3-tuple of a (major, minor, patch) version.

9
docs/write_file_doc.md
View File

@ -9,7 +9,6 @@ The rules generated by the macro do not use Bash or any other shell to write the
file. Instead they use Starlark's built-in file writing action
(ctx.actions.write).
<a id="write_file"></a>
## write_file
@ -27,9 +26,9 @@ Creates a UTF-8 encoded text file.
| :------------- | :------------- | :------------- |
| <a id="write_file-name"></a>name | Name of the rule. | none |
| <a id="write_file-out"></a>out | Path of the output file, relative to this package. | none |
| <a id="write_file-content"></a>content | A list of strings. Lines of text, the contents of the file. Newlines are added automatically after every line except the last one. | <code>[]</code> |
| <a id="write_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. | <code>False</code> |
| <a id="write_file-newline"></a>newline | one of ["auto", "unix", "windows"]: line endings to use. "auto" for platform-determined, "unix" for LF, and "windows" for CRLF. | <code>"auto"</code> |
| <a id="write_file-kwargs"></a>kwargs | further keyword arguments, e.g. <code>visibility</code> | none |
| <a id="write_file-content"></a>content | A list of strings. Lines of text, the contents of the file. Newlines are added automatically after every line except the last one. | `[]` |
| <a id="write_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. | `False` |
| <a id="write_file-newline"></a>newline | one of ["auto", "unix", "windows"]: line endings to use. "auto" for platform-determined, "unix" for LF, and "windows" for CRLF. | `"auto"` |
| <a id="write_file-kwargs"></a>kwargs | further keyword arguments, e.g. `visibility` | none |

2
version.bzl
View File

@ -14,4 +14,4 @@
"""The version of bazel-skylib."""
# Keep in sync with MODULE.bazel and @bazel_skylib_gazelle_plugin//:MODULE.bazel
version = "1.5.0"
version = "1.6.0"