add documentation pages for rules/ and lib/
This commit is contained in:
Christopher Parsons
parent
a35b13a1c9
commit
8e2272129c
13
WORKSPACE
13
WORKSPACE
|
|
@ -3,3 +3,16 @@ workspace(name = "bazel_skylib")
|
|||
load(":workspace.bzl", "bazel_skylib_workspace")
|
||||
|
||||
bazel_skylib_workspace()
|
||||
|
||||
# Below this line is for documentation generation only,
|
||||
# and should thus not be included by dependencies on
|
||||
# bazel-skylib.
|
||||
|
||||
load("@bazel_tools//tools/build_defs/repo:git.bzl", "git_repository")
|
||||
git_repository(
|
||||
name = "io_bazel_skydoc",
|
||||
remote = "https://github.com/bazelbuild/skydoc.git",
|
||||
tag = "0.2.0",
|
||||
)
|
||||
load("@io_bazel_skydoc//skylark:skylark.bzl", "skydoc_repositories")
|
||||
skydoc_repositories()
|
||||
|
|
|
|||
|
|
@ -0,0 +1,95 @@
|
|||
load("@io_bazel_skydoc//stardoc:stardoc.bzl",
|
||||
"stardoc")
|
||||
|
||||
# Note that due to a bug in Bazel 0.22.0, these targets cannot be built without
|
||||
# the --experimental_remap_main_repo flag.
|
||||
stardoc(
|
||||
name = "build_test_docs",
|
||||
input = "//rules:build_test.bzl",
|
||||
out = "build_test_doc_gen.md",
|
||||
deps = ["//rules:build_test"],
|
||||
)
|
||||
|
||||
stardoc(
|
||||
name = "analysis_test_docs",
|
||||
input = "//rules:analysis_test.bzl",
|
||||
out = "analysis_test_doc_gen.md",
|
||||
)
|
||||
|
||||
stardoc(
|
||||
name = "collections_docs",
|
||||
input = "//lib:collections.bzl",
|
||||
out = "collections_doc_gen.md",
|
||||
deps = ["//lib:collections"],
|
||||
)
|
||||
|
||||
stardoc(
|
||||
name = "dicts_docs",
|
||||
input = "//lib:dicts.bzl",
|
||||
out = "dicts_doc_gen.md",
|
||||
deps = ["//lib:dicts"],
|
||||
)
|
||||
|
||||
stardoc(
|
||||
name = "partial_docs",
|
||||
input = "//lib:partial.bzl",
|
||||
out = "partial_doc_gen.md",
|
||||
deps = ["//lib:partial"],
|
||||
)
|
||||
|
||||
stardoc(
|
||||
name = "paths_docs",
|
||||
input = "//lib:paths.bzl",
|
||||
out = "paths_doc_gen.md",
|
||||
deps = ["//lib:paths"],
|
||||
)
|
||||
|
||||
stardoc(
|
||||
name = "selects_docs",
|
||||
input = "//lib:selects.bzl",
|
||||
out = "selects_doc_gen.md",
|
||||
deps = ["//lib:selects"],
|
||||
)
|
||||
|
||||
stardoc(
|
||||
name = "new_sets_docs",
|
||||
input = "//lib:new_sets.bzl",
|
||||
out = "new_sets_doc_gen.md",
|
||||
deps = ["//lib:new_sets"],
|
||||
)
|
||||
|
||||
stardoc(
|
||||
name = "shell_docs",
|
||||
input = "//lib:shell.bzl",
|
||||
out = "shell_doc_gen.md",
|
||||
deps = ["//lib:shell"],
|
||||
)
|
||||
|
||||
stardoc(
|
||||
name = "structs_docs",
|
||||
input = "//lib:structs.bzl",
|
||||
out = "structs_doc_gen.md",
|
||||
deps = ["//lib:structs"],
|
||||
)
|
||||
|
||||
stardoc(
|
||||
name = "types_docs",
|
||||
input = "//lib:types.bzl",
|
||||
out = "types_doc_gen.md",
|
||||
deps = ["//lib:types"],
|
||||
)
|
||||
|
||||
stardoc(
|
||||
name = "unittest_docs",
|
||||
input = "//lib:unittest.bzl",
|
||||
out = "unittest_doc_gen.md",
|
||||
deps = ["//lib:unittest"],
|
||||
)
|
||||
|
||||
stardoc(
|
||||
name = "versions_docs",
|
||||
input = "//lib:versions.bzl",
|
||||
out = "versions_doc_gen.md",
|
||||
deps = ["//lib:versions"],
|
||||
)
|
||||
|
||||
|
|
@ -0,0 +1,88 @@
|
|||
<a name="#analysis_test"></a>
|
||||
## analysis_test
|
||||
|
||||
<pre>
|
||||
analysis_test(<a href="#analysis_test-name">name</a>, <a href="#analysis_test-targets">targets</a>)
|
||||
</pre>
|
||||
|
||||
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.
|
||||
|
||||
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:
|
||||
|
||||
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.
|
||||
|
||||
|
||||
### Attributes
|
||||
|
||||
<table class="params-table">
|
||||
<colgroup>
|
||||
<col class="col-param" />
|
||||
<col class="col-description" />
|
||||
</colgroup>
|
||||
<tbody>
|
||||
<tr id="analysis_test-name">
|
||||
<td><code>name</code></td>
|
||||
<td>
|
||||
<a href="https://bazel.build/docs/build-ref.html#name">Name</a>; required
|
||||
<p>
|
||||
A unique name for this target.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr id="analysis_test-targets">
|
||||
<td><code>targets</code></td>
|
||||
<td>
|
||||
<a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a>; required
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
|
||||
## _analysis_test_impl
|
||||
|
||||
<pre>
|
||||
_analysis_test_impl(<a href="#_analysis_test_impl-ctx">ctx</a>)
|
||||
</pre>
|
||||
|
||||
Implementation function for analysis_test.
|
||||
|
||||
### Parameters
|
||||
|
||||
<table class="params-table">
|
||||
<colgroup>
|
||||
<col class="col-param" />
|
||||
<col class="col-description" />
|
||||
</colgroup>
|
||||
<tbody>
|
||||
<tr id="_analysis_test_impl-ctx>
|
||||
<td><code>ctx</code></td>
|
||||
<td>
|
||||
required.
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
|
||||
|
|
@ -0,0 +1,62 @@
|
|||
## build_test
|
||||
|
||||
<pre>
|
||||
build_test(<a href="#build_test-name">name</a>, <a href="#build_test-targets">targets</a>, <a href="#build_test-kwargs">kwargs</a>)
|
||||
</pre>
|
||||
|
||||
Test rule checking that other targets build.
|
||||
|
||||
This works not by an instance of this test failing, but instead by
|
||||
the targets it depends on failing to build, and hence failing
|
||||
the attempt to run this test.
|
||||
|
||||
NOTE: At the moment, this won't work on Windows; but someone adding
|
||||
support would be welcomed.
|
||||
|
||||
Typical usage:
|
||||
|
||||
load("@bazel_skylib//rules:build_test.bzl", "build_test")
|
||||
build_test(
|
||||
name = "my_build_test",
|
||||
targets = [
|
||||
"//some/package:rule",
|
||||
],
|
||||
)
|
||||
|
||||
|
||||
### Parameters
|
||||
|
||||
<table class="params-table">
|
||||
<colgroup>
|
||||
<col class="col-param" />
|
||||
<col class="col-description" />
|
||||
</colgroup>
|
||||
<tbody>
|
||||
<tr id="build_test-name>
|
||||
<td><code>name</code></td>
|
||||
<td>
|
||||
required.
|
||||
<p>
|
||||
The name of the test rule.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr id="build_test-targets>
|
||||
<td><code>targets</code></td>
|
||||
<td>
|
||||
required.
|
||||
<p>
|
||||
A list of targets to ensure build.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr id="build_test-kwargs>
|
||||
<td><code>kwargs</code></td>
|
||||
<td>
|
||||
required.
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
|
||||
|
|
@ -0,0 +1,108 @@
|
|||
## _after_each
|
||||
|
||||
<pre>
|
||||
_after_each(<a href="#_after_each-separator">separator</a>, <a href="#_after_each-iterable">iterable</a>)
|
||||
</pre>
|
||||
|
||||
Inserts `separator` after each item in `iterable`.
|
||||
|
||||
### Parameters
|
||||
|
||||
<table class="params-table">
|
||||
<colgroup>
|
||||
<col class="col-param" />
|
||||
<col class="col-description" />
|
||||
</colgroup>
|
||||
<tbody>
|
||||
<tr id="_after_each-separator>
|
||||
<td><code>separator</code></td>
|
||||
<td>
|
||||
required.
|
||||
<p>
|
||||
The value to insert after each item in `iterable`.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr id="_after_each-iterable>
|
||||
<td><code>iterable</code></td>
|
||||
<td>
|
||||
required.
|
||||
<p>
|
||||
The list into which to intersperse the separator.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
|
||||
## _before_each
|
||||
|
||||
<pre>
|
||||
_before_each(<a href="#_before_each-separator">separator</a>, <a href="#_before_each-iterable">iterable</a>)
|
||||
</pre>
|
||||
|
||||
Inserts `separator` before each item in `iterable`.
|
||||
|
||||
### Parameters
|
||||
|
||||
<table class="params-table">
|
||||
<colgroup>
|
||||
<col class="col-param" />
|
||||
<col class="col-description" />
|
||||
</colgroup>
|
||||
<tbody>
|
||||
<tr id="_before_each-separator>
|
||||
<td><code>separator</code></td>
|
||||
<td>
|
||||
required.
|
||||
<p>
|
||||
The value to insert before each item in `iterable`.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr id="_before_each-iterable>
|
||||
<td><code>iterable</code></td>
|
||||
<td>
|
||||
required.
|
||||
<p>
|
||||
The list into which to intersperse the separator.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
|
||||
## _uniq
|
||||
|
||||
<pre>
|
||||
_uniq(<a href="#_uniq-iterable">iterable</a>)
|
||||
</pre>
|
||||
|
||||
Returns a list of unique elements in `iterable`.
|
||||
|
||||
Requires all the elements to be hashable.
|
||||
|
||||
|
||||
### Parameters
|
||||
|
||||
<table class="params-table">
|
||||
<colgroup>
|
||||
<col class="col-param" />
|
||||
<col class="col-description" />
|
||||
</colgroup>
|
||||
<tbody>
|
||||
<tr id="_uniq-iterable>
|
||||
<td><code>iterable</code></td>
|
||||
<td>
|
||||
required.
|
||||
<p>
|
||||
An iterable to filter.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
|
||||
|
|
@ -0,0 +1,35 @@
|
|||
## _add
|
||||
|
||||
<pre>
|
||||
_add(<a href="#_add-dictionaries">dictionaries</a>)
|
||||
</pre>
|
||||
|
||||
Returns a new `dict` that has all the entries of the given dictionaries.
|
||||
|
||||
If the same key is present in more than one of the input dictionaries, the
|
||||
last of them in the argument list overrides any earlier ones.
|
||||
|
||||
This function is designed to take zero or one arguments as well as multiple
|
||||
dictionaries, so that it follows arithmetic identities and callers can avoid
|
||||
special cases for their inputs: the sum of zero dictionaries is the empty
|
||||
dictionary, and the sum of a single dictionary is a copy of itself.
|
||||
|
||||
|
||||
### Parameters
|
||||
|
||||
<table class="params-table">
|
||||
<colgroup>
|
||||
<col class="col-param" />
|
||||
<col class="col-description" />
|
||||
</colgroup>
|
||||
<tbody>
|
||||
<tr id="_add-dictionaries>
|
||||
<td><code>dictionaries</code></td>
|
||||
<td>
|
||||
required.
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
|
||||
|
|
@ -0,0 +1,525 @@
|
|||
## _contains
|
||||
|
||||
<pre>
|
||||
_contains(<a href="#_contains-a">a</a>, <a href="#_contains-e">e</a>)
|
||||
</pre>
|
||||
|
||||
Checks for the existence of an element in a set.
|
||||
|
||||
### Parameters
|
||||
|
||||
<table class="params-table">
|
||||
<colgroup>
|
||||
<col class="col-param" />
|
||||
<col class="col-description" />
|
||||
</colgroup>
|
||||
<tbody>
|
||||
<tr id="_contains-a>
|
||||
<td><code>a</code></td>
|
||||
<td>
|
||||
required.
|
||||
<p>
|
||||
A set, as returned by `sets.make()`.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr id="_contains-e>
|
||||
<td><code>e</code></td>
|
||||
<td>
|
||||
required.
|
||||
<p>
|
||||
The element to look for.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
|
||||
## _copy
|
||||
|
||||
<pre>
|
||||
_copy(<a href="#_copy-s">s</a>)
|
||||
</pre>
|
||||
|
||||
Creates a new set from another set.
|
||||
|
||||
### Parameters
|
||||
|
||||
<table class="params-table">
|
||||
<colgroup>
|
||||
<col class="col-param" />
|
||||
<col class="col-description" />
|
||||
</colgroup>
|
||||
<tbody>
|
||||
<tr id="_copy-s>
|
||||
<td><code>s</code></td>
|
||||
<td>
|
||||
required.
|
||||
<p>
|
||||
A set, as returned by `sets.make()`.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
|
||||
## _difference
|
||||
|
||||
<pre>
|
||||
_difference(<a href="#_difference-a">a</a>, <a href="#_difference-b">b</a>)
|
||||
</pre>
|
||||
|
||||
Returns the elements in `a` that are not in `b`.
|
||||
|
||||
### Parameters
|
||||
|
||||
<table class="params-table">
|
||||
<colgroup>
|
||||
<col class="col-param" />
|
||||
<col class="col-description" />
|
||||
</colgroup>
|
||||
<tbody>
|
||||
<tr id="_difference-a>
|
||||
<td><code>a</code></td>
|
||||
<td>
|
||||
required.
|
||||
<p>
|
||||
A set, as returned by `sets.make()`.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr id="_difference-b>
|
||||
<td><code>b</code></td>
|
||||
<td>
|
||||
required.
|
||||
<p>
|
||||
A set, as returned by `sets.make()`.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
|
||||
## _disjoint
|
||||
|
||||
<pre>
|
||||
_disjoint(<a href="#_disjoint-a">a</a>, <a href="#_disjoint-b">b</a>)
|
||||
</pre>
|
||||
|
||||
Returns whether two sets are disjoint.
|
||||
|
||||
Two sets are disjoint if they have no elements in common.
|
||||
|
||||
|
||||
### Parameters
|
||||
|
||||
<table class="params-table">
|
||||
<colgroup>
|
||||
<col class="col-param" />
|
||||
<col class="col-description" />
|
||||
</colgroup>
|
||||
<tbody>
|
||||
<tr id="_disjoint-a>
|
||||
<td><code>a</code></td>
|
||||
<td>
|
||||
required.
|
||||
<p>
|
||||
A set, as returned by `sets.make()`.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr id="_disjoint-b>
|
||||
<td><code>b</code></td>
|
||||
<td>
|
||||
required.
|
||||
<p>
|
||||
A set, as returned by `sets.make()`.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
|
||||
## _get_shorter_and_longer
|
||||
|
||||
<pre>
|
||||
_get_shorter_and_longer(<a href="#_get_shorter_and_longer-a">a</a>, <a href="#_get_shorter_and_longer-b">b</a>)
|
||||
</pre>
|
||||
|
||||
Returns two sets in the order of shortest and longest.
|
||||
|
||||
### Parameters
|
||||
|
||||
<table class="params-table">
|
||||
<colgroup>
|
||||
<col class="col-param" />
|
||||
<col class="col-description" />
|
||||
</colgroup>
|
||||
<tbody>
|
||||
<tr id="_get_shorter_and_longer-a>
|
||||
<td><code>a</code></td>
|
||||
<td>
|
||||
required.
|
||||
<p>
|
||||
A set, as returned by `sets.make()`.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr id="_get_shorter_and_longer-b>
|
||||
<td><code>b</code></td>
|
||||
<td>
|
||||
required.
|
||||
<p>
|
||||
A set, as returned by `sets.make()`.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
|
||||
## _insert
|
||||
|
||||
<pre>
|
||||
_insert(<a href="#_insert-s">s</a>, <a href="#_insert-e">e</a>)
|
||||
</pre>
|
||||
|
||||
Inserts an element into the set.
|
||||
|
||||
Element must be hashable. This mutates the orginal set.
|
||||
|
||||
|
||||
### Parameters
|
||||
|
||||
<table class="params-table">
|
||||
<colgroup>
|
||||
<col class="col-param" />
|
||||
<col class="col-description" />
|
||||
</colgroup>
|
||||
<tbody>
|
||||
<tr id="_insert-s>
|
||||
<td><code>s</code></td>
|
||||
<td>
|
||||
required.
|
||||
<p>
|
||||
A set, as returned by `sets.make()`.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr id="_insert-e>
|
||||
<td><code>e</code></td>
|
||||
<td>
|
||||
required.
|
||||
<p>
|
||||
The element to be inserted.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
|
||||
## _intersection
|
||||
|
||||
<pre>
|
||||
_intersection(<a href="#_intersection-a">a</a>, <a href="#_intersection-b">b</a>)
|
||||
</pre>
|
||||
|
||||
Returns the intersection of two sets.
|
||||
|
||||
### Parameters
|
||||
|
||||
<table class="params-table">
|
||||
<colgroup>
|
||||
<col class="col-param" />
|
||||
<col class="col-description" />
|
||||
</colgroup>
|
||||
<tbody>
|
||||
<tr id="_intersection-a>
|
||||
<td><code>a</code></td>
|
||||
<td>
|
||||
required.
|
||||
<p>
|
||||
A set, as returned by `sets.make()`.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr id="_intersection-b>
|
||||
<td><code>b</code></td>
|
||||
<td>
|
||||
required.
|
||||
<p>
|
||||
A set, as returned by `sets.make()`.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
|
||||
## _is_equal
|
||||
|
||||
<pre>
|
||||
_is_equal(<a href="#_is_equal-a">a</a>, <a href="#_is_equal-b">b</a>)
|
||||
</pre>
|
||||
|
||||
Returns whether two sets are equal.
|
||||
|
||||
### Parameters
|
||||
|
||||
<table class="params-table">
|
||||
<colgroup>
|
||||
<col class="col-param" />
|
||||
<col class="col-description" />
|
||||
</colgroup>
|
||||
<tbody>
|
||||
<tr id="_is_equal-a>
|
||||
<td><code>a</code></td>
|
||||
<td>
|
||||
required.
|
||||
<p>
|
||||
A set, as returned by `sets.make()`.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr id="_is_equal-b>
|
||||
<td><code>b</code></td>
|
||||
<td>
|
||||
required.
|
||||
<p>
|
||||
A set, as returned by `sets.make()`.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
|
||||
## _is_subset
|
||||
|
||||
<pre>
|
||||
_is_subset(<a href="#_is_subset-a">a</a>, <a href="#_is_subset-b">b</a>)
|
||||
</pre>
|
||||
|
||||
Returns whether `a` is a subset of `b`.
|
||||
|
||||
### Parameters
|
||||
|
||||
<table class="params-table">
|
||||
<colgroup>
|
||||
<col class="col-param" />
|
||||
<col class="col-description" />
|
||||
</colgroup>
|
||||
<tbody>
|
||||
<tr id="_is_subset-a>
|
||||
<td><code>a</code></td>
|
||||
<td>
|
||||
required.
|
||||
<p>
|
||||
A set, as returned by `sets.make()`.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr id="_is_subset-b>
|
||||
<td><code>b</code></td>
|
||||
<td>
|
||||
required.
|
||||
<p>
|
||||
A set, as returned by `sets.make()`.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
|
||||
## _length
|
||||
|
||||
<pre>
|
||||
_length(<a href="#_length-s">s</a>)
|
||||
</pre>
|
||||
|
||||
Returns the number of elements in a set.
|
||||
|
||||
### Parameters
|
||||
|
||||
<table class="params-table">
|
||||
<colgroup>
|
||||
<col class="col-param" />
|
||||
<col class="col-description" />
|
||||
</colgroup>
|
||||
<tbody>
|
||||
<tr id="_length-s>
|
||||
<td><code>s</code></td>
|
||||
<td>
|
||||
required.
|
||||
<p>
|
||||
A set, as returned by `sets.make()`.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
|
||||
## _make
|
||||
|
||||
<pre>
|
||||
_make(<a href="#_make-elements">elements</a>)
|
||||
</pre>
|
||||
|
||||
Creates a new set.
|
||||
|
||||
All elements must be hashable.
|
||||
|
||||
|
||||
### Parameters
|
||||
|
||||
<table class="params-table">
|
||||
<colgroup>
|
||||
<col class="col-param" />
|
||||
<col class="col-description" />
|
||||
</colgroup>
|
||||
<tbody>
|
||||
<tr id="_make-elements>
|
||||
<td><code>elements</code></td>
|
||||
<td>
|
||||
optional. default is <code>None</code>
|
||||
<p>
|
||||
Optional sequence to construct the set out of.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
|
||||
## _remove
|
||||
|
||||
<pre>
|
||||
_remove(<a href="#_remove-s">s</a>, <a href="#_remove-e">e</a>)
|
||||
</pre>
|
||||
|
||||
Removes an element from the set.
|
||||
|
||||
Element must be hashable. This mutates the orginal set.
|
||||
|
||||
|
||||
### Parameters
|
||||
|
||||
<table class="params-table">
|
||||
<colgroup>
|
||||
<col class="col-param" />
|
||||
<col class="col-description" />
|
||||
</colgroup>
|
||||
<tbody>
|
||||
<tr id="_remove-s>
|
||||
<td><code>s</code></td>
|
||||
<td>
|
||||
required.
|
||||
<p>
|
||||
A set, as returned by `sets.make()`.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr id="_remove-e>
|
||||
<td><code>e</code></td>
|
||||
<td>
|
||||
required.
|
||||
<p>
|
||||
The element to be removed.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
|
||||
## _repr
|
||||
|
||||
<pre>
|
||||
_repr(<a href="#_repr-s">s</a>)
|
||||
</pre>
|
||||
|
||||
Returns a string value representing the set.
|
||||
|
||||
### Parameters
|
||||
|
||||
<table class="params-table">
|
||||
<colgroup>
|
||||
<col class="col-param" />
|
||||
<col class="col-description" />
|
||||
</colgroup>
|
||||
<tbody>
|
||||
<tr id="_repr-s>
|
||||
<td><code>s</code></td>
|
||||
<td>
|
||||
required.
|
||||
<p>
|
||||
A set, as returned by `sets.make()`.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
|
||||
## _to_list
|
||||
|
||||
<pre>
|
||||
_to_list(<a href="#_to_list-s">s</a>)
|
||||
</pre>
|
||||
|
||||
Creates a list from the values in the set.
|
||||
|
||||
### Parameters
|
||||
|
||||
<table class="params-table">
|
||||
<colgroup>
|
||||
<col class="col-param" />
|
||||
<col class="col-description" />
|
||||
</colgroup>
|
||||
<tbody>
|
||||
<tr id="_to_list-s>
|
||||
<td><code>s</code></td>
|
||||
<td>
|
||||
required.
|
||||
<p>
|
||||
A set, as returned by `sets.make()`.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
|
||||
## _union
|
||||
|
||||
<pre>
|
||||
_union(<a href="#_union-args">args</a>)
|
||||
</pre>
|
||||
|
||||
Returns the union of several sets.
|
||||
|
||||
### Parameters
|
||||
|
||||
<table class="params-table">
|
||||
<colgroup>
|
||||
<col class="col-param" />
|
||||
<col class="col-description" />
|
||||
</colgroup>
|
||||
<tbody>
|
||||
<tr id="_union-args>
|
||||
<td><code>args</code></td>
|
||||
<td>
|
||||
required.
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
|
||||
|
|
@ -0,0 +1,156 @@
|
|||
## _call
|
||||
|
||||
<pre>
|
||||
_call(<a href="#_call-partial">partial</a>, <a href="#_call-args">args</a>, <a href="#_call-kwargs">kwargs</a>)
|
||||
</pre>
|
||||
|
||||
Calls a partial created using `make`.
|
||||
|
||||
### Parameters
|
||||
|
||||
<table class="params-table">
|
||||
<colgroup>
|
||||
<col class="col-param" />
|
||||
<col class="col-description" />
|
||||
</colgroup>
|
||||
<tbody>
|
||||
<tr id="_call-partial>
|
||||
<td><code>partial</code></td>
|
||||
<td>
|
||||
required.
|
||||
<p>
|
||||
The partial to be called.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr id="_call-args>
|
||||
<td><code>args</code></td>
|
||||
<td>
|
||||
required.
|
||||
</td>
|
||||
</tr>
|
||||
<tr id="_call-kwargs>
|
||||
<td><code>kwargs</code></td>
|
||||
<td>
|
||||
required.
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
|
||||
## _make
|
||||
|
||||
<pre>
|
||||
_make(<a href="#_make-func">func</a>, <a href="#_make-args">args</a>, <a href="#_make-kwargs">kwargs</a>)
|
||||
</pre>
|
||||
|
||||
Creates a partial that can be called using `call`.
|
||||
|
||||
A partial can have args assigned to it at the make site, and can have args
|
||||
passed to it at the call sites.
|
||||
|
||||
A partial 'function' can be defined with positional args and kwargs:
|
||||
|
||||
# function with no args
|
||||
def function1():
|
||||
...
|
||||
|
||||
# function with 2 args
|
||||
def function2(arg1, arg2):
|
||||
...
|
||||
|
||||
# function with 2 args and keyword args
|
||||
def function3(arg1, arg2, x, y):
|
||||
...
|
||||
|
||||
The positional args passed to the function are the args passed into make
|
||||
followed by any additional positional args given to call. The below example
|
||||
illustrates a function with two positional arguments where one is supplied by
|
||||
make and the other by call:
|
||||
|
||||
# function demonstrating 1 arg at make site, and 1 arg at call site
|
||||
def _foo(make_arg1, func_arg1):
|
||||
print(make_arg1 + " " + func_arg1 + "!")
|
||||
|
||||
For example:
|
||||
|
||||
hi_func = partial.make(_foo, "Hello")
|
||||
bye_func = partial.make(_foo, "Goodbye")
|
||||
partial.call(hi_func, "Jennifer")
|
||||
partial.call(hi_func, "Dave")
|
||||
partial.call(bye_func, "Jennifer")
|
||||
partial.call(bye_func, "Dave")
|
||||
|
||||
prints:
|
||||
|
||||
"Hello, Jennifer!"
|
||||
"Hello, Dave!"
|
||||
"Goodbye, Jennifer!"
|
||||
"Goodbye, Dave!"
|
||||
|
||||
The keyword args given to the function are the kwargs passed into make
|
||||
unioned with the keyword args given to call. In case of a conflict, the
|
||||
keyword args given to call take precedence. This allows you to set a default
|
||||
value for keyword arguments and override it at the call site.
|
||||
|
||||
Example with a make site arg, a call site arg, a make site kwarg and a
|
||||
call site kwarg:
|
||||
|
||||
def _foo(make_arg1, call_arg1, make_location, call_location):
|
||||
print(make_arg1 + " is from " + make_location + " and " +
|
||||
call_arg1 + " is from " + call_location + "!")
|
||||
|
||||
func = partial.make(_foo, "Ben", make_location="Hollywood")
|
||||
partial.call(func, "Jennifer", call_location="Denver")
|
||||
|
||||
Prints "Ben is from Hollywood and Jennifer is from Denver!".
|
||||
|
||||
partial.call(func, "Jennifer", make_location="LA", call_location="Denver")
|
||||
|
||||
Prints "Ben is from LA and Jennifer is from Denver!".
|
||||
|
||||
Note that keyword args may not overlap with positional args, regardless of
|
||||
whether they are given during the make or call step. For instance, you can't
|
||||
do:
|
||||
|
||||
def foo(x):
|
||||
pass
|
||||
|
||||
func = partial.make(foo, 1)
|
||||
partial.call(func, x=2)
|
||||
|
||||
|
||||
### Parameters
|
||||
|
||||
<table class="params-table">
|
||||
<colgroup>
|
||||
<col class="col-param" />
|
||||
<col class="col-description" />
|
||||
</colgroup>
|
||||
<tbody>
|
||||
<tr id="_make-func>
|
||||
<td><code>func</code></td>
|
||||
<td>
|
||||
required.
|
||||
<p>
|
||||
The function to be called.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr id="_make-args>
|
||||
<td><code>args</code></td>
|
||||
<td>
|
||||
required.
|
||||
</td>
|
||||
</tr>
|
||||
<tr id="_make-kwargs>
|
||||
<td><code>kwargs</code></td>
|
||||
<td>
|
||||
required.
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
|
||||
|
|
@ -0,0 +1,308 @@
|
|||
## _basename
|
||||
|
||||
<pre>
|
||||
_basename(<a href="#_basename-p">p</a>)
|
||||
</pre>
|
||||
|
||||
Returns the basename (i.e., the file portion) of a path.
|
||||
|
||||
Note that if `p` ends with a slash, this function returns an empty string.
|
||||
This matches the behavior of Python's `os.path.basename`, but differs from
|
||||
the Unix `basename` command (which would return the path segment preceding
|
||||
the final slash).
|
||||
|
||||
|
||||
### Parameters
|
||||
|
||||
<table class="params-table">
|
||||
<colgroup>
|
||||
<col class="col-param" />
|
||||
<col class="col-description" />
|
||||
</colgroup>
|
||||
<tbody>
|
||||
<tr id="_basename-p>
|
||||
<td><code>p</code></td>
|
||||
<td>
|
||||
required.
|
||||
<p>
|
||||
The path whose basename should be returned.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
|
||||
## _dirname
|
||||
|
||||
<pre>
|
||||
_dirname(<a href="#_dirname-p">p</a>)
|
||||
</pre>
|
||||
|
||||
Returns the dirname of a path.
|
||||
|
||||
The dirname is the portion of `p` up to but not including the file portion
|
||||
(i.e., the basename). Any slashes immediately preceding the basename are not
|
||||
included, unless omitting them would make the dirname empty.
|
||||
|
||||
|
||||
### Parameters
|
||||
|
||||
<table class="params-table">
|
||||
<colgroup>
|
||||
<col class="col-param" />
|
||||
<col class="col-description" />
|
||||
</colgroup>
|
||||
<tbody>
|
||||
<tr id="_dirname-p>
|
||||
<td><code>p</code></td>
|
||||
<td>
|
||||
required.
|
||||
<p>
|
||||
The path whose dirname should be returned.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
|
||||
## _is_absolute
|
||||
|
||||
<pre>
|
||||
_is_absolute(<a href="#_is_absolute-path">path</a>)
|
||||
</pre>
|
||||
|
||||
Returns `True` if `path` is an absolute path.
|
||||
|
||||
### Parameters
|
||||
|
||||
<table class="params-table">
|
||||
<colgroup>
|
||||
<col class="col-param" />
|
||||
<col class="col-description" />
|
||||
</colgroup>
|
||||
<tbody>
|
||||
<tr id="_is_absolute-path>
|
||||
<td><code>path</code></td>
|
||||
<td>
|
||||
required.
|
||||
<p>
|
||||
A path (which is a string).
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
|
||||
## _join
|
||||
|
||||
<pre>
|
||||
_join(<a href="#_join-path">path</a>, <a href="#_join-others">others</a>)
|
||||
</pre>
|
||||
|
||||
Joins one or more path components intelligently.
|
||||
|
||||
This function mimics the behavior of Python's `os.path.join` function on POSIX
|
||||
platform. It returns the concatenation of `path` and any members of `others`,
|
||||
inserting directory separators before each component except the first. The
|
||||
separator is not inserted if the path up until that point is either empty or
|
||||
already ends in a separator.
|
||||
|
||||
If any component is an absolute path, all previous components are discarded.
|
||||
|
||||
|
||||
### Parameters
|
||||
|
||||
<table class="params-table">
|
||||
<colgroup>
|
||||
<col class="col-param" />
|
||||
<col class="col-description" />
|
||||
</colgroup>
|
||||
<tbody>
|
||||
<tr id="_join-path>
|
||||
<td><code>path</code></td>
|
||||
<td>
|
||||
required.
|
||||
<p>
|
||||
A path segment.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr id="_join-others>
|
||||
<td><code>others</code></td>
|
||||
<td>
|
||||
required.
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
|
||||
## _normalize
|
||||
|
||||
<pre>
|
||||
_normalize(<a href="#_normalize-path">path</a>)
|
||||
</pre>
|
||||
|
||||
Normalizes a path, eliminating double slashes and other redundant segments.
|
||||
|
||||
This function mimics the behavior of Python's `os.path.normpath` function on
|
||||
POSIX platforms; specifically:
|
||||
|
||||
- If the entire path is empty, "." is returned.
|
||||
- All "." segments are removed, unless the path consists solely of a single
|
||||
"." segment.
|
||||
- Trailing slashes are removed, unless the path consists solely of slashes.
|
||||
- ".." segments are removed as long as there are corresponding segments
|
||||
earlier in the path to remove; otherwise, they are retained as leading ".."
|
||||
segments.
|
||||
- Single and double leading slashes are preserved, but three or more leading
|
||||
slashes are collapsed into a single leading slash.
|
||||
- Multiple adjacent internal slashes are collapsed into a single slash.
|
||||
|
||||
|
||||
### Parameters
|
||||
|
||||
<table class="params-table">
|
||||
<colgroup>
|
||||
<col class="col-param" />
|
||||
<col class="col-description" />
|
||||
</colgroup>
|
||||
<tbody>
|
||||
<tr id="_normalize-path>
|
||||
<td><code>path</code></td>
|
||||
<td>
|
||||
required.
|
||||
<p>
|
||||
A path.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
|
||||
## _relativize
|
||||
|
||||
<pre>
|
||||
_relativize(<a href="#_relativize-path">path</a>, <a href="#_relativize-start">start</a>)
|
||||
</pre>
|
||||
|
||||
Returns the portion of `path` that is relative to `start`.
|
||||
|
||||
Because we do not have access to the underlying file system, this
|
||||
implementation differs slightly from Python's `os.path.relpath` in that it
|
||||
will fail if `path` is not beneath `start` (rather than use parent segments to
|
||||
walk up to the common file system root).
|
||||
|
||||
Relativizing paths that start with parent directory references only works if
|
||||
the path both start with the same initial parent references.
|
||||
|
||||
|
||||
### Parameters
|
||||
|
||||
<table class="params-table">
|
||||
<colgroup>
|
||||
<col class="col-param" />
|
||||
<col class="col-description" />
|
||||
</colgroup>
|
||||
<tbody>
|
||||
<tr id="_relativize-path>
|
||||
<td><code>path</code></td>
|
||||
<td>
|
||||
required.
|
||||
<p>
|
||||
The path to relativize.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr id="_relativize-start>
|
||||
<td><code>start</code></td>
|
||||
<td>
|
||||
required.
|
||||
<p>
|
||||
The ancestor path against which to relativize.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
|
||||
## _replace_extension
|
||||
|
||||
<pre>
|
||||
_replace_extension(<a href="#_replace_extension-p">p</a>, <a href="#_replace_extension-new_extension">new_extension</a>)
|
||||
</pre>
|
||||
|
||||
Replaces the extension of the file at the end of a path.
|
||||
|
||||
If the path has no extension, the new extension is added to it.
|
||||
|
||||
|
||||
### Parameters
|
||||
|
||||
<table class="params-table">
|
||||
<colgroup>
|
||||
<col class="col-param" />
|
||||
<col class="col-description" />
|
||||
</colgroup>
|
||||
<tbody>
|
||||
<tr id="_replace_extension-p>
|
||||
<td><code>p</code></td>
|
||||
<td>
|
||||
required.
|
||||
<p>
|
||||
The path whose extension should be replaced.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr id="_replace_extension-new_extension>
|
||||
<td><code>new_extension</code></td>
|
||||
<td>
|
||||
required.
|
||||
<p>
|
||||
The new extension for the file. The new extension should
|
||||
begin with a dot if you want the new filename to have one.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
|
||||
## _split_extension
|
||||
|
||||
<pre>
|
||||
_split_extension(<a href="#_split_extension-p">p</a>)
|
||||
</pre>
|
||||
|
||||
Splits the path `p` into a tuple containing the root and extension.
|
||||
|
||||
Leading periods on the basename are ignored, so
|
||||
`path.split_extension(".bashrc")` returns `(".bashrc", "")`.
|
||||
|
||||
|
||||
### Parameters
|
||||
|
||||
<table class="params-table">
|
||||
<colgroup>
|
||||
<col class="col-param" />
|
||||
<col class="col-description" />
|
||||
</colgroup>
|
||||
<tbody>
|
||||
<tr id="_split_extension-p>
|
||||
<td><code>p</code></td>
|
||||
<td>
|
||||
required.
|
||||
<p>
|
||||
The path whose root and extension should be split.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
|
||||
|
|
@ -0,0 +1,87 @@
|
|||
## _with_or
|
||||
|
||||
<pre>
|
||||
_with_or(<a href="#_with_or-input_dict">input_dict</a>, <a href="#_with_or-no_match_error">no_match_error</a>)
|
||||
</pre>
|
||||
|
||||
Drop-in replacement for `select()` that supports ORed keys.
|
||||
|
||||
### Parameters
|
||||
|
||||
<table class="params-table">
|
||||
<colgroup>
|
||||
<col class="col-param" />
|
||||
<col class="col-description" />
|
||||
</colgroup>
|
||||
<tbody>
|
||||
<tr id="_with_or-input_dict>
|
||||
<td><code>input_dict</code></td>
|
||||
<td>
|
||||
required.
|
||||
<p>
|
||||
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 `...`.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr id="_with_or-no_match_error>
|
||||
<td><code>no_match_error</code></td>
|
||||
<td>
|
||||
optional. default is <code>""</code>
|
||||
<p>
|
||||
Optional custom error to report if no condition matches.
|
||||
|
||||
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.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
|
||||
## _with_or_dict
|
||||
|
||||
<pre>
|
||||
_with_or_dict(<a href="#_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
|
||||
|
||||
<table class="params-table">
|
||||
<colgroup>
|
||||
<col class="col-param" />
|
||||
<col class="col-description" />
|
||||
</colgroup>
|
||||
<tbody>
|
||||
<tr id="_with_or_dict-input_dict>
|
||||
<td><code>input_dict</code></td>
|
||||
<td>
|
||||
required.
|
||||
<p>
|
||||
Same as `with_or`.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
|
||||
|
|
@ -0,0 +1,71 @@
|
|||
## _array_literal
|
||||
|
||||
<pre>
|
||||
_array_literal(<a href="#_array_literal-iterable">iterable</a>)
|
||||
</pre>
|
||||
|
||||
Creates a string from a sequence that can be used as a shell array.
|
||||
|
||||
For example, `shell.array_literal(["a", "b", "c"])` would return the string
|
||||
`("a" "b" "c")`, which can be used in a shell script wherever an array
|
||||
literal is needed.
|
||||
|
||||
Note that all elements in the array are quoted (using `shell.quote`) for
|
||||
safety, even if they do not need to be.
|
||||
|
||||
|
||||
### Parameters
|
||||
|
||||
<table class="params-table">
|
||||
<colgroup>
|
||||
<col class="col-param" />
|
||||
<col class="col-description" />
|
||||
</colgroup>
|
||||
<tbody>
|
||||
<tr id="_array_literal-iterable>
|
||||
<td><code>iterable</code></td>
|
||||
<td>
|
||||
required.
|
||||
<p>
|
||||
A sequence of elements. Elements that are not strings will be
|
||||
converted to strings first, by calling `str()`.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
|
||||
## _quote
|
||||
|
||||
<pre>
|
||||
_quote(<a href="#_quote-s">s</a>)
|
||||
</pre>
|
||||
|
||||
Quotes the given string for use in a shell command.
|
||||
|
||||
This function quotes the given string (in case it contains spaces or other
|
||||
shell metacharacters.)
|
||||
|
||||
|
||||
### Parameters
|
||||
|
||||
<table class="params-table">
|
||||
<colgroup>
|
||||
<col class="col-param" />
|
||||
<col class="col-description" />
|
||||
</colgroup>
|
||||
<tbody>
|
||||
<tr id="_quote-s>
|
||||
<td><code>s</code></td>
|
||||
<td>
|
||||
required.
|
||||
<p>
|
||||
The string to quote.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
|
||||
|
|
@ -0,0 +1,29 @@
|
|||
## _to_dict
|
||||
|
||||
<pre>
|
||||
_to_dict(<a href="#_to_dict-s">s</a>)
|
||||
</pre>
|
||||
|
||||
Converts a `struct` to a `dict`.
|
||||
|
||||
### Parameters
|
||||
|
||||
<table class="params-table">
|
||||
<colgroup>
|
||||
<col class="col-param" />
|
||||
<col class="col-description" />
|
||||
</colgroup>
|
||||
<tbody>
|
||||
<tr id="_to_dict-s>
|
||||
<td><code>s</code></td>
|
||||
<td>
|
||||
required.
|
||||
<p>
|
||||
A `struct`.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
|
||||
|
|
@ -0,0 +1,271 @@
|
|||
## _a_function
|
||||
|
||||
<pre>
|
||||
_a_function()
|
||||
</pre>
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
## _is_bool
|
||||
|
||||
<pre>
|
||||
_is_bool(<a href="#_is_bool-v">v</a>)
|
||||
</pre>
|
||||
|
||||
Returns True if v is an instance of a bool.
|
||||
|
||||
### Parameters
|
||||
|
||||
<table class="params-table">
|
||||
<colgroup>
|
||||
<col class="col-param" />
|
||||
<col class="col-description" />
|
||||
</colgroup>
|
||||
<tbody>
|
||||
<tr id="_is_bool-v>
|
||||
<td><code>v</code></td>
|
||||
<td>
|
||||
required.
|
||||
<p>
|
||||
The value whose type should be checked.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
|
||||
## _is_depset
|
||||
|
||||
<pre>
|
||||
_is_depset(<a href="#_is_depset-v">v</a>)
|
||||
</pre>
|
||||
|
||||
Returns True if v is an instance of a `depset`.
|
||||
|
||||
### Parameters
|
||||
|
||||
<table class="params-table">
|
||||
<colgroup>
|
||||
<col class="col-param" />
|
||||
<col class="col-description" />
|
||||
</colgroup>
|
||||
<tbody>
|
||||
<tr id="_is_depset-v>
|
||||
<td><code>v</code></td>
|
||||
<td>
|
||||
required.
|
||||
<p>
|
||||
The value whose type should be checked.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
|
||||
## _is_dict
|
||||
|
||||
<pre>
|
||||
_is_dict(<a href="#_is_dict-v">v</a>)
|
||||
</pre>
|
||||
|
||||
Returns True if v is an instance of a dict.
|
||||
|
||||
### Parameters
|
||||
|
||||
<table class="params-table">
|
||||
<colgroup>
|
||||
<col class="col-param" />
|
||||
<col class="col-description" />
|
||||
</colgroup>
|
||||
<tbody>
|
||||
<tr id="_is_dict-v>
|
||||
<td><code>v</code></td>
|
||||
<td>
|
||||
required.
|
||||
<p>
|
||||
The value whose type should be checked.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
|
||||
## _is_function
|
||||
|
||||
<pre>
|
||||
_is_function(<a href="#_is_function-v">v</a>)
|
||||
</pre>
|
||||
|
||||
Returns True if v is an instance of a function.
|
||||
|
||||
### Parameters
|
||||
|
||||
<table class="params-table">
|
||||
<colgroup>
|
||||
<col class="col-param" />
|
||||
<col class="col-description" />
|
||||
</colgroup>
|
||||
<tbody>
|
||||
<tr id="_is_function-v>
|
||||
<td><code>v</code></td>
|
||||
<td>
|
||||
required.
|
||||
<p>
|
||||
The value whose type should be checked.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
|
||||
## _is_int
|
||||
|
||||
<pre>
|
||||
_is_int(<a href="#_is_int-v">v</a>)
|
||||
</pre>
|
||||
|
||||
Returns True if v is an instance of a signed integer.
|
||||
|
||||
### Parameters
|
||||
|
||||
<table class="params-table">
|
||||
<colgroup>
|
||||
<col class="col-param" />
|
||||
<col class="col-description" />
|
||||
</colgroup>
|
||||
<tbody>
|
||||
<tr id="_is_int-v>
|
||||
<td><code>v</code></td>
|
||||
<td>
|
||||
required.
|
||||
<p>
|
||||
The value whose type should be checked.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
|
||||
## _is_list
|
||||
|
||||
<pre>
|
||||
_is_list(<a href="#_is_list-v">v</a>)
|
||||
</pre>
|
||||
|
||||
Returns True if v is an instance of a list.
|
||||
|
||||
### Parameters
|
||||
|
||||
<table class="params-table">
|
||||
<colgroup>
|
||||
<col class="col-param" />
|
||||
<col class="col-description" />
|
||||
</colgroup>
|
||||
<tbody>
|
||||
<tr id="_is_list-v>
|
||||
<td><code>v</code></td>
|
||||
<td>
|
||||
required.
|
||||
<p>
|
||||
The value whose type should be checked.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
|
||||
## _is_none
|
||||
|
||||
<pre>
|
||||
_is_none(<a href="#_is_none-v">v</a>)
|
||||
</pre>
|
||||
|
||||
Returns True if v has the type of None.
|
||||
|
||||
### Parameters
|
||||
|
||||
<table class="params-table">
|
||||
<colgroup>
|
||||
<col class="col-param" />
|
||||
<col class="col-description" />
|
||||
</colgroup>
|
||||
<tbody>
|
||||
<tr id="_is_none-v>
|
||||
<td><code>v</code></td>
|
||||
<td>
|
||||
required.
|
||||
<p>
|
||||
The value whose type should be checked.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
|
||||
## _is_string
|
||||
|
||||
<pre>
|
||||
_is_string(<a href="#_is_string-v">v</a>)
|
||||
</pre>
|
||||
|
||||
Returns True if v is an instance of a string.
|
||||
|
||||
### Parameters
|
||||
|
||||
<table class="params-table">
|
||||
<colgroup>
|
||||
<col class="col-param" />
|
||||
<col class="col-description" />
|
||||
</colgroup>
|
||||
<tbody>
|
||||
<tr id="_is_string-v>
|
||||
<td><code>v</code></td>
|
||||
<td>
|
||||
required.
|
||||
<p>
|
||||
The value whose type should be checked.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
|
||||
## _is_tuple
|
||||
|
||||
<pre>
|
||||
_is_tuple(<a href="#_is_tuple-v">v</a>)
|
||||
</pre>
|
||||
|
||||
Returns True if v is an instance of a tuple.
|
||||
|
||||
### Parameters
|
||||
|
||||
<table class="params-table">
|
||||
<colgroup>
|
||||
<col class="col-param" />
|
||||
<col class="col-description" />
|
||||
</colgroup>
|
||||
<tbody>
|
||||
<tr id="_is_tuple-v>
|
||||
<td><code>v</code></td>
|
||||
<td>
|
||||
required.
|
||||
<p>
|
||||
The value whose type should be checked.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
|
||||
|
|
@ -0,0 +1,940 @@
|
|||
<a name="#unittest_toolchain"></a>
|
||||
## unittest_toolchain
|
||||
|
||||
<pre>
|
||||
unittest_toolchain(<a href="#unittest_toolchain-name">name</a>, <a href="#unittest_toolchain-failure_templ">failure_templ</a>, <a href="#unittest_toolchain-file_ext">file_ext</a>, <a href="#unittest_toolchain-join_on">join_on</a>, <a href="#unittest_toolchain-success_templ">success_templ</a>)
|
||||
</pre>
|
||||
|
||||
|
||||
|
||||
### Attributes
|
||||
|
||||
<table class="params-table">
|
||||
<colgroup>
|
||||
<col class="col-param" />
|
||||
<col class="col-description" />
|
||||
</colgroup>
|
||||
<tbody>
|
||||
<tr id="unittest_toolchain-name">
|
||||
<td><code>name</code></td>
|
||||
<td>
|
||||
<a href="https://bazel.build/docs/build-ref.html#name">Name</a>; required
|
||||
<p>
|
||||
A unique name for this target.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr id="unittest_toolchain-failure_templ">
|
||||
<td><code>failure_templ</code></td>
|
||||
<td>
|
||||
String; required
|
||||
</td>
|
||||
</tr>
|
||||
<tr id="unittest_toolchain-file_ext">
|
||||
<td><code>file_ext</code></td>
|
||||
<td>
|
||||
String; required
|
||||
</td>
|
||||
</tr>
|
||||
<tr id="unittest_toolchain-join_on">
|
||||
<td><code>join_on</code></td>
|
||||
<td>
|
||||
String; required
|
||||
</td>
|
||||
</tr>
|
||||
<tr id="unittest_toolchain-success_templ">
|
||||
<td><code>success_templ</code></td>
|
||||
<td>
|
||||
String; required
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
|
||||
<a name="#_ActionInfo"></a>
|
||||
## _ActionInfo
|
||||
|
||||
<pre>
|
||||
_ActionInfo(<a href="#_ActionInfo-actions">actions</a>)
|
||||
</pre>
|
||||
|
||||
|
||||
|
||||
### Fields
|
||||
|
||||
<table class="params-table">
|
||||
<colgroup>
|
||||
<col class="col-param" />
|
||||
<col class="col-description" />
|
||||
</colgroup>
|
||||
<tbody>
|
||||
<tr id="_ActionInfo-actions">
|
||||
<td><code>actions</code></td>
|
||||
<td>
|
||||
<p>(Undocumented)</p>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
|
||||
<a name="#_UnittestToolchainInfo"></a>
|
||||
## _UnittestToolchainInfo
|
||||
|
||||
<pre>
|
||||
_UnittestToolchainInfo(<a href="#_UnittestToolchainInfo-file_ext">file_ext</a>, <a href="#_UnittestToolchainInfo-success_templ">success_templ</a>, <a href="#_UnittestToolchainInfo-failure_templ">failure_templ</a>, <a href="#_UnittestToolchainInfo-join_on">join_on</a>)
|
||||
</pre>
|
||||
|
||||
Execution platform information for rules in the bazel_skylib repository.
|
||||
|
||||
### Fields
|
||||
|
||||
<table class="params-table">
|
||||
<colgroup>
|
||||
<col class="col-param" />
|
||||
<col class="col-description" />
|
||||
</colgroup>
|
||||
<tbody>
|
||||
<tr id="_UnittestToolchainInfo-file_ext">
|
||||
<td><code>file_ext</code></td>
|
||||
<td>
|
||||
<p>(Undocumented)</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr id="_UnittestToolchainInfo-success_templ">
|
||||
<td><code>success_templ</code></td>
|
||||
<td>
|
||||
<p>(Undocumented)</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr id="_UnittestToolchainInfo-failure_templ">
|
||||
<td><code>failure_templ</code></td>
|
||||
<td>
|
||||
<p>(Undocumented)</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr id="_UnittestToolchainInfo-join_on">
|
||||
<td><code>join_on</code></td>
|
||||
<td>
|
||||
<p>(Undocumented)</p>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
|
||||
## _action_retrieving_aspect_impl
|
||||
|
||||
<pre>
|
||||
_action_retrieving_aspect_impl(<a href="#_action_retrieving_aspect_impl-target">target</a>, <a href="#_action_retrieving_aspect_impl-ctx">ctx</a>)
|
||||
</pre>
|
||||
|
||||
|
||||
|
||||
### Parameters
|
||||
|
||||
<table class="params-table">
|
||||
<colgroup>
|
||||
<col class="col-param" />
|
||||
<col class="col-description" />
|
||||
</colgroup>
|
||||
<tbody>
|
||||
<tr id="_action_retrieving_aspect_impl-target>
|
||||
<td><code>target</code></td>
|
||||
<td>
|
||||
required.
|
||||
</td>
|
||||
</tr>
|
||||
<tr id="_action_retrieving_aspect_impl-ctx>
|
||||
<td><code>ctx</code></td>
|
||||
<td>
|
||||
required.
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
|
||||
## _assert_equals
|
||||
|
||||
<pre>
|
||||
_assert_equals(<a href="#_assert_equals-env">env</a>, <a href="#_assert_equals-expected">expected</a>, <a href="#_assert_equals-actual">actual</a>, <a href="#_assert_equals-msg">msg</a>)
|
||||
</pre>
|
||||
|
||||
Asserts that the given `expected` and `actual` values are equal.
|
||||
|
||||
### Parameters
|
||||
|
||||
<table class="params-table">
|
||||
<colgroup>
|
||||
<col class="col-param" />
|
||||
<col class="col-description" />
|
||||
</colgroup>
|
||||
<tbody>
|
||||
<tr id="_assert_equals-env>
|
||||
<td><code>env</code></td>
|
||||
<td>
|
||||
required.
|
||||
<p>
|
||||
The test environment returned by `unittest.begin`.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr id="_assert_equals-expected>
|
||||
<td><code>expected</code></td>
|
||||
<td>
|
||||
required.
|
||||
<p>
|
||||
The expected value of some computation.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr id="_assert_equals-actual>
|
||||
<td><code>actual</code></td>
|
||||
<td>
|
||||
required.
|
||||
<p>
|
||||
The actual value returned by some computation.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr id="_assert_equals-msg>
|
||||
<td><code>msg</code></td>
|
||||
<td>
|
||||
optional. default is <code>None</code>
|
||||
<p>
|
||||
An optional message that will be printed that describes the failure.
|
||||
If omitted, a default will be used.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
|
||||
## _assert_false
|
||||
|
||||
<pre>
|
||||
_assert_false(<a href="#_assert_false-env">env</a>, <a href="#_assert_false-condition">condition</a>, <a href="#_assert_false-msg">msg</a>)
|
||||
</pre>
|
||||
|
||||
Asserts that the given `condition` is false.
|
||||
|
||||
### Parameters
|
||||
|
||||
<table class="params-table">
|
||||
<colgroup>
|
||||
<col class="col-param" />
|
||||
<col class="col-description" />
|
||||
</colgroup>
|
||||
<tbody>
|
||||
<tr id="_assert_false-env>
|
||||
<td><code>env</code></td>
|
||||
<td>
|
||||
required.
|
||||
<p>
|
||||
The test environment returned by `unittest.begin`.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr id="_assert_false-condition>
|
||||
<td><code>condition</code></td>
|
||||
<td>
|
||||
required.
|
||||
<p>
|
||||
A value that will be evaluated in a Boolean context.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr id="_assert_false-msg>
|
||||
<td><code>msg</code></td>
|
||||
<td>
|
||||
optional. default is <code>"Expected condition to be false, but was true."</code>
|
||||
<p>
|
||||
An optional message that will be printed that describes the failure.
|
||||
If omitted, a default will be used.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
|
||||
## _assert_new_set_equals
|
||||
|
||||
<pre>
|
||||
_assert_new_set_equals(<a href="#_assert_new_set_equals-env">env</a>, <a href="#_assert_new_set_equals-expected">expected</a>, <a href="#_assert_new_set_equals-actual">actual</a>, <a href="#_assert_new_set_equals-msg">msg</a>)
|
||||
</pre>
|
||||
|
||||
Asserts that the given `expected` and `actual` sets are equal.
|
||||
|
||||
### Parameters
|
||||
|
||||
<table class="params-table">
|
||||
<colgroup>
|
||||
<col class="col-param" />
|
||||
<col class="col-description" />
|
||||
</colgroup>
|
||||
<tbody>
|
||||
<tr id="_assert_new_set_equals-env>
|
||||
<td><code>env</code></td>
|
||||
<td>
|
||||
required.
|
||||
<p>
|
||||
The test environment returned by `unittest.begin`.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr id="_assert_new_set_equals-expected>
|
||||
<td><code>expected</code></td>
|
||||
<td>
|
||||
required.
|
||||
<p>
|
||||
The expected set resulting from some computation.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr id="_assert_new_set_equals-actual>
|
||||
<td><code>actual</code></td>
|
||||
<td>
|
||||
required.
|
||||
<p>
|
||||
The actual set returned by some computation.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr id="_assert_new_set_equals-msg>
|
||||
<td><code>msg</code></td>
|
||||
<td>
|
||||
optional. default is <code>None</code>
|
||||
<p>
|
||||
An optional message that will be printed that describes the failure.
|
||||
If omitted, a default will be used.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
|
||||
## _assert_set_equals
|
||||
|
||||
<pre>
|
||||
_assert_set_equals(<a href="#_assert_set_equals-env">env</a>, <a href="#_assert_set_equals-expected">expected</a>, <a href="#_assert_set_equals-actual">actual</a>, <a href="#_assert_set_equals-msg">msg</a>)
|
||||
</pre>
|
||||
|
||||
Asserts that the given `expected` and `actual` sets are equal.
|
||||
|
||||
### Parameters
|
||||
|
||||
<table class="params-table">
|
||||
<colgroup>
|
||||
<col class="col-param" />
|
||||
<col class="col-description" />
|
||||
</colgroup>
|
||||
<tbody>
|
||||
<tr id="_assert_set_equals-env>
|
||||
<td><code>env</code></td>
|
||||
<td>
|
||||
required.
|
||||
<p>
|
||||
The test environment returned by `unittest.begin`.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr id="_assert_set_equals-expected>
|
||||
<td><code>expected</code></td>
|
||||
<td>
|
||||
required.
|
||||
<p>
|
||||
The expected set resulting from some computation.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr id="_assert_set_equals-actual>
|
||||
<td><code>actual</code></td>
|
||||
<td>
|
||||
required.
|
||||
<p>
|
||||
The actual set returned by some computation.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr id="_assert_set_equals-msg>
|
||||
<td><code>msg</code></td>
|
||||
<td>
|
||||
optional. default is <code>None</code>
|
||||
<p>
|
||||
An optional message that will be printed that describes the failure.
|
||||
If omitted, a default will be used.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
|
||||
## _assert_true
|
||||
|
||||
<pre>
|
||||
_assert_true(<a href="#_assert_true-env">env</a>, <a href="#_assert_true-condition">condition</a>, <a href="#_assert_true-msg">msg</a>)
|
||||
</pre>
|
||||
|
||||
Asserts that the given `condition` is true.
|
||||
|
||||
### Parameters
|
||||
|
||||
<table class="params-table">
|
||||
<colgroup>
|
||||
<col class="col-param" />
|
||||
<col class="col-description" />
|
||||
</colgroup>
|
||||
<tbody>
|
||||
<tr id="_assert_true-env>
|
||||
<td><code>env</code></td>
|
||||
<td>
|
||||
required.
|
||||
<p>
|
||||
The test environment returned by `unittest.begin`.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr id="_assert_true-condition>
|
||||
<td><code>condition</code></td>
|
||||
<td>
|
||||
required.
|
||||
<p>
|
||||
A value that will be evaluated in a Boolean context.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr id="_assert_true-msg>
|
||||
<td><code>msg</code></td>
|
||||
<td>
|
||||
optional. default is <code>"Expected condition to be true, but was false."</code>
|
||||
<p>
|
||||
An optional message that will be printed that describes the failure.
|
||||
If omitted, a default will be used.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
|
||||
## _begin
|
||||
|
||||
<pre>
|
||||
_begin(<a href="#_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
|
||||
|
||||
<table class="params-table">
|
||||
<colgroup>
|
||||
<col class="col-param" />
|
||||
<col class="col-description" />
|
||||
</colgroup>
|
||||
<tbody>
|
||||
<tr id="_begin-ctx>
|
||||
<td><code>ctx</code></td>
|
||||
<td>
|
||||
required.
|
||||
<p>
|
||||
The Skylark context. Pass the implementation function's `ctx` argument
|
||||
in verbatim.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
|
||||
## _end
|
||||
|
||||
<pre>
|
||||
_end(<a href="#_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
|
||||
|
||||
<table class="params-table">
|
||||
<colgroup>
|
||||
<col class="col-param" />
|
||||
<col class="col-description" />
|
||||
</colgroup>
|
||||
<tbody>
|
||||
<tr id="_end-env>
|
||||
<td><code>env</code></td>
|
||||
<td>
|
||||
required.
|
||||
<p>
|
||||
The test environment returned by `unittest.begin`.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
|
||||
## _end_analysis_test
|
||||
|
||||
<pre>
|
||||
_end_analysis_test(<a href="#_end_analysis_test-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
|
||||
|
||||
<table class="params-table">
|
||||
<colgroup>
|
||||
<col class="col-param" />
|
||||
<col class="col-description" />
|
||||
</colgroup>
|
||||
<tbody>
|
||||
<tr id="_end_analysis_test-env>
|
||||
<td><code>env</code></td>
|
||||
<td>
|
||||
required.
|
||||
<p>
|
||||
The test environment returned by `analysistest.begin`.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
|
||||
## _expect_failure
|
||||
|
||||
<pre>
|
||||
_expect_failure(<a href="#_expect_failure-env">env</a>, <a href="#_expect_failure-expected_failure_msg">expected_failure_msg</a>)
|
||||
</pre>
|
||||
|
||||
Asserts that the target under test has failed with a given error message.
|
||||
|
||||
This requires that the analysis test is created with `analysistest.make()` and
|
||||
`expect_failures = True` is specified.
|
||||
|
||||
|
||||
### Parameters
|
||||
|
||||
<table class="params-table">
|
||||
<colgroup>
|
||||
<col class="col-param" />
|
||||
<col class="col-description" />
|
||||
</colgroup>
|
||||
<tbody>
|
||||
<tr id="_expect_failure-env>
|
||||
<td><code>env</code></td>
|
||||
<td>
|
||||
required.
|
||||
<p>
|
||||
The test environment returned by `analysistest.begin`.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr id="_expect_failure-expected_failure_msg>
|
||||
<td><code>expected_failure_msg</code></td>
|
||||
<td>
|
||||
optional. default is <code>""</code>
|
||||
<p>
|
||||
The error message to expect as a result of analysis failures.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
|
||||
## _fail
|
||||
|
||||
<pre>
|
||||
_fail(<a href="#_fail-env">env</a>, <a href="#_fail-msg">msg</a>)
|
||||
</pre>
|
||||
|
||||
Unconditionally causes the current test to fail.
|
||||
|
||||
### Parameters
|
||||
|
||||
<table class="params-table">
|
||||
<colgroup>
|
||||
<col class="col-param" />
|
||||
<col class="col-description" />
|
||||
</colgroup>
|
||||
<tbody>
|
||||
<tr id="_fail-env>
|
||||
<td><code>env</code></td>
|
||||
<td>
|
||||
required.
|
||||
<p>
|
||||
The test environment returned by `unittest.begin`.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr id="_fail-msg>
|
||||
<td><code>msg</code></td>
|
||||
<td>
|
||||
required.
|
||||
<p>
|
||||
The message to log describing the failure.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
|
||||
## _impl_function_name
|
||||
|
||||
<pre>
|
||||
_impl_function_name(<a href="#_impl_function_name-impl">impl</a>)
|
||||
</pre>
|
||||
|
||||
Derives the name of the given rule implementation function.
|
||||
|
||||
This can be used for better test feedback.
|
||||
|
||||
### Parameters
|
||||
|
||||
<table class="params-table">
|
||||
<colgroup>
|
||||
<col class="col-param" />
|
||||
<col class="col-description" />
|
||||
</colgroup>
|
||||
<tbody>
|
||||
<tr id="_impl_function_name-impl>
|
||||
<td><code>impl</code></td>
|
||||
<td>
|
||||
required.
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
|
||||
## _make
|
||||
|
||||
<pre>
|
||||
_make(<a href="#_make-impl">impl</a>, <a href="#_make-attrs">attrs</a>)
|
||||
</pre>
|
||||
|
||||
Creates a unit test rule from its implementation function.
|
||||
|
||||
Each unit test is defined in an implementation function that must then be
|
||||
associated with a rule so that a target can be built. This function handles
|
||||
the boilerplate to create and return a test rule and captures the
|
||||
implementation function's name so that it can be printed in test feedback.
|
||||
|
||||
The optional `attrs` argument can be used to define dependencies for this
|
||||
test, in order to form unit tests of rules.
|
||||
|
||||
An example of a unit test:
|
||||
|
||||
```
|
||||
def _your_test(ctx):
|
||||
env = unittest.begin(ctx)
|
||||
|
||||
# Assert statements go here
|
||||
|
||||
return unittest.end(env)
|
||||
|
||||
your_test = unittest.make(_your_test)
|
||||
```
|
||||
|
||||
Recall that names of test rules must end in `_test`.
|
||||
|
||||
|
||||
### Parameters
|
||||
|
||||
<table class="params-table">
|
||||
<colgroup>
|
||||
<col class="col-param" />
|
||||
<col class="col-description" />
|
||||
</colgroup>
|
||||
<tbody>
|
||||
<tr id="_make-impl>
|
||||
<td><code>impl</code></td>
|
||||
<td>
|
||||
required.
|
||||
<p>
|
||||
The implementation function of the unit test.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr id="_make-attrs>
|
||||
<td><code>attrs</code></td>
|
||||
<td>
|
||||
optional. default is <code>None</code>
|
||||
<p>
|
||||
An optional dictionary to supplement the attrs passed to the
|
||||
unit test's `rule()` constructor.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
|
||||
## _make_analysis_test
|
||||
|
||||
<pre>
|
||||
_make_analysis_test(<a href="#_make_analysis_test-impl">impl</a>, <a href="#_make_analysis_test-expect_failure">expect_failure</a>, <a href="#_make_analysis_test-config_settings">config_settings</a>)
|
||||
</pre>
|
||||
|
||||
Creates an analysis test rule from its implementation function.
|
||||
|
||||
An analysis test verifies the behavior of a "real" rule target by examining
|
||||
and asserting on the providers given by the real target.
|
||||
|
||||
Each analysis test is defined in an implementation function that must then be
|
||||
associated with a rule so that a target can be built. This function handles
|
||||
the boilerplate to create and return a test rule and captures the
|
||||
implementation function's name so that it can be printed in test feedback.
|
||||
|
||||
An example of an analysis test:
|
||||
|
||||
```
|
||||
def _your_test(ctx):
|
||||
env = analysistest.begin(ctx)
|
||||
|
||||
# Assert statements go here
|
||||
|
||||
return analysistest.end(env)
|
||||
|
||||
your_test = analysistest.make(_your_test)
|
||||
```
|
||||
|
||||
Recall that names of test rules must end in `_test`.
|
||||
|
||||
|
||||
### Parameters
|
||||
|
||||
<table class="params-table">
|
||||
<colgroup>
|
||||
<col class="col-param" />
|
||||
<col class="col-description" />
|
||||
</colgroup>
|
||||
<tbody>
|
||||
<tr id="_make_analysis_test-impl>
|
||||
<td><code>impl</code></td>
|
||||
<td>
|
||||
required.
|
||||
<p>
|
||||
The implementation function of the unit test.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr id="_make_analysis_test-expect_failure>
|
||||
<td><code>expect_failure</code></td>
|
||||
<td>
|
||||
optional. default is <code>False</code>
|
||||
<p>
|
||||
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
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr id="_make_analysis_test-config_settings>
|
||||
<td><code>config_settings</code></td>
|
||||
<td>
|
||||
optional. default is <code>{}</code>
|
||||
<p>
|
||||
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
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
|
||||
## _suite
|
||||
|
||||
<pre>
|
||||
_suite(<a href="#_suite-name">name</a>, <a href="#_suite-test_rules">test_rules</a>)
|
||||
</pre>
|
||||
|
||||
Defines a `test_suite` target that contains multiple tests.
|
||||
|
||||
After defining your test rules in a `.bzl` file, you need to create targets
|
||||
from those rules so that `blaze test` can execute them. Doing this manually
|
||||
in a BUILD file would consist of listing each test in your `load` statement
|
||||
and then creating each target one by one. To reduce duplication, we recommend
|
||||
writing a macro in your `.bzl` file to instantiate all targets, and calling
|
||||
that macro from your BUILD file so you only have to load one symbol.
|
||||
|
||||
For the case where your unit tests do not take any (non-default) attributes --
|
||||
i.e., if your unit tests do not test rules -- you can use this function to
|
||||
create the targets and wrap them in a single test_suite target. In your
|
||||
`.bzl` file, write:
|
||||
|
||||
```
|
||||
def your_test_suite():
|
||||
unittest.suite(
|
||||
"your_test_suite",
|
||||
your_test,
|
||||
your_other_test,
|
||||
yet_another_test,
|
||||
)
|
||||
```
|
||||
|
||||
Then, in your `BUILD` file, simply load the macro and invoke it to have all
|
||||
of the targets created:
|
||||
|
||||
```
|
||||
load("//path/to/your/package:tests.bzl", "your_test_suite")
|
||||
your_test_suite()
|
||||
```
|
||||
|
||||
If you pass _N_ unit test rules to `unittest.suite`, _N_ + 1 targets will be
|
||||
created: a `test_suite` target named `${name}` (where `${name}` is the name
|
||||
argument passed in here) and targets named `${name}_test_${i}`, where `${i}`
|
||||
is the index of the test in the `test_rules` list, which is used to uniquely
|
||||
name each target.
|
||||
|
||||
|
||||
### Parameters
|
||||
|
||||
<table class="params-table">
|
||||
<colgroup>
|
||||
<col class="col-param" />
|
||||
<col class="col-description" />
|
||||
</colgroup>
|
||||
<tbody>
|
||||
<tr id="_suite-name>
|
||||
<td><code>name</code></td>
|
||||
<td>
|
||||
required.
|
||||
<p>
|
||||
The name of the `test_suite` target, and the prefix of all the test
|
||||
target names.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr id="_suite-test_rules>
|
||||
<td><code>test_rules</code></td>
|
||||
<td>
|
||||
required.
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
|
||||
## _target_actions
|
||||
|
||||
<pre>
|
||||
_target_actions(<a href="#_target_actions-env">env</a>)
|
||||
</pre>
|
||||
|
||||
Returns a list of actions registered by the target under test.
|
||||
|
||||
### Parameters
|
||||
|
||||
<table class="params-table">
|
||||
<colgroup>
|
||||
<col class="col-param" />
|
||||
<col class="col-description" />
|
||||
</colgroup>
|
||||
<tbody>
|
||||
<tr id="_target_actions-env>
|
||||
<td><code>env</code></td>
|
||||
<td>
|
||||
required.
|
||||
<p>
|
||||
The test environment returned by `analysistest.begin`.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
|
||||
## _target_under_test
|
||||
|
||||
<pre>
|
||||
_target_under_test(<a href="#_target_under_test-env">env</a>)
|
||||
</pre>
|
||||
|
||||
Returns the target under test.
|
||||
|
||||
### Parameters
|
||||
|
||||
<table class="params-table">
|
||||
<colgroup>
|
||||
<col class="col-param" />
|
||||
<col class="col-description" />
|
||||
</colgroup>
|
||||
<tbody>
|
||||
<tr id="_target_under_test-env>
|
||||
<td><code>env</code></td>
|
||||
<td>
|
||||
required.
|
||||
<p>
|
||||
The test environment returned by `analysistest.begin`.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
|
||||
## _unittest_toolchain_impl
|
||||
|
||||
<pre>
|
||||
_unittest_toolchain_impl(<a href="#_unittest_toolchain_impl-ctx">ctx</a>)
|
||||
</pre>
|
||||
|
||||
|
||||
|
||||
### Parameters
|
||||
|
||||
<table class="params-table">
|
||||
<colgroup>
|
||||
<col class="col-param" />
|
||||
<col class="col-description" />
|
||||
</colgroup>
|
||||
<tbody>
|
||||
<tr id="_unittest_toolchain_impl-ctx>
|
||||
<td><code>ctx</code></td>
|
||||
<td>
|
||||
required.
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
|
||||
## register_unittest_toolchains
|
||||
|
||||
<pre>
|
||||
register_unittest_toolchains()
|
||||
</pre>
|
||||
|
||||
Registers the toolchains for unittest users.
|
||||
|
||||
|
||||
|
||||
|
|
@ -0,0 +1,195 @@
|
|||
## _check_bazel_version
|
||||
|
||||
<pre>
|
||||
_check_bazel_version(<a href="#_check_bazel_version-minimum_bazel_version">minimum_bazel_version</a>, <a href="#_check_bazel_version-maximum_bazel_version">maximum_bazel_version</a>, <a href="#_check_bazel_version-bazel_version">bazel_version</a>)
|
||||
</pre>
|
||||
|
||||
Check that the version of Bazel is valid within the specified range.
|
||||
|
||||
### Parameters
|
||||
|
||||
<table class="params-table">
|
||||
<colgroup>
|
||||
<col class="col-param" />
|
||||
<col class="col-description" />
|
||||
</colgroup>
|
||||
<tbody>
|
||||
<tr id="_check_bazel_version-minimum_bazel_version>
|
||||
<td><code>minimum_bazel_version</code></td>
|
||||
<td>
|
||||
required.
|
||||
<p>
|
||||
minimum version of Bazel expected
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr id="_check_bazel_version-maximum_bazel_version>
|
||||
<td><code>maximum_bazel_version</code></td>
|
||||
<td>
|
||||
optional. default is <code>None</code>
|
||||
<p>
|
||||
maximum version of Bazel expected
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr id="_check_bazel_version-bazel_version>
|
||||
<td><code>bazel_version</code></td>
|
||||
<td>
|
||||
optional. default is <code>None</code>
|
||||
<p>
|
||||
the version of Bazel to check. Used for testing, defaults to native.bazel_version
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
|
||||
## _extract_version_number
|
||||
|
||||
<pre>
|
||||
_extract_version_number(<a href="#_extract_version_number-bazel_version">bazel_version</a>)
|
||||
</pre>
|
||||
|
||||
Extracts the semantic version number from a version string
|
||||
|
||||
### Parameters
|
||||
|
||||
<table class="params-table">
|
||||
<colgroup>
|
||||
<col class="col-param" />
|
||||
<col class="col-description" />
|
||||
</colgroup>
|
||||
<tbody>
|
||||
<tr id="_extract_version_number-bazel_version>
|
||||
<td><code>bazel_version</code></td>
|
||||
<td>
|
||||
required.
|
||||
<p>
|
||||
the version string that begins with the semantic version
|
||||
e.g. "1.2.3rc1 abc1234" where "abc1234" is a commit hash.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
|
||||
## _get_bazel_version
|
||||
|
||||
<pre>
|
||||
_get_bazel_version()
|
||||
</pre>
|
||||
|
||||
Returns the current Bazel version
|
||||
|
||||
|
||||
|
||||
## _is_at_least
|
||||
|
||||
<pre>
|
||||
_is_at_least(<a href="#_is_at_least-threshold">threshold</a>, <a href="#_is_at_least-version">version</a>)
|
||||
</pre>
|
||||
|
||||
Check that a version is higher or equals to a threshold.
|
||||
|
||||
### Parameters
|
||||
|
||||
<table class="params-table">
|
||||
<colgroup>
|
||||
<col class="col-param" />
|
||||
<col class="col-description" />
|
||||
</colgroup>
|
||||
<tbody>
|
||||
<tr id="_is_at_least-threshold>
|
||||
<td><code>threshold</code></td>
|
||||
<td>
|
||||
required.
|
||||
<p>
|
||||
the minimum version string
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr id="_is_at_least-version>
|
||||
<td><code>version</code></td>
|
||||
<td>
|
||||
required.
|
||||
<p>
|
||||
the version string to be compared to the threshold
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
|
||||
## _is_at_most
|
||||
|
||||
<pre>
|
||||
_is_at_most(<a href="#_is_at_most-threshold">threshold</a>, <a href="#_is_at_most-version">version</a>)
|
||||
</pre>
|
||||
|
||||
Check that a version is lower or equals to a threshold.
|
||||
|
||||
### Parameters
|
||||
|
||||
<table class="params-table">
|
||||
<colgroup>
|
||||
<col class="col-param" />
|
||||
<col class="col-description" />
|
||||
</colgroup>
|
||||
<tbody>
|
||||
<tr id="_is_at_most-threshold>
|
||||
<td><code>threshold</code></td>
|
||||
<td>
|
||||
required.
|
||||
<p>
|
||||
the maximum version string
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr id="_is_at_most-version>
|
||||
<td><code>version</code></td>
|
||||
<td>
|
||||
required.
|
||||
<p>
|
||||
the version string to be compared to the threshold
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
|
||||
## _parse_bazel_version
|
||||
|
||||
<pre>
|
||||
_parse_bazel_version(<a href="#_parse_bazel_version-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 (<, >).
|
||||
|
||||
|
||||
### Parameters
|
||||
|
||||
<table class="params-table">
|
||||
<colgroup>
|
||||
<col class="col-param" />
|
||||
<col class="col-description" />
|
||||
</colgroup>
|
||||
<tbody>
|
||||
<tr id="_parse_bazel_version-bazel_version>
|
||||
<td><code>bazel_version</code></td>
|
||||
<td>
|
||||
required.
|
||||
<p>
|
||||
the Bazel version string
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
|
||||
|
|
@ -7,6 +7,7 @@ package(default_visibility = ["//visibility:public"])
|
|||
bzl_library(
|
||||
name = "build_test",
|
||||
srcs = ["build_test.bzl"],
|
||||
deps = ["//lib:new_sets"],
|
||||
)
|
||||
|
||||
bzl_library(
|
||||
|
|
|
|||
Loading…
Reference in New Issue