diff options
| author | Android Build Coastguard Worker <android-build-coastguard-worker@google.com> | 2023-07-07 00:57:38 +0000 |
|---|---|---|
| committer | Android Build Coastguard Worker <android-build-coastguard-worker@google.com> | 2023-07-07 00:57:38 +0000 |
| commit | d301a7fbe4b7815cd80cf990b184977db3584613 (patch) | |
| tree | 3c15c050ced2749753c4d6f1cf9d3a9b9bd94085 | |
| parent | e3e4f5325f3a9b46381531439b27dcfb294477fe (diff) | |
| parent | f8aadd2ad5a51ac3187333bf589a754c5347d447 (diff) | |
| download | bazel-skylib-android14-mainline-resolv-release.tar.gz | |
Snap for 10447354 from f8aadd2ad5a51ac3187333bf589a754c5347d447 to mainline-resolv-releaseaml_res_341510000aml_res_341410010aml_res_341311030aml_res_341110000aml_res_340912000android14-mainline-resolv-release
Change-Id: I260a1941320c28e8abf2c7d93369c1b22b637b50
89 files changed, 2205 insertions, 2605 deletions
@@ -4,8 +4,6 @@ licenses(["notice"]) package(default_visibility = ["//visibility:public"]) -# gazelle:exclude internal_deps.bzl -# gazelle:exclude internal_setup.bzl # buildifier: disable=skylark-comment # gazelle:exclude skylark_library.bzl @@ -77,10 +75,3 @@ filegroup( "//toolchains/unittest:distribution", ] + glob(["*.bzl"]), ) - -filegroup( - name = "bins", - srcs = [ - "//rules:bins", - ], -) diff --git a/CHANGELOG.md b/CHANGELOG.md index dce01b4..4567ed3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,54 @@ +Release 1.2.1 + +Bugfix release: fixes build failure with --incompatible_disallow_empty_glob +(#359) + +**Contributors** + +Alexandre Rostovtsev, Ivo List + + +Release 1.2.0 + +**New Features** + +- The unittest toolchain has better support for special characters in failure + messages (#320) +- Use portable Bash shebangs for BSD compatibility (#329) +- Add loadingtest - tests which evaluate during the loading phase (#347) +- Add doc parameter to analysistest.make, allowing analysis tests to be + documented in a Stardoc-friendly way (#343, #352) + +**Contributors** + +Alexandre Rostovtsev, Geoffrey Martin-Noble, Kevin Kress, Samuel Freilich, +UebelAndre, Yesudeep Mangalapilly + + +Release 1.1.1 (initially tagged as 1.1.0) + +**New Features** + +- Gazelle: support relative imports (#271) and imports from `@bazel_tools` + (#273) +- Add partial.is_instance() (#276) +- Allow unittest.suite() to accept partial calls of test rules (#276) +- Allow specifying additional aspects to target under test in + analysistest.make() (#299) +- Add Windows support for build_test (#302) + +**Incompatible Changes** + +- structs.to_dict() ignores deprecated to_json()/to_proto() methods (#295) + +**Contributors** + +aiuto, alandonovan, Alex Eagle, Alexandre Rostovtsev, Andrew Z Allen, c-parsons, +Christopher Sauer, Daniel Wagner-Hall, David Sanderson, dmaclach, Laurent Le +Brun, Mansur, Olek Wojnar, Philipp Wollermann, River, Samuel Giddins, Thaler +Benedek + + Release 1.0.3 **Significant Changes** @@ -41,7 +92,7 @@ Release 0.9.0 https://docs.google.com/document/d/1vc8v-kXjvgZOdQdnxPTaV0rrLxtP2XwnD2tAZlYJOqw/edit#bookmark=id.iiumwic0jphr - selects.bzl: Add config_setting_group for config_setting AND/OR-chaining Implements - https://github.com/bazelbuild/proposals/blob/master/designs/2018-11-09-config-setting-chaining.md. + https://github.com/bazelbuild/proposals/blob/HEAD/designs/2018-11-09-config-setting-chaining.md. - Make sets.bzl point to new_sets.bzl instead of old_sets.bzl. new_sets.bzl and old_sets.bzl should be removed in the following skylib release. @@ -1,4 +1,3 @@ -* @c-parsons @laurentlb @jin @aiuto -distribution/ @aiuto @fwe -rules/ @juliexxia -gazelle/ @achew22 @jayconrod +# More details on syntax here: https://help.github.com/articles/about-codeowners/ +* @brandjon @tetromino @comius @hvadehra @c-mita +/gazelle/ @achew22 @jayconrod diff --git a/METADATA b/METADATA new file mode 100644 index 0000000..0c4d938 --- /dev/null +++ b/METADATA @@ -0,0 +1,16 @@ +name: "bazel-skylib" +description: + "" + +third_party { + url { + type: HOMEPAGE + value: "https://github.com/bazelbuild/bazel-skylib" + } + url { + type: GIT + value: "https://github.com/bazelbuild/bazel-skylib.git" + } + version: "1.2.1" + last_upgrade_date { year: 2022 month: 6 day: 21 } +} diff --git a/MODULE_LICENSE_APACHE2 b/MODULE_LICENSE_APACHE2 new file mode 100644 index 0000000..e69de29 --- /dev/null +++ b/MODULE_LICENSE_APACHE2 @@ -1,13 +1,9 @@ # Skylib -[](https://buildkite.com/bazel/bazel-skylib) +[](https://buildkite.com/bazel/bazel-skylib) -Skylib is a standard library that provides functions useful for manipulating -collections, file paths, and other features that are useful when writing custom -build rules in Bazel. - -> This library is currently under early development. Be aware that the APIs -> in these modules may change during this time. +Skylib is a library of Starlark functions for manipulating collections, file paths, +and various other data types in the domain of Bazel build rules. Each of the `.bzl` files in the `lib` directory defines a "module"—a `struct` that contains a set of related functions and/or other symbols that can @@ -63,9 +59,26 @@ s = shell.quote(p) * [analysis_test](docs/analysis_test_doc.md) * [build_test](docs/build_test_doc.md) +* [copy_file](docs/copy_file_doc.md) +* [write_file](docs/write_file_doc.md) ## Writing a new module +The criteria for adding a new function or module to this repository are: + +1. Is it widely needed? The new code must solve a problem that occurs often during the development of Bazel build rules. It is not sufficient that the new code is merely useful. Candidate code should generally have been proven to be necessary across several projects, either because it provides indispensible common functionality, or because it requires a single standardized implementation. + +1. Is its interface simpler than its implementation? A good abstraction provides a simple interface to a complex implementation, relieving the user from the burden of understanding. By contrast, a shallow abstraction provides little that the user could not easily have written out for themselves. If a function's doc comment is longer than its body, it's a good sign that the abstraction is too shallow. + +1. Is its interface unimpeachable? Given the problem it tries to solve, does it have sufficient parameters or generality to address all reasonable cases, or does it make arbitrary policy choices that limit its usefulness? If the function is not general, it likely does not belong here. Conversely, if it is general thanks only to a bewildering number of parameters, it also does not belong here. + +1. Is it efficient? Does it solve the problem using the asymptotically optimal algorithm, without using excessive looping, allocation, or other high constant factors? Starlark is an interpreted language with relatively expensive basic operations, and an approach that might make sense in C++ may not in Starlark. + +If your new module meets all these criteria, then you should consider sending us a pull request. It is always better to discuss your plans before executing them. + +Many of the declarations already in this repository do not meet this bar. + + Steps to add a module to Skylib: 1. Create a new `.bzl` file in the `lib` directory. @@ -106,3 +119,8 @@ ERROR: Analysis of target '//foo:bar' failed; build aborted: no matching toolcha then you probably forgot to load and call `bazel_skylib_workspace()` in your `WORKSPACE` file. + +### Maintainer's guide + +See the [maintaner's guide](docs/maintainers_guide.md) for instructions for +cutting a new release. @@ -3,71 +3,78 @@ workspace(name = "bazel_skylib") load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive") load("@bazel_tools//tools/build_defs/repo:utils.bzl", "maybe") -http_archive( - name = "rules_pkg", - urls = [ - "https://github.com/bazelbuild/rules_pkg/releases/download/0.2.5/rules_pkg-0.2.5.tar.gz", - "https://mirror.bazel.build/github.com/bazelbuild/rules_pkg/releases/download/0.2.5/rules_pkg-0.2.5.tar.gz", - ], - sha256 = "352c090cc3d3f9a6b4e676cf42a6047c16824959b438895a76c2989c6d7c246a", -) -load("@rules_pkg//:deps.bzl", "rules_pkg_dependencies") -rules_pkg_dependencies() - maybe( - name = "bazel_federation", + name = "io_bazel_rules_go", repo_rule = http_archive, - sha256 = "b10529fcf8a464591e845588348533981e948315b706183481e0d076afe2fa3c", - url = "https://github.com/bazelbuild/bazel-federation/releases/download/0.0.2/bazel_federation-0.0.2.tar.gz", + sha256 = "2b1641428dff9018f9e85c0384f03ec6c10660d935b750e3fa1492a281a53b0f", + urls = [ + "https://mirror.bazel.build/github.com/bazelbuild/rules_go/releases/download/v0.29.0/rules_go-v0.29.0.zip", + "https://github.com/bazelbuild/rules_go/releases/download/v0.29.0/rules_go-v0.29.0.zip", + ], ) -load("@bazel_federation//:repositories.bzl", "bazel_skylib_deps", "rules_go") - -bazel_skylib_deps() - -rules_go() +load("@io_bazel_rules_go//go:deps.bzl", "go_register_toolchains", "go_rules_dependencies") -load("@bazel_federation//setup:bazel_skylib.bzl", "bazel_skylib_setup") +go_rules_dependencies() -bazel_skylib_setup() - -load("@bazel_federation//setup:rules_go.bzl", "rules_go_setup") - -rules_go_setup() +go_register_toolchains(version = "1.17.1") # Below this line is for documentation generation only, # and should thus not be included by dependencies on # bazel-skylib. -load("//:internal_deps.bzl", "bazel_skylib_internal_deps") +maybe( + http_archive, + name = "io_bazel_stardoc", + sha256 = "c9794dcc8026a30ff67cf7cf91ebe245ca294b20b071845d12c192afe243ad72", + urls = [ + "https://mirror.bazel.build/github.com/bazelbuild/stardoc/releases/download/0.5.0/stardoc-0.5.0.tar.gz", + "https://github.com/bazelbuild/stardoc/releases/download/0.5.0/stardoc-0.5.0.tar.gz", + ], +) + +load("@io_bazel_stardoc//:setup.bzl", "stardoc_repositories") -bazel_skylib_internal_deps() +stardoc_repositories() + +maybe( + http_archive, + name = "rules_pkg", + sha256 = "a89e203d3cf264e564fcb96b6e06dd70bc0557356eb48400ce4b5d97c2c3720d", + urls = [ + "https://mirror.bazel.build/github.com/bazelbuild/rules_pkg/releases/download/0.5.1/rules_pkg-0.5.1.tar.gz", + "https://github.com/bazelbuild/rules_pkg/releases/download/0.5.1/rules_pkg-0.5.1.tar.gz", + ], +) -load("//:internal_setup.bzl", "bazel_skylib_internal_setup") +load("@rules_pkg//:deps.bzl", "rules_pkg_dependencies") -bazel_skylib_internal_setup() +rules_pkg_dependencies() maybe( name = "rules_cc", repo_rule = http_archive, - sha256 = "b4b2a2078bdb7b8328d843e8de07d7c13c80e6c89e86a09d6c4b424cfd1aaa19", - strip_prefix = "rules_cc-cb2dfba6746bfa3c3705185981f3109f0ae1b893", + sha256 = "4dccbfd22c0def164c8f47458bd50e0c7148f3d92002cdb459c2a96a68498241", urls = [ - "https://mirror.bazel.build/github.com/bazelbuild/rules_cc/archive/cb2dfba6746bfa3c3705185981f3109f0ae1b893.zip", - "https://github.com/bazelbuild/rules_cc/archive/cb2dfba6746bfa3c3705185981f3109f0ae1b893.zip", + "https://mirror.bazel.build/github.com/bazelbuild/rules_cc/releases/download/0.0.1/rules_cc-0.0.1.tar.gz", + "https://github.com/bazelbuild/rules_cc/releases/download/0.0.1/rules_cc-0.0.1.tar.gz", ], ) +load("//lib:unittest.bzl", "register_unittest_toolchains") + +register_unittest_toolchains() + # Provide a repository hint for Gazelle to inform it that the go package # github.com/bazelbuild/rules_go is available from io_bazel_rules_go and it # doesn't need to duplicatively fetch it. # gazelle:repository go_repository name=io_bazel_rules_go importpath=github.com/bazelbuild/rules_go http_archive( name = "bazel_gazelle", - sha256 = "bfd86b3cbe855d6c16c6fce60d76bd51f5c8dbc9cfcaef7a2bb5c1aafd0710e8", + sha256 = "de69a09dc70417580aabf20a28619bb3ef60d038470c7cf8442fafcf627c21cb", urls = [ - "https://mirror.bazel.build/github.com/bazelbuild/bazel-gazelle/releases/download/v0.21.0/bazel-gazelle-v0.21.0.tar.gz", - "https://github.com/bazelbuild/bazel-gazelle/releases/download/v0.21.0/bazel-gazelle-v0.21.0.tar.gz", + "https://mirror.bazel.build/github.com/bazelbuild/bazel-gazelle/releases/download/v0.24.0/bazel-gazelle-v0.24.0.tar.gz", + "https://github.com/bazelbuild/bazel-gazelle/releases/download/v0.24.0/bazel-gazelle-v0.24.0.tar.gz", ], ) # Another Gazelle repository hint. diff --git a/distribution/BUILD b/distribution/BUILD index ba903aa..8a9b1e7 100644 --- a/distribution/BUILD +++ b/distribution/BUILD @@ -6,37 +6,15 @@ package( default_visibility = ["//visibility:private"], ) -pkg_tar( - name = "srcs", - srcs = ["//:distribution"], - mode = "0444", - # Make it owned by root so it does not have the uid of the CI robot. - owner = "0.0", - package_dir = "", - strip_prefix = ".", -) - -pkg_tar( - name = "bins", - srcs = ["//:bins"], - mode = "0555", - # Make it owned by root so it does not have the uid of the CI robot. - owner = "0.0", - package_dir = "", - strip_prefix = ".", -) - # Build the artifact to put on the github release page. pkg_tar( name = "bazel-skylib-%s" % version, + srcs = ["//:distribution"], extension = "tar.gz", + mode = "0644", # Make it owned by root so it does not have the uid of the CI robot. owner = "0.0", strip_prefix = ".", - deps = [ - ":bins.tar", - ":srcs.tar", - ], ) print_rel_notes( @@ -1,4 +1,4 @@ -load("@io_bazel_skydoc//stardoc:stardoc.bzl", "stardoc") +load("@io_bazel_stardoc//stardoc:stardoc.bzl", "stardoc") licenses(["notice"]) diff --git a/docs/analysis_test_doc.md b/docs/analysis_test_doc.md index 817be66..1a564ae 100755 --- a/docs/analysis_test_doc.md +++ b/docs/analysis_test_doc.md @@ -1,4 +1,9 @@ -<a name="#analysis_test"></a> +<!-- Generated with Stardoc: http://skydoc.bazel.build --> + +A test verifying other targets can be successfully analyzed as part of a `bazel test` + +<a id="#analysis_test"></a> + ## analysis_test <pre> @@ -32,30 +37,12 @@ Test rule checking that other targets can be successfully analyzed. 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> +**ATTRIBUTES** + + +| Name | Description | Type | Mandatory | Default | +| :------------- | :------------- | :------------- | :------------- | :------------- | +| <a id="analysis_test-name"></a>name | A unique name for this target. | <a href="https://bazel.build/docs/build-ref.html#name">Name</a> | required | | +| <a id="analysis_test-targets"></a>targets | - | <a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a> | required | | diff --git a/docs/build_test_doc.md b/docs/build_test_doc.md index 6f3c597..332dc58 100755 --- a/docs/build_test_doc.md +++ b/docs/build_test_doc.md @@ -1,3 +1,9 @@ +<!-- Generated with Stardoc: http://skydoc.bazel.build --> + +A test verifying other targets build as part of a `bazel test` + +<a id="#build_test"></a> + ## build_test <pre> @@ -10,9 +16,6 @@ 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: ``` @@ -26,42 +29,13 @@ Typical usage: ``` -### Parameters +**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> - optional. - <p> - The <a href="https://docs.bazel.build/versions/master/be/common-definitions.html#common-attributes-tests">common attributes for tests</a>. - </p> - </td> - </tr> - </tbody> -</table> +| Name | Description | Default Value | +| :------------- | :------------- | :------------- | +| <a id="build_test-name"></a>name | The name of the test rule. | none | +| <a id="build_test-targets"></a>targets | A list of targets to ensure build. | none | +| <a id="build_test-kwargs"></a>kwargs | The <a href="https://docs.bazel.build/versions/main/be/common-definitions.html#common-attributes-tests">common attributes for tests</a>. | none | diff --git a/docs/collections_doc.md b/docs/collections_doc.md index 64ffb5e..1138850 100755 --- a/docs/collections_doc.md +++ b/docs/collections_doc.md @@ -1,3 +1,9 @@ +<!-- Generated with Stardoc: http://skydoc.bazel.build --> + +Skylib module containing functions that operate on collections. + +<a id="#collections.after_each"></a> + ## collections.after_each <pre> @@ -6,35 +12,20 @@ collections.after_each(<a href="#collections.after_each-separator">separator</a> 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="collections.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="collections.after_each-iterable"> - <td><code>iterable</code></td> - <td> - required. - <p> - The list into which to intersperse the separator. - </p> - </td> - </tr> - </tbody> -</table> +**PARAMETERS** + + +| 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-iterable"></a>iterable | The list into which to intersperse the separator. | none | +**RETURNS** + +A new list with `separator` after each item in `iterable`. + + +<a id="#collections.before_each"></a> ## collections.before_each @@ -44,35 +35,20 @@ collections.before_each(<a href="#collections.before_each-separator">separator</ 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="collections.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="collections.before_each-iterable"> - <td><code>iterable</code></td> - <td> - required. - <p> - The list into which to intersperse the separator. - </p> - </td> - </tr> - </tbody> -</table> +**PARAMETERS** + +| 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-iterable"></a>iterable | The list into which to intersperse the separator. | none | + +**RETURNS** + +A new list with `separator` before each item in `iterable`. + + +<a id="#collections.uniq"></a> ## collections.uniq @@ -85,24 +61,15 @@ 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="collections.uniq-iterable"> - <td><code>iterable</code></td> - <td> - required. - <p> - An iterable to filter. - </p> - </td> - </tr> - </tbody> -</table> +**PARAMETERS** + + +| Name | Description | Default Value | +| :------------- | :------------- | :------------- | +| <a id="collections.uniq-iterable"></a>iterable | An iterable to filter. | none | + +**RETURNS** + +A new list with all unique elements from `iterable`. diff --git a/docs/common_settings_doc.md b/docs/common_settings_doc.md index 676f070..736e48c 100755 --- a/docs/common_settings_doc.md +++ b/docs/common_settings_doc.md @@ -1,6 +1,15 @@ <!-- Generated with Stardoc: http://skydoc.bazel.build --> -<a name="#bool_flag"></a> +Common build setting rules + +These rules return a BuildSettingInfo with the value of the build setting. +For label-typed settings, use the native label_flag and label_setting rules. + +More documentation on how to use build settings at +https://docs.bazel.build/versions/main/skylark/config.html#user-defined-build-settings + + +<a id="#bool_flag"></a> ## bool_flag @@ -10,28 +19,15 @@ bool_flag(<a href="#bool_flag-name">name</a>) A bool-typed build setting that can be set on the command line -### Attributes - -<table class="params-table"> - <colgroup> - <col class="col-param" /> - <col class="col-description" /> - </colgroup> - <tbody> - <tr id="bool_flag-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> - </tbody> -</table> - - -<a name="#bool_setting"></a> +**ATTRIBUTES** + + +| Name | Description | Type | Mandatory | Default | +| :------------- | :------------- | :------------- | :------------- | :------------- | +| <a id="bool_flag-name"></a>name | A unique name for this target. | <a href="https://bazel.build/docs/build-ref.html#name">Name</a> | required | | + + +<a id="#bool_setting"></a> ## bool_setting @@ -41,28 +37,15 @@ bool_setting(<a href="#bool_setting-name">name</a>) A bool-typed build setting that cannot be set on the command line -### Attributes - -<table class="params-table"> - <colgroup> - <col class="col-param" /> - <col class="col-description" /> - </colgroup> - <tbody> - <tr id="bool_setting-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> - </tbody> -</table> - - -<a name="#int_flag"></a> +**ATTRIBUTES** + + +| Name | Description | Type | Mandatory | Default | +| :------------- | :------------- | :------------- | :------------- | :------------- | +| <a id="bool_setting-name"></a>name | A unique name for this target. | <a href="https://bazel.build/docs/build-ref.html#name">Name</a> | required | | + + +<a id="#int_flag"></a> ## int_flag @@ -72,28 +55,15 @@ int_flag(<a href="#int_flag-name">name</a>) An int-typed build setting that can be set on the command line -### Attributes - -<table class="params-table"> - <colgroup> - <col class="col-param" /> - <col class="col-description" /> - </colgroup> - <tbody> - <tr id="int_flag-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> - </tbody> -</table> - - -<a name="#int_setting"></a> +**ATTRIBUTES** + + +| Name | Description | Type | Mandatory | Default | +| :------------- | :------------- | :------------- | :------------- | :------------- | +| <a id="int_flag-name"></a>name | A unique name for this target. | <a href="https://bazel.build/docs/build-ref.html#name">Name</a> | required | | + + +<a id="#int_setting"></a> ## int_setting @@ -103,28 +73,15 @@ int_setting(<a href="#int_setting-name">name</a>) An int-typed build setting that cannot be set on the command line -### Attributes - -<table class="params-table"> - <colgroup> - <col class="col-param" /> - <col class="col-description" /> - </colgroup> - <tbody> - <tr id="int_setting-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> - </tbody> -</table> - - -<a name="#string_flag"></a> +**ATTRIBUTES** + + +| Name | Description | Type | Mandatory | Default | +| :------------- | :------------- | :------------- | :------------- | :------------- | +| <a id="int_setting-name"></a>name | A unique name for this target. | <a href="https://bazel.build/docs/build-ref.html#name">Name</a> | required | | + + +<a id="#string_flag"></a> ## string_flag @@ -134,37 +91,16 @@ string_flag(<a href="#string_flag-name">name</a>, <a href="#string_flag-values"> A string-typed build setting that can be set on the command line -### Attributes - -<table class="params-table"> - <colgroup> - <col class="col-param" /> - <col class="col-description" /> - </colgroup> - <tbody> - <tr id="string_flag-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="string_flag-values"> - <td><code>values</code></td> - <td> - List of strings; optional - <p> - The list of allowed values for this setting. An error is raised if any other value is given. - </p> - </td> - </tr> - </tbody> -</table> - - -<a name="#string_list_flag"></a> +**ATTRIBUTES** + + +| Name | Description | Type | Mandatory | Default | +| :------------- | :------------- | :------------- | :------------- | :------------- | +| <a id="string_flag-name"></a>name | A unique name for this target. | <a href="https://bazel.build/docs/build-ref.html#name">Name</a> | required | | +| <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> ## string_list_flag @@ -174,28 +110,15 @@ string_list_flag(<a href="#string_list_flag-name">name</a>) A string list-typed build setting that can be set on the command line -### Attributes - -<table class="params-table"> - <colgroup> - <col class="col-param" /> - <col class="col-description" /> - </colgroup> - <tbody> - <tr id="string_list_flag-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> - </tbody> -</table> - - -<a name="#string_list_setting"></a> +**ATTRIBUTES** + + +| Name | Description | Type | Mandatory | Default | +| :------------- | :------------- | :------------- | :------------- | :------------- | +| <a id="string_list_flag-name"></a>name | A unique name for this target. | <a href="https://bazel.build/docs/build-ref.html#name">Name</a> | required | | + + +<a id="#string_list_setting"></a> ## string_list_setting @@ -205,28 +128,15 @@ string_list_setting(<a href="#string_list_setting-name">name</a>) A string list-typed build setting that cannot be set on the command line -### Attributes - -<table class="params-table"> - <colgroup> - <col class="col-param" /> - <col class="col-description" /> - </colgroup> - <tbody> - <tr id="string_list_setting-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> - </tbody> -</table> - - -<a name="#string_setting"></a> +**ATTRIBUTES** + + +| Name | Description | Type | Mandatory | Default | +| :------------- | :------------- | :------------- | :------------- | :------------- | +| <a id="string_list_setting-name"></a>name | A unique name for this target. | <a href="https://bazel.build/docs/build-ref.html#name">Name</a> | required | | + + +<a id="#string_setting"></a> ## string_setting @@ -236,37 +146,16 @@ string_setting(<a href="#string_setting-name">name</a>, <a href="#string_setting A string-typed build setting that cannot be set on the command line -### Attributes - -<table class="params-table"> - <colgroup> - <col class="col-param" /> - <col class="col-description" /> - </colgroup> - <tbody> - <tr id="string_setting-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="string_setting-values"> - <td><code>values</code></td> - <td> - List of strings; optional - <p> - The list of allowed values for this setting. An error is raised if any other value is given. - </p> - </td> - </tr> - </tbody> -</table> - - -<a name="#BuildSettingInfo"></a> +**ATTRIBUTES** + + +| Name | Description | Type | Mandatory | Default | +| :------------- | :------------- | :------------- | :------------- | :------------- | +| <a id="string_setting-name"></a>name | A unique name for this target. | <a href="https://bazel.build/docs/build-ref.html#name">Name</a> | required | | +| <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> ## BuildSettingInfo @@ -276,21 +165,11 @@ BuildSettingInfo(<a href="#BuildSettingInfo-value">value</a>) A singleton provider that contains the raw value of a build setting -### Fields - -<table class="params-table"> - <colgroup> - <col class="col-param" /> - <col class="col-description" /> - </colgroup> - <tbody> - <tr id="BuildSettingInfo-value"> - <td><code>value</code></td> - <td> - <p>The value of the build setting in the current configuration. This value may come from the command line or an upstream transition, or else it will be the build setting's default.</p> - </td> - </tr> - </tbody> -</table> +**FIELDS** + + +| Name | Description | +| :------------- | :------------- | +| <a id="BuildSettingInfo-value"></a>value | The value of the build setting in the current configuration. This value may come from the command line or an upstream transition, or else it will be the build setting's default. | diff --git a/docs/copy_file_doc.md b/docs/copy_file_doc.md index 67148bc..47a1244 100755 --- a/docs/copy_file_doc.md +++ b/docs/copy_file_doc.md @@ -1,6 +1,15 @@ <!-- Generated with Stardoc: http://skydoc.bazel.build --> -<a name="#copy_file"></a> +A rule that copies a file to another place. + +native.genrule() is sometimes used to copy files (often wishing to rename them). +The 'copy_file' rule does this with a simpler interface than genrule. + +The 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 @@ -15,78 +24,16 @@ Copies a file to another location. This rule uses a Bash command on Linux/macOS/non-Windows, and a cmd.exe command on Windows (no Bash is required). -### Parameters - -<table class="params-table"> - <colgroup> - <col class="col-param" /> - <col class="col-description" /> - </colgroup> - <tbody> - <tr id="copy_file-name"> - <td><code>name</code></td> - <td> - required. - <p> - Name of the rule. - </p> - </td> - </tr> - <tr id="copy_file-src"> - <td><code>src</code></td> - <td> - required. - <p> - A Label. The file to make a copy of. (Can also be the label of a rule - that generates a file.) - </p> - </td> - </tr> - <tr id="copy_file-out"> - <td><code>out</code></td> - <td> - required. - <p> - Path of the output file, relative to this package. - </p> - </td> - </tr> - <tr id="copy_file-is_executable"> - <td><code>is_executable</code></td> - <td> - optional. default is <code>False</code> - <p> - 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. - </p> - </td> - </tr> - <tr id="copy_file-allow_symlink"> - <td><code>allow_symlink</code></td> - <td> - optional. default is <code>False</code> - <p> - 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). - </p> - </td> - </tr> - <tr id="copy_file-kwargs"> - <td><code>kwargs</code></td> - <td> - optional. - <p> - further keyword arguments, e.g. `visibility` - </p> - </td> - </tr> - </tbody> -</table> +**PARAMETERS** + + +| Name | Description | Default Value | +| :------------- | :------------- | :------------- | +| <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 | diff --git a/docs/dicts_doc.md b/docs/dicts_doc.md index 2e95cf8..5e8bce6 100755 --- a/docs/dicts_doc.md +++ b/docs/dicts_doc.md @@ -1,3 +1,9 @@ +<!-- Generated with Stardoc: http://skydoc.bazel.build --> + +Skylib module containing functions that operate on dictionaries. + +<a id="#dicts.add"></a> + ## dicts.add <pre> @@ -15,33 +21,16 @@ 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="dicts.add-dictionaries"> - <td><code>dictionaries</code></td> - <td> - optional. - <p> - Zero or more dictionaries to be added. - </p> - </td> - </tr> - <tr id="dicts.add-kwargs"> - <td><code>kwargs</code></td> - <td> - optional. - <p> - Additional dictionary passed as keyword args. - </p> - </td> - </tr> - </tbody> -</table> +**PARAMETERS** + + +| Name | Description | Default Value | +| :------------- | :------------- | :------------- | +| <a id="dicts.add-dictionaries"></a>dictionaries | Zero or more dictionaries to be added. | none | +| <a id="dicts.add-kwargs"></a>kwargs | Additional dictionary passed as keyword args. | none | + +**RETURNS** + +A new `dict` that has all the entries of the given dictionaries. diff --git a/docs/diff_test_doc.md b/docs/diff_test_doc.md index 07ce8b9..fd62a38 100755 --- a/docs/diff_test_doc.md +++ b/docs/diff_test_doc.md @@ -1,3 +1,13 @@ +<!-- Generated with Stardoc: http://skydoc.bazel.build --> + +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 <pre> @@ -9,51 +19,14 @@ A test that compares two files. The test succeeds if the files' contents match. -### Parameters - -<table class="params-table"> - <colgroup> - <col class="col-param" /> - <col class="col-description" /> - </colgroup> - <tbody> - <tr id="diff_test-name"> - <td><code>name</code></td> - <td> - required. - <p> - The name of the test rule. - </p> - </td> - </tr> - <tr id="diff_test-file1"> - <td><code>file1</code></td> - <td> - required. - <p> - Label of the file to compare to <code>file2</code>. - </p> - </td> - </tr> - <tr id="diff_test-file2"> - <td><code>file2</code></td> - <td> - required. - <p> - Label of the file to compare to <code>file1</code>. - </p> - </td> - </tr> - <tr id="diff_test-kwargs"> - <td><code>kwargs</code></td> - <td> - optional. - <p> - The <a href="https://docs.bazel.build/versions/master/be/common-definitions.html#common-attributes-tests">common attributes for tests</a>. - </p> - </td> - </tr> - </tbody> -</table> +**PARAMETERS** + + +| 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-kwargs"></a>kwargs | The <a href="https://docs.bazel.build/versions/main/be/common-definitions.html#common-attributes-tests">common attributes for tests</a>. | none | diff --git a/docs/maintainers_guide.md b/docs/maintainers_guide.md new file mode 100644 index 0000000..8a009c2 --- /dev/null +++ b/docs/maintainers_guide.md @@ -0,0 +1,114 @@ +# Skylib Maintainer's Guide + +## The Parts of Skylib + +* `bzl_library.bzl` - used by almost all rule sets, and thus requiring + especial attention to maintaining backwards compatibility. Ideally, it ought + to be moved out of Skylib and and into Bazel's bundled `@bazel_tools` repo + (see https://github.com/bazelbuild/bazel-skylib/issues/127). +* Test libraries - `rules/analysis_test.bzl`, `rules/build_test.bzl`, + `lib/unittest.bzl`; these are under more active development than the rest of + Skylib, because we want to provide rule authors with a good testing story. + Ideally, these ought to be moved out of Skylib and evolved at a faster pace. +* A kitchen sink of utility modules (everything else). Formerly, these + features were piled on in a rather haphazard manner. For any new additions, + we want to be more conservative: add a feature only if it is widely needed + (or was already independently implemented in multiple rule sets), if the + interface is unimpeachable, if level of abstraction is not shallow, and the + implementation is efficient. + +## PR Review Standards + +Because Skylib is so widely used, breaking backwards compatibility can cause +widespread pain, and shouldn't be done lightly. Therefore: + +1. In the first place, avoid adding insufficiently thought out, insufficiently + tested features which will later need to be replaced in a + backwards-incompatible manner. See the criteria in README.md. +2. Given a choice between breaking backwards compatibilty and keeping it, try + to keep backwards compatibility. For example, if adding a new argument to a + function, add it to the end of the argument list, so that existing callers' + positional arguments continue to work. +3. Keep Skylib out-of-the-box compatible with the current stable Bazel release + (ideally - with two most recent stable releases). + * For example, when adding a new function which calls the new + `native.foobar()` method which was introduced in the latest Bazel + pre-release or is gated behind an `--incompatible` flag, use an `if + hasattr(native, "foobar")` check to keep the rest of your module (which + doesn't need `native.foobar()`) working even when `native.foobar()` is + not available. + +In addition, make sure that new code is documented and tested. + +If a PR adds or changes any docstrings, check that Markdown docs in `docs` +directory are updated; if not, ask the PR author to run +`./docs/regenerate_docs.sh`. (See +https://github.com/bazelbuild/bazel-skylib/pull/321 for the proposal to automate +this.) + +## Making a New Release + +1. Update CHANGELOG.md at the top. You may want to use the following template: + +-------------------------------------------------------------------------------- + +Release $VERSION + +**New Features** + +- Feature +- Feature + +**Incompatible Changes** + +- Change +- Change + +**Contributors** + +Name 1, Name 2, Name 3 (alphabetically from `git log`) + +-------------------------------------------------------------------------------- + +2. Bump `version` in version.bzl to the new version. +3. Ensure that the commits for steps 1 and 2 have been merged. All further + steps must be performed on a single, known-good git commit. +4. `bazel build //distribution:bazel-skylib-$VERSION.tar.gz` +5. Copy the `bazel-skylib-$VERSION.tar.gz` tarball to the mirror (you'll need + Bazel developer gcloud credentials; assuming you are a Bazel developer, you + can obtain them via `gcloud init`): + +``` +gsutil cp bazel-bin/distro/bazel-skylib-$VERSION.tar.gz gs://bazel-mirror/github.com/bazelbuild/bazel-skylib/releases/download/$VERSION/bazel-skylib-$VERSION.tar.gz +gsutil setmeta -h "Cache-Control: public, max-age=31536000" "gs://bazel-mirror/github.com/bazelbuild/bazel-skylib/releases/download/$VERSION/bazel-skylib-$VERSION.tar.gz" +``` + +6. Run `sha256sum bazel-bin/distro/bazel-skylib-$VERSION.tar.gz`; you'll need + the checksum for the release notes. +7. Draft a new release with a new tag named $VERSION in github. Attach + `bazel-skylib-$VERSION.tar.gz` to the release. For the release notes, use + the CHANGELOG.md entry plus the following template: + +-------------------------------------------------------------------------------- + +**WORKSPACE setup** + +``` +load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive") +http_archive( + name = "bazel_skylib", + urls = [ + "https://mirror.bazel.build/github.com/bazelbuild/bazel-skylib/releases/download/$VERSION/bazel-skylib-$VERSION.tar.gz", + "https://github.com/bazelbuild/bazel-skylib/releases/download/$VERSION/bazel-skylib-$VERSION.tar.gz", + ], + sha256 = "$SHA256SUM", +) +load("@bazel_skylib//:workspace.bzl", "bazel_skylib_workspace") +bazel_skylib_workspace() +``` + +**Using the rules** + +See [the source](https://github.com/bazelbuild/bazel-skylib/tree/$VERSION). + +--------------------------------------------------------------------------------
\ No newline at end of file diff --git a/docs/native_binary_doc.md b/docs/native_binary_doc.md index 9cf90f4..1a330ca 100755 --- a/docs/native_binary_doc.md +++ b/docs/native_binary_doc.md @@ -1,3 +1,15 @@ +<!-- Generated with Stardoc: http://skydoc.bazel.build --> + +native_binary() and native_test() rule implementations. + +These rules let you wrap a pre-built binary or script in a conventional binary +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_exectuable="". + + +<a id="#native_binary"></a> + ## native_binary <pre> @@ -9,60 +21,20 @@ 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. -### Parameters - -<table class="params-table"> - <colgroup> - <col class="col-param" /> - <col class="col-description" /> - </colgroup> - <tbody> - <tr id="native_binary-name"> - <td><code>name</code></td> - <td> - required. - </td> - </tr> - <tr id="native_binary-src"> - <td><code>src</code></td> - <td> - required. - <p> - label; path of the pre-built executable - </p> - </td> - </tr> - <tr id="native_binary-out"> - <td><code>out</code></td> - <td> - required. - <p> - output; an output name for the copy of the binary. (Bazel requires that this rule make a copy of 'src'.) - </p> - </td> - </tr> - <tr id="native_binary-data"> - <td><code>data</code></td> - <td> - optional. default is <code>None</code> - <p> - list of labels; data dependencies - </p> - </td> - </tr> - <tr id="native_binary-kwargs"> - <td><code>kwargs</code></td> - <td> - optional. - <p> - The <a href="https://docs.bazel.build/versions/master/be/common-definitions.html#common-attributes-binaries">common attributes for binaries</a>. - </p> - </td> - </tr> - </tbody> -</table> +**PARAMETERS** +| Name | Description | Default Value | +| :------------- | :------------- | :------------- | +| <a id="native_binary-name"></a>name | The name of the rule. | none | +| <a id="native_binary-src"></a>src | label; path of the pre-built executable | none | +| <a id="native_binary-out"></a>out | output; an output name for the copy of the binary. (Bazel requires that this rule make a copy of 'src'.) | none | +| <a id="native_binary-data"></a>data | list of labels; data dependencies | <code>None</code> | +| <a id="native_binary-kwargs"></a>kwargs | The <a href="https://docs.bazel.build/versions/main/be/common-definitions.html#common-attributes-binaries">common attributes for binaries</a>. | none | + + +<a id="#native_test"></a> + ## native_test <pre> @@ -75,57 +47,15 @@ You can "bazel test" this rule like any other test rule. You can also augment th runfiles. -### Parameters - -<table class="params-table"> - <colgroup> - <col class="col-param" /> - <col class="col-description" /> - </colgroup> - <tbody> - <tr id="native_test-name"> - <td><code>name</code></td> - <td> - required. - </td> - </tr> - <tr id="native_test-src"> - <td><code>src</code></td> - <td> - required. - <p> - label; path of the pre-built executable - </p> - </td> - </tr> - <tr id="native_test-out"> - <td><code>out</code></td> - <td> - required. - <p> - output; an output name for the copy of the binary. (Bazel requires that this rule make a copy of 'src'.) - </p> - </td> - </tr> - <tr id="native_test-data"> - <td><code>data</code></td> - <td> - optional. default is <code>None</code> - <p> - list of labels; data dependencies - </p> - </td> - </tr> - <tr id="native_test-kwargs"> - <td><code>kwargs</code></td> - <td> - optional. - <p> - The <a href="https://docs.bazel.build/versions/master/be/common-definitions.html#common-attributes-tests">common attributes for tests</a>. - </p> - </td> - </tr> - </tbody> -</table> +**PARAMETERS** + + +| Name | Description | Default Value | +| :------------- | :------------- | :------------- | +| <a id="native_test-name"></a>name | The name of the test rule. | none | +| <a id="native_test-src"></a>src | label; path of the pre-built executable | none | +| <a id="native_test-out"></a>out | output; an output name for the copy of the binary. (Bazel requires that this rule make a copy of 'src'.) | none | +| <a id="native_test-data"></a>data | list of labels; data dependencies | <code>None</code> | +| <a id="native_test-kwargs"></a>kwargs | The <a href="https://docs.bazel.build/versions/main/be/common-definitions.html#common-attributes-tests">common attributes for tests</a>. | none | diff --git a/docs/new_sets_doc.md b/docs/new_sets_doc.md index feec3b8..e34107f 100755 --- a/docs/new_sets_doc.md +++ b/docs/new_sets_doc.md @@ -1,3 +1,18 @@ +<!-- Generated with Stardoc: http://skydoc.bazel.build --> + +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 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.make"></a> + ## sets.make <pre> @@ -9,26 +24,19 @@ Creates a new set. All elements must be hashable. -### Parameters +**PARAMETERS** + + +| Name | Description | Default Value | +| :------------- | :------------- | :------------- | +| <a id="sets.make-elements"></a>elements | Optional sequence to construct the set out of. | <code>None</code> | + +**RETURNS** + +A set containing the passed in values. -<table class="params-table"> - <colgroup> - <col class="col-param" /> - <col class="col-description" /> - </colgroup> - <tbody> - <tr id="sets.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> +<a id="#sets.copy"></a> ## sets.copy @@ -38,27 +46,20 @@ sets.copy(<a href="#sets.copy-s">s</a>) 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="sets.copy-s"> - <td><code>s</code></td> - <td> - required. - <p> - A set, as returned by `sets.make()`. - </p> - </td> - </tr> - </tbody> -</table> +**PARAMETERS** +| Name | Description | Default Value | +| :------------- | :------------- | :------------- | +| <a id="sets.copy-s"></a>s | A set, as returned by <code>sets.make()</code>. | none | + +**RETURNS** + +A new set containing the same elements as `s`. + + +<a id="#sets.to_list"></a> + ## sets.to_list <pre> @@ -67,26 +68,19 @@ sets.to_list(<a href="#sets.to_list-s">s</a>) 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="sets.to_list-s"> - <td><code>s</code></td> - <td> - required. - <p> - A set, as returned by `sets.make()`. - </p> - </td> - </tr> - </tbody> -</table> +**PARAMETERS** + + +| Name | Description | Default Value | +| :------------- | :------------- | :------------- | +| <a id="sets.to_list-s"></a>s | A set, as returned by <code>sets.make()</code>. | none | + +**RETURNS** + +A list of values inserted into the set. + +<a id="#sets.insert"></a> ## sets.insert @@ -99,36 +93,21 @@ Inserts an element into the set. Element must be hashable. This mutates the original set. -### Parameters - -<table class="params-table"> - <colgroup> - <col class="col-param" /> - <col class="col-description" /> - </colgroup> - <tbody> - <tr id="sets.insert-s"> - <td><code>s</code></td> - <td> - required. - <p> - A set, as returned by `sets.make()`. - </p> - </td> - </tr> - <tr id="sets.insert-e"> - <td><code>e</code></td> - <td> - required. - <p> - The element to be inserted. - </p> - </td> - </tr> - </tbody> -</table> +**PARAMETERS** +| 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-e"></a>e | The element to be inserted. | none | + +**RETURNS** + +The set `s` with `e` included. + + +<a id="#sets.contains"></a> + ## sets.contains <pre> @@ -137,35 +116,20 @@ sets.contains(<a href="#sets.contains-a">a</a>, <a href="#sets.contains-e">e</a> 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="sets.contains-a"> - <td><code>a</code></td> - <td> - required. - <p> - A set, as returned by `sets.make()`. - </p> - </td> - </tr> - <tr id="sets.contains-e"> - <td><code>e</code></td> - <td> - required. - <p> - The element to look for. - </p> - </td> - </tr> - </tbody> -</table> +**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 | + +**RETURNS** + +True if the element exists in the set, False if the element does not. + +<a id="#sets.is_equal"></a> ## sets.is_equal @@ -175,36 +139,21 @@ sets.is_equal(<a href="#sets.is_equal-a">a</a>, <a href="#sets.is_equal-b">b</a> Returns whether two sets are equal. -### Parameters - -<table class="params-table"> - <colgroup> - <col class="col-param" /> - <col class="col-description" /> - </colgroup> - <tbody> - <tr id="sets.is_equal-a"> - <td><code>a</code></td> - <td> - required. - <p> - A set, as returned by `sets.make()`. - </p> - </td> - </tr> - <tr id="sets.is_equal-b"> - <td><code>b</code></td> - <td> - required. - <p> - A set, as returned by `sets.make()`. - </p> - </td> - </tr> - </tbody> -</table> +**PARAMETERS** +| 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 | + +**RETURNS** + +True if `a` is equal to `b`, False otherwise. + + +<a id="#sets.is_subset"></a> + ## sets.is_subset <pre> @@ -213,35 +162,20 @@ sets.is_subset(<a href="#sets.is_subset-a">a</a>, <a href="#sets.is_subset-b">b< 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="sets.is_subset-a"> - <td><code>a</code></td> - <td> - required. - <p> - A set, as returned by `sets.make()`. - </p> - </td> - </tr> - <tr id="sets.is_subset-b"> - <td><code>b</code></td> - <td> - required. - <p> - A set, as returned by `sets.make()`. - </p> - </td> - </tr> - </tbody> -</table> +**PARAMETERS** + + +| 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 | + +**RETURNS** + +True if `a` is a subset of `b`, False otherwise. + +<a id="#sets.disjoint"></a> ## sets.disjoint @@ -254,36 +188,21 @@ 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="sets.disjoint-a"> - <td><code>a</code></td> - <td> - required. - <p> - A set, as returned by `sets.make()`. - </p> - </td> - </tr> - <tr id="sets.disjoint-b"> - <td><code>b</code></td> - <td> - required. - <p> - A set, as returned by `sets.make()`. - </p> - </td> - </tr> - </tbody> -</table> +**PARAMETERS** +| 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 | + +**RETURNS** + +True if `a` and `b` are disjoint, False otherwise. + + +<a id="#sets.intersection"></a> + ## sets.intersection <pre> @@ -292,35 +211,20 @@ sets.intersection(<a href="#sets.intersection-a">a</a>, <a href="#sets.intersect Returns the intersection of two sets. -### Parameters - -<table class="params-table"> - <colgroup> - <col class="col-param" /> - <col class="col-description" /> - </colgroup> - <tbody> - <tr id="sets.intersection-a"> - <td><code>a</code></td> - <td> - required. - <p> - A set, as returned by `sets.make()`. - </p> - </td> - </tr> - <tr id="sets.intersection-b"> - <td><code>b</code></td> - <td> - required. - <p> - A set, as returned by `sets.make()`. - </p> - </td> - </tr> - </tbody> -</table> +**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 | + +**RETURNS** + +A set containing the elements that are in both `a` and `b`. + +<a id="#sets.union"></a> ## sets.union @@ -330,27 +234,20 @@ sets.union(<a href="#sets.union-args">args</a>) Returns the union of several sets. -### Parameters - -<table class="params-table"> - <colgroup> - <col class="col-param" /> - <col class="col-description" /> - </colgroup> - <tbody> - <tr id="sets.union-args"> - <td><code>args</code></td> - <td> - optional. - <p> - An arbitrary number of sets or lists. - </p> - </td> - </tr> - </tbody> -</table> +**PARAMETERS** +| Name | Description | Default Value | +| :------------- | :------------- | :------------- | +| <a id="sets.union-args"></a>args | An arbitrary number of sets. | none | + +**RETURNS** + +The set union of all sets in `*args`. + + +<a id="#sets.difference"></a> + ## sets.difference <pre> @@ -359,35 +256,20 @@ sets.difference(<a href="#sets.difference-a">a</a>, <a href="#sets.difference-b" 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="sets.difference-a"> - <td><code>a</code></td> - <td> - required. - <p> - A set, as returned by `sets.make()`. - </p> - </td> - </tr> - <tr id="sets.difference-b"> - <td><code>b</code></td> - <td> - required. - <p> - A set, as returned by `sets.make()`. - </p> - </td> - </tr> - </tbody> -</table> +**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 @@ -397,27 +279,20 @@ sets.length(<a href="#sets.length-s">s</a>) 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="sets.length-s"> - <td><code>s</code></td> - <td> - required. - <p> - A set, as returned by `sets.make()`. - </p> - </td> - </tr> - </tbody> -</table> +**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> @@ -429,35 +304,20 @@ Removes an element from the set. Element must be hashable. This mutates the original set. -### Parameters - -<table class="params-table"> - <colgroup> - <col class="col-param" /> - <col class="col-description" /> - </colgroup> - <tbody> - <tr id="sets.remove-s"> - <td><code>s</code></td> - <td> - required. - <p> - A set, as returned by `sets.make()`. - </p> - </td> - </tr> - <tr id="sets.remove-e"> - <td><code>e</code></td> - <td> - required. - <p> - The element to be removed. - </p> - </td> - </tr> - </tbody> -</table> +**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 @@ -467,27 +327,20 @@ sets.repr(<a href="#sets.repr-s">s</a>) 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="sets.repr-s"> - <td><code>s</code></td> - <td> - required. - <p> - A set, as returned by `sets.make()`. - </p> - </td> - </tr> - </tbody> -</table> +**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> @@ -496,24 +349,15 @@ sets.str(<a href="#sets.str-s">s</a>) 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="sets.str-s"> - <td><code>s</code></td> - <td> - required. - <p> - A set, as returned by `sets.make()`. - </p> - </td> - </tr> - </tbody> -</table> +**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. diff --git a/docs/partial_doc.md b/docs/partial_doc.md index 4559ba3..d772ec8 100755 --- a/docs/partial_doc.md +++ b/docs/partial_doc.md @@ -1,3 +1,14 @@ +<!-- Generated with Stardoc: http://skydoc.bazel.build --> + +Starlark module for working with partial function objects. + +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.make"></a> + ## partial.make <pre> @@ -12,16 +23,22 @@ 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 @@ -29,24 +46,30 @@ 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 + "!") + 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 @@ -56,16 +79,20 @@ 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!". @@ -73,52 +100,30 @@ 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** -### Parameters - -<table class="params-table"> - <colgroup> - <col class="col-param" /> - <col class="col-description" /> - </colgroup> - <tbody> - <tr id="partial.make-func"> - <td><code>func</code></td> - <td> - required. - <p> - The function to be called. - </p> - </td> - </tr> - <tr id="partial.make-args"> - <td><code>args</code></td> - <td> - optional. - <p> - Positional arguments to be passed to function. - </p> - </td> - </tr> - <tr id="partial.make-kwargs"> - <td><code>kwargs</code></td> - <td> - optional. - <p> - Keyword arguments to be passed to function. Note that these can - be overridden at the call sites. - </p> - </td> - </tr> - </tbody> -</table> +| Name | Description | Default Value | +| :------------- | :------------- | :------------- | +| <a id="partial.make-func"></a>func | The function to be called. | none | +| <a id="partial.make-args"></a>args | Positional arguments to be passed to function. | none | +| <a id="partial.make-kwargs"></a>kwargs | Keyword arguments to be passed to function. Note that these can be overridden at the call sites. | none | + +**RETURNS** + +A new `partial` that can be called using `call` + + +<a id="#partial.call"></a> ## partial.call @@ -128,44 +133,39 @@ partial.call(<a href="#partial.call-partial">partial</a>, <a href="#partial.call Calls a partial created using `make`. -### Parameters - -<table class="params-table"> - <colgroup> - <col class="col-param" /> - <col class="col-description" /> - </colgroup> - <tbody> - <tr id="partial.call-partial"> - <td><code>partial</code></td> - <td> - required. - <p> - The partial to be called. - </p> - </td> - </tr> - <tr id="partial.call-args"> - <td><code>args</code></td> - <td> - optional. - <p> - Additional positional arguments to be appended to the ones given to - make. - </p> - </td> - </tr> - <tr id="partial.call-kwargs"> - <td><code>kwargs</code></td> - <td> - optional. - <p> - Additional keyword arguments to augment and override the ones - given to make. - </p> - </td> - </tr> - </tbody> -</table> +**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. diff --git a/docs/paths_doc.md b/docs/paths_doc.md index 8797c01..e0d8116 100755 --- a/docs/paths_doc.md +++ b/docs/paths_doc.md @@ -1,3 +1,14 @@ +<!-- Generated with Stardoc: http://skydoc.bazel.build --> + +Skylib module containing file path manipulation functions. + +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 <pre> @@ -12,26 +23,19 @@ the Unix `basename` command (which would return the path segment preceding the final slash). -### Parameters +**PARAMETERS** + -<table class="params-table"> - <colgroup> - <col class="col-param" /> - <col class="col-description" /> - </colgroup> - <tbody> - <tr id="paths.basename-p"> - <td><code>p</code></td> - <td> - required. - <p> - The path whose basename should be returned. - </p> - </td> - </tr> - </tbody> -</table> +| Name | Description | Default Value | +| :------------- | :------------- | :------------- | +| <a id="paths.basename-p"></a>p | The path whose basename should be returned. | none | +**RETURNS** + +The basename of the path, which includes the extension. + + +<a id="#paths.dirname"></a> ## paths.dirname @@ -46,26 +50,19 @@ The dirname is the portion of `p` up to but not including the file portion included, unless omitting them would make the dirname empty. -### Parameters +**PARAMETERS** + + +| Name | Description | Default Value | +| :------------- | :------------- | :------------- | +| <a id="paths.dirname-p"></a>p | The path whose dirname should be returned. | none | -<table class="params-table"> - <colgroup> - <col class="col-param" /> - <col class="col-description" /> - </colgroup> - <tbody> - <tr id="paths.dirname-p"> - <td><code>p</code></td> - <td> - required. - <p> - The path whose dirname should be returned. - </p> - </td> - </tr> - </tbody> -</table> +**RETURNS** +The dirname of the path. + + +<a id="#paths.is_absolute"></a> ## paths.is_absolute @@ -75,26 +72,19 @@ paths.is_absolute(<a href="#paths.is_absolute-path">path</a>) 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="paths.is_absolute-path"> - <td><code>path</code></td> - <td> - required. - <p> - A path (which is a string). - </p> - </td> - </tr> - </tbody> -</table> +**PARAMETERS** + + +| Name | Description | Default Value | +| :------------- | :------------- | :------------- | +| <a id="paths.is_absolute-path"></a>path | A path (which is a string). | none | + +**RETURNS** +`True` if `path` is an absolute path. + + +<a id="#paths.join"></a> ## paths.join @@ -113,35 +103,20 @@ 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="paths.join-path"> - <td><code>path</code></td> - <td> - required. - <p> - A path segment. - </p> - </td> - </tr> - <tr id="paths.join-others"> - <td><code>others</code></td> - <td> - optional. - <p> - Additional path segments. - </p> - </td> - </tr> - </tbody> -</table> +**PARAMETERS** + + +| Name | Description | Default Value | +| :------------- | :------------- | :------------- | +| <a id="paths.join-path"></a>path | A path segment. | none | +| <a id="paths.join-others"></a>others | Additional path segments. | none | + +**RETURNS** +A string containing the joined paths. + + +<a id="#paths.normalize"></a> ## paths.normalize @@ -166,27 +141,20 @@ POSIX platforms; specifically: - Multiple adjacent internal slashes are collapsed into a single slash. -### Parameters +**PARAMETERS** + + +| Name | Description | Default Value | +| :------------- | :------------- | :------------- | +| <a id="paths.normalize-path"></a>path | A path. | none | + +**RETURNS** -<table class="params-table"> - <colgroup> - <col class="col-param" /> - <col class="col-description" /> - </colgroup> - <tbody> - <tr id="paths.normalize-path"> - <td><code>path</code></td> - <td> - required. - <p> - A path. - </p> - </td> - </tr> - </tbody> -</table> +The normalized path. +<a id="#paths.relativize"></a> + ## paths.relativize <pre> @@ -204,36 +172,21 @@ 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="paths.relativize-path"> - <td><code>path</code></td> - <td> - required. - <p> - The path to relativize. - </p> - </td> - </tr> - <tr id="paths.relativize-start"> - <td><code>start</code></td> - <td> - required. - <p> - The ancestor path against which to relativize. - </p> - </td> - </tr> - </tbody> -</table> +**PARAMETERS** + + +| Name | Description | Default Value | +| :------------- | :------------- | :------------- | +| <a id="paths.relativize-path"></a>path | The path to relativize. | none | +| <a id="paths.relativize-start"></a>start | The ancestor path against which to relativize. | none | + +**RETURNS** + +The portion of `path` that is relative to `start`. +<a id="#paths.replace_extension"></a> + ## paths.replace_extension <pre> @@ -245,37 +198,21 @@ 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="paths.replace_extension-p"> - <td><code>p</code></td> - <td> - required. - <p> - The path whose extension should be replaced. - </p> - </td> - </tr> - <tr id="paths.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> +**PARAMETERS** + + +| Name | Description | Default Value | +| :------------- | :------------- | :------------- | +| <a id="paths.replace_extension-p"></a>p | The path whose extension should be replaced. | none | +| <a id="paths.replace_extension-new_extension"></a>new_extension | The new extension for the file. The new extension should begin with a dot if you want the new filename to have one. | none | + +**RETURNS** + +The path with the extension replaced (or added, if it did not have one). +<a id="#paths.split_extension"></a> + ## paths.split_extension <pre> @@ -288,24 +225,18 @@ 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="paths.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> +**PARAMETERS** + + +| Name | Description | Default Value | +| :------------- | :------------- | :------------- | +| <a id="paths.split_extension-p"></a>p | The path whose root and extension should be split. | none | + +**RETURNS** + +A tuple `(root, ext)` such that the root is the path without the file +extension, and `ext` is the file extension (which, if non-empty, contains +the leading dot). The returned tuple always satisfies the relationship +`root + ext == p`. diff --git a/docs/regenerate_docs.sh b/docs/regenerate_docs.sh index 2ab9a08..d16ea63 100755 --- a/docs/regenerate_docs.sh +++ b/docs/regenerate_docs.sh @@ -1,4 +1,4 @@ -#!/bin/bash +#!/usr/bin/env bash # Copyright 2019 The Bazel Authors. All rights reserved. # @@ -19,7 +19,7 @@ set -euo pipefail -bazel build docs:all --experimental_remap_main_repo +bazel build docs:all for filename in bazel-bin/docs/*_gen.md; do target_filename="$(echo $filename | sed -En "s/bazel-bin\/(.*)_gen.md/\1/p").md" diff --git a/docs/run_binary_doc.md b/docs/run_binary_doc.md index 188e277..96bada5 100755 --- a/docs/run_binary_doc.md +++ b/docs/run_binary_doc.md @@ -1,4 +1,13 @@ -<a name="#run_binary"></a> +<!-- 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> @@ -7,69 +16,16 @@ run_binary(<a href="#run_binary-name">name</a>, <a href="#run_binary-args">args< Runs a binary as a build action.<br/><br/>This rule does not require Bash (unlike <code>native.genrule</code>). -### Attributes +**ATTRIBUTES** + -<table class="params-table"> - <colgroup> - <col class="col-param" /> - <col class="col-description" /> - </colgroup> - <tbody> - <tr id="run_binary-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="run_binary-args"> - <td><code>args</code></td> - <td> - List of strings; optional - <p> - Command line arguments of the binary.<br/><br/>Subject to<code><a href="https://docs.bazel.build/versions/master/be/make-variables.html#location">$(location)</a></code> expansion. - </p> - </td> - </tr> - <tr id="run_binary-env"> - <td><code>env</code></td> - <td> - <a href="https://bazel.build/docs/skylark/lib/dict.html">Dictionary: String -> String</a>; optional - <p> - Environment variables of the action.<br/><br/>Subject to <code><a href="https://docs.bazel.build/versions/master/be/make-variables.html#location">$(location)</a></code> expansion. - </p> - </td> - </tr> - <tr id="run_binary-outs"> - <td><code>outs</code></td> - <td> - List of labels; required - <p> - 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>. - </p> - </td> - </tr> - <tr id="run_binary-srcs"> - <td><code>srcs</code></td> - <td> - <a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a>; optional - <p> - Additional inputs of the action.<br/><br/>These labels are available for <code>$(location)</code> expansion in <code>args</code> and <code>env</code>. - </p> - </td> - </tr> - <tr id="run_binary-tool"> - <td><code>tool</code></td> - <td> - <a href="https://bazel.build/docs/build-ref.html#labels">Label</a>; required - <p> - 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>. - </p> - </td> - </tr> - </tbody> -</table> +| Name | Description | Type | Mandatory | Default | +| :------------- | :------------- | :------------- | :------------- | :------------- | +| <a id="run_binary-name"></a>name | A unique name for this target. | <a href="https://bazel.build/docs/build-ref.html#name">Name</a> | required | | +| <a id="run_binary-args"></a>args | Command line arguments of the binary.<br/><br/>Subject to<code><a href="https://docs.bazel.build/versions/main/be/make-variables.html#location">$(location)</a></code> expansion. | List of strings | optional | [] | +| <a id="run_binary-env"></a>env | Environment variables of the action.<br/><br/>Subject to <code><a href="https://docs.bazel.build/versions/main/be/make-variables.html#location">$(location)</a></code> expansion. | <a href="https://bazel.build/docs/skylark/lib/dict.html">Dictionary: String -> String</a> | optional | {} | +| <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/docs/build-ref.html#labels">List of labels</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 <code>$(location)</code> expansion in <code>args</code> and <code>env</code>. | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | required | | diff --git a/docs/selects_doc.md b/docs/selects_doc.md index 55711c9..8bfd964 100755 --- a/docs/selects_doc.md +++ b/docs/selects_doc.md @@ -1,6 +1,8 @@ <!-- Generated with Stardoc: http://skydoc.bazel.build --> -<a name="#selects.with_or"></a> +Skylib module containing convenience interfaces for select(). + +<a id="#selects.with_or"></a> ## selects.with_or @@ -24,40 +26,29 @@ Example: Key labels may appear at most once anywhere in the input. -### Parameters - -<table class="params-table"> - <colgroup> - <col class="col-param" /> - <col class="col-description" /> - </colgroup> - <tbody> - <tr id="selects.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="selects.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. - </p> - </td> - </tr> - </tbody> -</table> - - -<a name="#selects.with_or_dict"></a> +**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 @@ -71,33 +62,24 @@ Unlike `select()`, the contents of the dict can be inspected by Starlark macros. -### Parameters +**PARAMETERS** + + +| Name | Description | Default Value | +| :------------- | :------------- | :------------- | +| <a id="selects.with_or_dict-input_dict"></a>input_dict | Same as <code>with_or</code>. | none | -<table class="params-table"> - <colgroup> - <col class="col-param" /> - <col class="col-description" /> - </colgroup> - <tbody> - <tr id="selects.with_or_dict-input_dict"> - <td><code>input_dict</code></td> - <td> - required. - <p> - Same as `with_or`. - </p> - </td> - </tr> - </tbody> -</table> +**RETURNS** +A dictionary usable by a native `select()`. -<a name="#selects.config_setting_group"></a> + +<a id="#selects.config_setting_group"></a> ## selects.config_setting_group <pre> -selects.config_setting_group(<a href="#selects.config_setting_group-name">name</a>, <a href="#selects.config_setting_group-match_any">match_any</a>, <a href="#selects.config_setting_group-match_all">match_all</a>) +selects.config_setting_group(<a href="#selects.config_setting_group-name">name</a>, <a href="#selects.config_setting_group-match_any">match_any</a>, <a href="#selects.config_setting_group-match_all">match_all</a>, <a href="#selects.config_setting_group-visibility">visibility</a>) </pre> Matches if all or any of its member `config_setting`s match. @@ -124,45 +106,14 @@ Example: ``` -### Parameters - -<table class="params-table"> - <colgroup> - <col class="col-param" /> - <col class="col-description" /> - </colgroup> - <tbody> - <tr id="selects.config_setting_group-name"> - <td><code>name</code></td> - <td> - required. - <p> - The group's name. This is how `select()`s reference it. - </p> - </td> - </tr> - <tr id="selects.config_setting_group-match_any"> - <td><code>match_any</code></td> - <td> - optional. default is <code>[]</code> - <p> - 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. - </p> - </td> - </tr> - <tr id="selects.config_setting_group-match_all"> - <td><code>match_all</code></td> - <td> - optional. default is <code>[]</code> - <p> - 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. - </p> - </td> - </tr> - </tbody> -</table> +**PARAMETERS** + + +| 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> | diff --git a/docs/shell_doc.md b/docs/shell_doc.md index 6c655be..0759434 100755 --- a/docs/shell_doc.md +++ b/docs/shell_doc.md @@ -1,3 +1,9 @@ +<!-- Generated with Stardoc: http://skydoc.bazel.build --> + +Skylib module containing shell utility functions. + +<a id="#shell.array_literal"></a> + ## shell.array_literal <pre> @@ -14,27 +20,20 @@ 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="shell.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> +**PARAMETERS** + + +| 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 | + +**RETURNS** +A string that represents the sequence as a shell array; that is, +parentheses containing the quoted elements. + + +<a id="#shell.quote"></a> ## shell.quote @@ -48,24 +47,15 @@ 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="shell.quote-s"> - <td><code>s</code></td> - <td> - required. - <p> - The string to quote. - </p> - </td> - </tr> - </tbody> -</table> +**PARAMETERS** + + +| Name | Description | Default Value | +| :------------- | :------------- | :------------- | +| <a id="shell.quote-s"></a>s | The string to quote. | none | + +**RETURNS** + +A quoted version of the string that can be passed to a shell command. diff --git a/docs/structs_doc.md b/docs/structs_doc.md index 3b742cb..a409d86 100755 --- a/docs/structs_doc.md +++ b/docs/structs_doc.md @@ -1,3 +1,9 @@ +<!-- Generated with Stardoc: http://skydoc.bazel.build --> + +Skylib module containing functions that operate on structs. + +<a id="#structs.to_dict"></a> + ## structs.to_dict <pre> @@ -6,24 +12,17 @@ structs.to_dict(<a href="#structs.to_dict-s">s</a>) Converts a `struct` to a `dict`. -### Parameters - -<table class="params-table"> - <colgroup> - <col class="col-param" /> - <col class="col-description" /> - </colgroup> - <tbody> - <tr id="structs.to_dict-s"> - <td><code>s</code></td> - <td> - required. - <p> - A `struct`. - </p> - </td> - </tr> - </tbody> -</table> +**PARAMETERS** + + +| Name | Description | Default Value | +| :------------- | :------------- | :------------- | +| <a id="structs.to_dict-s"></a>s | A <code>struct</code>. | none | + +**RETURNS** + +A `dict` whose keys and values are the same as the fields in `s`. The +transformation is only applied to the struct's fields and not to any +nested values. diff --git a/docs/types_doc.md b/docs/types_doc.md index 038ae0a..7ab0a6c 100755 --- a/docs/types_doc.md +++ b/docs/types_doc.md @@ -1,3 +1,9 @@ +<!-- Generated with Stardoc: http://skydoc.bazel.build --> + +Skylib module containing functions checking types. + +<a id="#types.is_list"></a> + ## types.is_list <pre> @@ -6,26 +12,19 @@ types.is_list(<a href="#types.is_list-v">v</a>) 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="types.is_list-v"> - <td><code>v</code></td> - <td> - required. - <p> - The value whose type should be checked. - </p> - </td> - </tr> - </tbody> -</table> +**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 @@ -35,27 +34,20 @@ types.is_string(<a href="#types.is_string-v">v</a>) 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="types.is_string-v"> - <td><code>v</code></td> - <td> - required. - <p> - The value whose type should be checked. - </p> - </td> - </tr> - </tbody> -</table> +**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 <pre> @@ -64,26 +56,19 @@ types.is_bool(<a href="#types.is_bool-v">v</a>) 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="types.is_bool-v"> - <td><code>v</code></td> - <td> - required. - <p> - The value whose type should be checked. - </p> - </td> - </tr> - </tbody> -</table> +**PARAMETERS** + + +| Name | Description | Default Value | +| :------------- | :------------- | :------------- | +| <a id="types.is_bool-v"></a>v | The value whose type should be checked. | none | +**RETURNS** + +True if v is an instance of a bool, False otherwise. + + +<a id="#types.is_none"></a> ## types.is_none @@ -93,26 +78,19 @@ types.is_none(<a href="#types.is_none-v">v</a>) 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="types.is_none-v"> - <td><code>v</code></td> - <td> - required. - <p> - The value whose type should be checked. - </p> - </td> - </tr> - </tbody> -</table> +**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_int"></a> ## types.is_int @@ -122,27 +100,20 @@ types.is_int(<a href="#types.is_int-v">v</a>) 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="types.is_int-v"> - <td><code>v</code></td> - <td> - required. - <p> - The value whose type should be checked. - </p> - </td> - </tr> - </tbody> -</table> +**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> @@ -151,26 +122,19 @@ types.is_tuple(<a href="#types.is_tuple-v">v</a>) 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="types.is_tuple-v"> - <td><code>v</code></td> - <td> - required. - <p> - The value whose type should be checked. - </p> - </td> - </tr> - </tbody> -</table> +**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. + + +<a id="#types.is_dict"></a> ## types.is_dict @@ -180,26 +144,19 @@ types.is_dict(<a href="#types.is_dict-v">v</a>) 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="types.is_dict-v"> - <td><code>v</code></td> - <td> - required. - <p> - The value whose type should be checked. - </p> - </td> - </tr> - </tbody> -</table> +**PARAMETERS** + + +| Name | Description | Default Value | +| :------------- | :------------- | :------------- | +| <a id="types.is_dict-v"></a>v | The value whose type should be checked. | none | + +**RETURNS** + +True if v is an instance of a dict, False otherwise. + +<a id="#types.is_function"></a> ## types.is_function @@ -209,27 +166,20 @@ types.is_function(<a href="#types.is_function-v">v</a>) 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="types.is_function-v"> - <td><code>v</code></td> - <td> - required. - <p> - The value whose type should be checked. - </p> - </td> - </tr> - </tbody> -</table> +**PARAMETERS** +| Name | Description | Default Value | +| :------------- | :------------- | :------------- | +| <a id="types.is_function-v"></a>v | The value whose type should be checked. | none | + +**RETURNS** + +True if v is an instance of a function, False otherwise. + + +<a id="#types.is_depset"></a> + ## types.is_depset <pre> @@ -238,24 +188,37 @@ types.is_depset(<a href="#types.is_depset-v">v</a>) 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="types.is_depset-v"> - <td><code>v</code></td> - <td> - required. - <p> - The value whose type should be checked. - </p> - </td> - </tr> - </tbody> -</table> +**PARAMETERS** + + +| Name | Description | Default Value | +| :------------- | :------------- | :------------- | +| <a id="types.is_depset-v"></a>v | The value whose type should be checked. | none | + +**RETURNS** + +True if v is an instance of a `depset`, False otherwise. + + +<a id="#types.is_set"></a> + +## types.is_set + +<pre> +types.is_set(<a href="#types.is_set-v">v</a>) +</pre> + +Returns True if v is a set created by sets.make(). + +**PARAMETERS** + + +| Name | Description | Default Value | +| :------------- | :------------- | :------------- | +| <a id="types.is_set-v"></a>v | The value whose type should be checked. | none | + +**RETURNS** + +True if v was created by sets.make(), False otherwise. diff --git a/docs/unittest_doc.md b/docs/unittest_doc.md index 4fbd96f..5472d74 100755 --- a/docs/unittest_doc.md +++ b/docs/unittest_doc.md @@ -1,61 +1,44 @@ -<a name="#unittest_toolchain"></a> +<!-- Generated with Stardoc: http://skydoc.bazel.build --> + +Unit testing support. + +Unlike most Skylib files, this exports two modules: `unittest` which contains +functions to declare and define unit tests, and `asserts` which contains the +assertions used to within tests. + + +<a id="#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>) +unittest_toolchain(<a href="#unittest_toolchain-name">name</a>, <a href="#unittest_toolchain-escape_chars_with">escape_chars_with</a>, <a href="#unittest_toolchain-escape_other_chars_with">escape_other_chars_with</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> +**ATTRIBUTES** + + +| Name | Description | Type | Mandatory | Default | +| :------------- | :------------- | :------------- | :------------- | :------------- | +| <a id="unittest_toolchain-name"></a>name | A unique name for this target. | <a href="https://bazel.build/docs/build-ref.html#name">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>{"%": "%", ">": "^"}</code> would replace <code>%</code> with <code>%%</code> and <code>></code> with <code>^></code> in the failure message before that is included in <code>success_templ</code>. | <a href="https://bazel.build/docs/skylark/lib/dict.html">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 <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 | "" | +| <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-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-success_templ"></a>success_templ | Test script generated when the test passes. Should exit with status 0. | String | required | | +<a id="#analysistest.make"></a> + ## analysistest.make <pre> -analysistest.make(<a href="#analysistest.make-impl">impl</a>, <a href="#analysistest.make-expect_failure">expect_failure</a>, <a href="#analysistest.make-attrs">attrs</a>, <a href="#analysistest.make-config_settings">config_settings</a>) +analysistest.make(<a href="#analysistest.make-impl">impl</a>, <a href="#analysistest.make-expect_failure">expect_failure</a>, <a href="#analysistest.make-attrs">attrs</a>, <a href="#analysistest.make-fragments">fragments</a>, <a href="#analysistest.make-config_settings">config_settings</a>, + <a href="#analysistest.make-extra_target_under_test_aspects">extra_target_under_test_aspects</a>, <a href="#analysistest.make-doc">doc</a>) </pre> Creates an analysis test rule from its implementation function. @@ -84,58 +67,26 @@ 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="analysistest.make-impl"> - <td><code>impl</code></td> - <td> - required. - <p> - The implementation function of the unit test. - </p> - </td> - </tr> - <tr id="analysistest.make-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="analysistest.make-attrs"> - <td><code>attrs</code></td> - <td> - optional. default is <code>{}</code> - <p> - An optional dictionary to supplement the attrs passed to the - unit test's `rule()` constructor. - </p> - </td> - </tr> - <tr id="analysistest.make-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> +**PARAMETERS** + + +| 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> | + +**RETURNS** +A rule definition that should be stored in a global whose name ends in +`_test`. + + +<a id="#analysistest.begin"></a> ## analysistest.begin @@ -151,27 +102,21 @@ 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="analysistest.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> +**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 +`unittest.end`. Do not rely on internal details about the fields in this +struct as it may change. + + +<a id="#analysistest.end"></a> ## analysistest.end @@ -185,27 +130,20 @@ This must be called and returned at the end of an analysis test implementation f that the results are reported. -### Parameters +**PARAMETERS** + + +| Name | Description | Default Value | +| :------------- | :------------- | :------------- | +| <a id="analysistest.end-env"></a>env | The test environment returned by <code>analysistest.begin</code>. | none | + +**RETURNS** -<table class="params-table"> - <colgroup> - <col class="col-param" /> - <col class="col-description" /> - </colgroup> - <tbody> - <tr id="analysistest.end-env"> - <td><code>env</code></td> - <td> - required. - <p> - The test environment returned by `analysistest.begin`. - </p> - </td> - </tr> - </tbody> -</table> +A list of providers needed to automatically register the analysis test result. +<a id="#analysistest.fail"></a> + ## analysistest.fail <pre> @@ -214,35 +152,16 @@ analysistest.fail(<a href="#analysistest.fail-env">env</a>, <a href="#analysiste 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="analysistest.fail-env"> - <td><code>env</code></td> - <td> - required. - <p> - The test environment returned by `unittest.begin`. - </p> - </td> - </tr> - <tr id="analysistest.fail-msg"> - <td><code>msg</code></td> - <td> - required. - <p> - The message to log describing the failure. - </p> - </td> - </tr> - </tbody> -</table> +**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 @@ -252,26 +171,41 @@ analysistest.target_actions(<a href="#analysistest.target_actions-env">env</a>) 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="analysistest.target_actions-env"> - <td><code>env</code></td> - <td> - required. - <p> - The test environment returned by `analysistest.begin`. - </p> - </td> - </tr> - </tbody> -</table> +**PARAMETERS** + + +| Name | Description | Default Value | +| :------------- | :------------- | :------------- | +| <a id="analysistest.target_actions-env"></a>env | The test environment returned by <code>analysistest.begin</code>. | none | + +**RETURNS** +A list of actions registered by the target under test + + +<a id="#analysistest.target_bin_dir_path"></a> + +## analysistest.target_bin_dir_path + +<pre> +analysistest.target_bin_dir_path(<a href="#analysistest.target_bin_dir_path-env">env</a>) +</pre> + +Returns ctx.bin_dir.path for the target under test. + +**PARAMETERS** + + +| Name | Description | Default Value | +| :------------- | :------------- | :------------- | +| <a id="analysistest.target_bin_dir_path-env"></a>env | The test environment returned by <code>analysistest.begin</code>. | none | + +**RETURNS** + +Output bin dir path string. + + +<a id="#analysistest.target_under_test"></a> ## analysistest.target_under_test @@ -281,27 +215,20 @@ analysistest.target_under_test(<a href="#analysistest.target_under_test-env">env Returns the target under test. -### Parameters - -<table class="params-table"> - <colgroup> - <col class="col-param" /> - <col class="col-description" /> - </colgroup> - <tbody> - <tr id="analysistest.target_under_test-env"> - <td><code>env</code></td> - <td> - required. - <p> - The test environment returned by `analysistest.begin`. - </p> - </td> - </tr> - </tbody> -</table> +**PARAMETERS** +| Name | Description | Default Value | +| :------------- | :------------- | :------------- | +| <a id="analysistest.target_under_test-env"></a>env | The test environment returned by <code>analysistest.begin</code>. | none | + +**RETURNS** + +The target under test. + + +<a id="#asserts.expect_failure"></a> + ## asserts.expect_failure <pre> @@ -314,36 +241,17 @@ 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="asserts.expect_failure-env"> - <td><code>env</code></td> - <td> - required. - <p> - The test environment returned by `analysistest.begin`. - </p> - </td> - </tr> - <tr id="asserts.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> +**PARAMETERS** + + +| 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> @@ -352,55 +260,19 @@ asserts.equals(<a href="#asserts.equals-env">env</a>, <a href="#asserts.equals-e 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="asserts.equals-env"> - <td><code>env</code></td> - <td> - required. - <p> - The test environment returned by `unittest.begin`. - </p> - </td> - </tr> - <tr id="asserts.equals-expected"> - <td><code>expected</code></td> - <td> - required. - <p> - The expected value of some computation. - </p> - </td> - </tr> - <tr id="asserts.equals-actual"> - <td><code>actual</code></td> - <td> - required. - <p> - The actual value returned by some computation. - </p> - </td> - </tr> - <tr id="asserts.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> +**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.false"></a> + ## asserts.false <pre> @@ -409,46 +281,18 @@ asserts.false(<a href="#asserts.false-env">env</a>, <a href="#asserts.false-cond 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="asserts.false-env"> - <td><code>env</code></td> - <td> - required. - <p> - The test environment returned by `unittest.begin`. - </p> - </td> - </tr> - <tr id="asserts.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="asserts.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> +**PARAMETERS** + + +| 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-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> @@ -457,54 +301,18 @@ asserts.set_equals(<a href="#asserts.set_equals-env">env</a>, <a href="#asserts. 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="asserts.set_equals-env"> - <td><code>env</code></td> - <td> - required. - <p> - The test environment returned by `unittest.begin`. - </p> - </td> - </tr> - <tr id="asserts.set_equals-expected"> - <td><code>expected</code></td> - <td> - required. - <p> - The expected set resulting from some computation. - </p> - </td> - </tr> - <tr id="asserts.set_equals-actual"> - <td><code>actual</code></td> - <td> - required. - <p> - The actual set returned by some computation. - </p> - </td> - </tr> - <tr id="asserts.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> +**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.new_set_equals"></a> ## asserts.new_set_equals @@ -514,54 +322,18 @@ asserts.new_set_equals(<a href="#asserts.new_set_equals-env">env</a>, <a href="# 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="asserts.new_set_equals-env"> - <td><code>env</code></td> - <td> - required. - <p> - The test environment returned by `unittest.begin`. - </p> - </td> - </tr> - <tr id="asserts.new_set_equals-expected"> - <td><code>expected</code></td> - <td> - required. - <p> - The expected set resulting from some computation. - </p> - </td> - </tr> - <tr id="asserts.new_set_equals-actual"> - <td><code>actual</code></td> - <td> - required. - <p> - The actual set returned by some computation. - </p> - </td> - </tr> - <tr id="asserts.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> +**PARAMETERS** + + +| 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-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.true"></a> ## asserts.true @@ -571,45 +343,64 @@ asserts.true(<a href="#asserts.true-env">env</a>, <a href="#asserts.true-conditi 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="asserts.true-env"> - <td><code>env</code></td> - <td> - required. - <p> - The test environment returned by `unittest.begin`. - </p> - </td> - </tr> - <tr id="asserts.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="asserts.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> +**PARAMETERS** + + +| 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-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="#loadingtest.equals"></a> + +## loadingtest.equals + +<pre> +loadingtest.equals(<a href="#loadingtest.equals-env">env</a>, <a href="#loadingtest.equals-test_case">test_case</a>, <a href="#loadingtest.equals-expected">expected</a>, <a href="#loadingtest.equals-actual">actual</a>) +</pre> + +Creates a test case for asserting state at LOADING phase. + +**PARAMETERS** + + +| Name | Description | Default Value | +| :------------- | :------------- | :------------- | +| <a id="loadingtest.equals-env"></a>env | Loading test env created from loadingtest.make | none | +| <a id="loadingtest.equals-test_case"></a>test_case | Name of the test case | none | +| <a id="loadingtest.equals-expected"></a>expected | Expected value to test | none | +| <a id="loadingtest.equals-actual"></a>actual | Actual value received. | none | + +**RETURNS** + +None, creates test case + +<a id="#register_unittest_toolchains"></a> ## register_unittest_toolchains @@ -621,6 +412,8 @@ Registers the toolchains for unittest users. +<a id="#unittest.make"></a> + ## unittest.make <pre> @@ -653,36 +446,21 @@ 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="unittest.make-impl"> - <td><code>impl</code></td> - <td> - required. - <p> - The implementation function of the unit test. - </p> - </td> - </tr> - <tr id="unittest.make-attrs"> - <td><code>attrs</code></td> - <td> - optional. default is <code>{}</code> - <p> - An optional dictionary to supplement the attrs passed to the - unit test's `rule()` constructor. - </p> - </td> - </tr> - </tbody> -</table> +**PARAMETERS** + + +| 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> | + +**RETURNS** +A rule definition that should be stored in a global whose name ends in +`_test`. + + +<a id="#unittest.suite"></a> ## unittest.suite @@ -699,10 +477,10 @@ 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: +You can use this function to create the targets and wrap them in a single +test_suite target. If a test rule requires no arguments, you can simply list +it as an argument. If you wish to supply attributes explicitly, you can do so +using `partial.make()`. For instance, in your `.bzl` file, you could write: ``` def your_test_suite(): @@ -710,7 +488,7 @@ def your_test_suite(): "your_test_suite", your_test, your_other_test, - yet_another_test, + partial.make(yet_another_test, timeout = "short"), ) ``` @@ -729,36 +507,16 @@ 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="unittest.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="unittest.suite-test_rules"> - <td><code>test_rules</code></td> - <td> - optional. - <p> - A list of test rules defines by `unittest.test`. - </p> - </td> - </tr> - </tbody> -</table> +**PARAMETERS** + +| 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 @@ -774,27 +532,21 @@ 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="unittest.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> +**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 @@ -808,26 +560,19 @@ This must be called and returned at the end of a unit test implementation functi that the results are reported. -### Parameters +**PARAMETERS** -<table class="params-table"> - <colgroup> - <col class="col-param" /> - <col class="col-description" /> - </colgroup> - <tbody> - <tr id="unittest.end-env"> - <td><code>env</code></td> - <td> - required. - <p> - The test environment returned by `unittest.begin`. - </p> - </td> - </tr> - </tbody> -</table> +| 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 @@ -837,33 +582,12 @@ unittest.fail(<a href="#unittest.fail-env">env</a>, <a href="#unittest.fail-msg" 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="unittest.fail-env"> - <td><code>env</code></td> - <td> - required. - <p> - The test environment returned by `unittest.begin`. - </p> - </td> - </tr> - <tr id="unittest.fail-msg"> - <td><code>msg</code></td> - <td> - required. - <p> - The message to log describing the failure. - </p> - </td> - </tr> - </tbody> -</table> +**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 | diff --git a/docs/versions_doc.md b/docs/versions_doc.md index d94076c..83ee7a7 100755 --- a/docs/versions_doc.md +++ b/docs/versions_doc.md @@ -1,3 +1,9 @@ +<!-- Generated with Stardoc: http://skydoc.bazel.build --> + +Skylib module containing functions for checking Bazel versions. + +<a id="#versions.get"></a> + ## versions.get <pre> @@ -8,6 +14,8 @@ Returns the current Bazel version +<a id="#versions.parse"></a> + ## versions.parse <pre> @@ -19,26 +27,19 @@ Parses a version string into a 3-tuple of ints int tuples can be compared directly using binary operators (<, >). -### Parameters +**PARAMETERS** + -<table class="params-table"> - <colgroup> - <col class="col-param" /> - <col class="col-description" /> - </colgroup> - <tbody> - <tr id="versions.parse-bazel_version"> - <td><code>bazel_version</code></td> - <td> - required. - <p> - the Bazel version string - </p> - </td> - </tr> - </tbody> -</table> +| 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 @@ -48,45 +49,18 @@ versions.check(<a href="#versions.check-minimum_bazel_version">minimum_bazel_ver 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="versions.check-minimum_bazel_version"> - <td><code>minimum_bazel_version</code></td> - <td> - required. - <p> - minimum version of Bazel expected - </p> - </td> - </tr> - <tr id="versions.check-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="versions.check-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> +**PARAMETERS** + + +| 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.is_at_most"></a> + ## versions.is_at_most <pre> @@ -95,36 +69,21 @@ versions.is_at_most(<a href="#versions.is_at_most-threshold">threshold</a>, <a h 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="versions.is_at_most-threshold"> - <td><code>threshold</code></td> - <td> - required. - <p> - the maximum version string - </p> - </td> - </tr> - <tr id="versions.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> +**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.is_at_least"></a> + ## versions.is_at_least <pre> @@ -133,33 +92,16 @@ versions.is_at_least(<a href="#versions.is_at_least-threshold">threshold</a>, <a 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="versions.is_at_least-threshold"> - <td><code>threshold</code></td> - <td> - required. - <p> - the minimum version string - </p> - </td> - </tr> - <tr id="versions.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> +**PARAMETERS** + + +| Name | Description | Default Value | +| :------------- | :------------- | :------------- | +| <a id="versions.is_at_least-threshold"></a>threshold | the minimum version string | none | +| <a id="versions.is_at_least-version"></a>version | the version string to be compared to the threshold | none | + +**RETURNS** + +True if version >= threshold. diff --git a/docs/write_file_doc.md b/docs/write_file_doc.md index d8f098e..8f39376 100755 --- a/docs/write_file_doc.md +++ b/docs/write_file_doc.md @@ -1,3 +1,17 @@ +<!-- Generated with Stardoc: http://skydoc.bazel.build --> + +A rule that writes a UTF-8 encoded text file from user-specified contents. + +native.genrule() is sometimes used to create a text file. The 'write_file' and +macro does this with a simpler interface than genrule. + +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 <pre> @@ -6,74 +20,16 @@ write_file(<a href="#write_file-name">name</a>, <a href="#write_file-out">out</a Creates a UTF-8 encoded text file. -### Parameters +**PARAMETERS** + -<table class="params-table"> - <colgroup> - <col class="col-param" /> - <col class="col-description" /> - </colgroup> - <tbody> - <tr id="write_file-name"> - <td><code>name</code></td> - <td> - required. - <p> - Name of the rule. - </p> - </td> - </tr> - <tr id="write_file-out"> - <td><code>out</code></td> - <td> - required. - <p> - Path of the output file, relative to this package. - </p> - </td> - </tr> - <tr id="write_file-content"> - <td><code>content</code></td> - <td> - optional. default is <code>[]</code> - <p> - A list of strings. Lines of text, the contents of the file. - Newlines are added automatically after every line except the last one. - </p> - </td> - </tr> - <tr id="write_file-is_executable"> - <td><code>is_executable</code></td> - <td> - optional. default is <code>False</code> - <p> - 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. - </p> - </td> - </tr> - <tr id="write_file-newline"> - <td><code>newline</code></td> - <td> - optional. default is <code>"auto"</code> - <p> - one of ["auto", "unix", "windows"]: line endings to use. "auto" - for platform-determined, "unix" for LF, and "windows" for CRLF. - </p> - </td> - </tr> - <tr id="write_file-kwargs"> - <td><code>kwargs</code></td> - <td> - optional. - <p> - further keyword arguments, e.g. <code>visibility</code> - </p> - </td> - </tr> - </tbody> -</table> +| Name | Description | Default Value | +| :------------- | :------------- | :------------- | +| <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 | diff --git a/gazelle/bzl/BUILD b/gazelle/bzl/BUILD index fea1d51..29caeb0 100644 --- a/gazelle/bzl/BUILD +++ b/gazelle/bzl/BUILD @@ -49,5 +49,5 @@ gazelle_binary( gazelle( name = "gazelle", - gazelle = "//gazelle:gazelle-skylib", + gazelle = ":gazelle-skylib", ) diff --git a/gazelle/bzl/gazelle.go b/gazelle/bzl/gazelle.go index f948390..dccec27 100644 --- a/gazelle/bzl/gazelle.go +++ b/gazelle/bzl/gazelle.go @@ -152,24 +152,46 @@ func (*bzlLibraryLang) Resolve(c *config.Config, ix *resolve.RuleIndex, rc *repo deps := make([]string, 0, len(imports)) for _, imp := range imports { - if strings.HasPrefix(imp, "@") || !c.IndexLibraries { + impLabel, err := label.Parse(imp) + if err != nil { + log.Printf("%s: import of %q is invalid: %v", from.String(), imp, err) + continue + } + + // the index only contains absolute labels, not relative + impLabel = impLabel.Abs(from.Repo, from.Pkg) + + if impLabel.Repo == "bazel_tools" { + // The @bazel_tools repo is tricky because it is a part of the "shipped + // with bazel" core library for interacting with the outside world. + // This means that it can not depend on skylib. Fortunately there is a + // fairly simple workaround for this, which is that you can add those + // bzl files as `deps` entries. + deps = append(deps, imp) + continue + } + + if impLabel.Repo != "" || !c.IndexLibraries { // This is a dependency that is external to the current repo, or indexing // is disabled so take a guess at what hte target name should be. deps = append(deps, strings.TrimSuffix(imp, fileType)) - } else { - res := resolve.ImportSpec{ - Lang: languageName, - Imp: imp, - } - matches := ix.FindRulesByImport(res, languageName) + continue + } - if len(matches) == 0 { - log.Printf("%s: %q was not found in dependency index. Skipping. This may result in an incomplete deps section and require manual BUILD file intervention.\n", from.String(), imp) - } + res := resolve.ImportSpec{ + Lang: languageName, + Imp: impLabel.String(), + } + matches := ix.FindRulesByImport(res, languageName) - for _, m := range matches { - deps = append(deps, m.Label.String()) - } + if len(matches) == 0 { + log.Printf("%s: %q (%s) was not found in dependency index. Skipping. This may result in an incomplete deps section and require manual BUILD file intervention.\n", from.String(), imp, impLabel.String()) + } + + for _, m := range matches { + depLabel := m.Label + depLabel = depLabel.Rel(from.Repo, from.Pkg) + deps = append(deps, depLabel.String()) } } @@ -211,11 +233,10 @@ func (*bzlLibraryLang) GenerateRules(args language.GenerateArgs) language.Genera r.SetAttr("srcs", []string{f}) - if args.File == nil || !args.File.HasDefaultVisibility() { - inPrivateDir := pathtools.Index(args.Rel, "private") >= 0 - if !inPrivateDir { - r.SetAttr("visibility", []string{"//visibility:public"}) - } + shouldSetVisibility := args.File == nil || !args.File.HasDefaultVisibility() + if shouldSetVisibility { + vis := checkInternalVisibility(args.Rel, "//visibility:public") + r.SetAttr("visibility", []string{vis}) } fullPath := filepath.Join(args.Dir, f) @@ -313,3 +334,16 @@ func (s srcsList) Contains(m string) bool { } return false } + +// checkInternalVisibility overrides the given visibility if the package is +// internal. +func checkInternalVisibility(rel, visibility string) string { + if i := pathtools.Index(rel, "internal"); i > 0 { + visibility = fmt.Sprintf("//%s:__subpackages__", rel[:i-1]) + } else if i := pathtools.Index(rel, "private"); i > 0 { + visibility = fmt.Sprintf("//%s:__subpackages__", rel[:i-1]) + } else if pathtools.HasPrefix(rel, "internal") || pathtools.HasPrefix(rel, "private") { + visibility = "//:__subpackages__" + } + return visibility +} diff --git a/gazelle/bzl/testdata/bazel_tools/BUILD.in b/gazelle/bzl/testdata/bazel_tools/BUILD.in new file mode 100644 index 0000000..e267b5a --- /dev/null +++ b/gazelle/bzl/testdata/bazel_tools/BUILD.in @@ -0,0 +1,6 @@ +# Some comment to be preserved + +filegroup( + name = "allfiles", + srcs = glob(["**"]), +) diff --git a/gazelle/bzl/testdata/bazel_tools/BUILD.out b/gazelle/bzl/testdata/bazel_tools/BUILD.out new file mode 100644 index 0000000..576cfad --- /dev/null +++ b/gazelle/bzl/testdata/bazel_tools/BUILD.out @@ -0,0 +1,15 @@ +load("@bazel_skylib//:bzl_library.bzl", "bzl_library") + +# Some comment to be preserved + +filegroup( + name = "allfiles", + srcs = glob(["**"]), +) + +bzl_library( + name = "foo", + srcs = ["foo.bzl"], + visibility = ["//visibility:public"], + deps = ["@bazel_tools//tools/build_defs/repo:http.bzl"], +) diff --git a/gazelle/bzl/testdata/bazel_tools/WORKSPACE b/gazelle/bzl/testdata/bazel_tools/WORKSPACE new file mode 100644 index 0000000..e69de29 --- /dev/null +++ b/gazelle/bzl/testdata/bazel_tools/WORKSPACE diff --git a/gazelle/bzl/testdata/bazel_tools/foo.bzl b/gazelle/bzl/testdata/bazel_tools/foo.bzl new file mode 100644 index 0000000..b025d21 --- /dev/null +++ b/gazelle/bzl/testdata/bazel_tools/foo.bzl @@ -0,0 +1,10 @@ +""" +Doc string +""" + +load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive") + +def wrapped_http_archive(**kwargs): + http_archive( + **kwargs + ) diff --git a/gazelle/bzl/testdata/import/BUILD.out b/gazelle/bzl/testdata/import/BUILD.out index a19a11a..2d39feb 100644 --- a/gazelle/bzl/testdata/import/BUILD.out +++ b/gazelle/bzl/testdata/import/BUILD.out @@ -10,5 +10,5 @@ bzl_library( name = "foo", srcs = ["foo.bzl"], visibility = ["//visibility:public"], - deps = ["//:bar"], + deps = [":bar"], ) diff --git a/gazelle/bzl/testdata/private/nested/private/BUILD.out b/gazelle/bzl/testdata/private/nested/private/BUILD.out new file mode 100644 index 0000000..442401c --- /dev/null +++ b/gazelle/bzl/testdata/private/nested/private/BUILD.out @@ -0,0 +1,7 @@ +load("@bazel_skylib//:bzl_library.bzl", "bzl_library") + +bzl_library( + name = "bar", + srcs = ["bar.bzl"], + visibility = ["//nested:__subpackages__"], +) diff --git a/gazelle/bzl/testdata/private/nested/private/bar.bzl b/gazelle/bzl/testdata/private/nested/private/bar.bzl new file mode 100644 index 0000000..c8a4871 --- /dev/null +++ b/gazelle/bzl/testdata/private/nested/private/bar.bzl @@ -0,0 +1,6 @@ +""" +Test sample code. +""" + +def func(): + pass diff --git a/gazelle/bzl/testdata/private/nested/private/inside/internal/BUILD.out b/gazelle/bzl/testdata/private/nested/private/inside/internal/BUILD.out new file mode 100644 index 0000000..afaf8f3 --- /dev/null +++ b/gazelle/bzl/testdata/private/nested/private/inside/internal/BUILD.out @@ -0,0 +1,7 @@ +load("@bazel_skylib//:bzl_library.bzl", "bzl_library") + +bzl_library( + name = "bar", + srcs = ["bar.bzl"], + visibility = ["//nested/private/inside:__subpackages__"], +) diff --git a/gazelle/bzl/testdata/private/nested/private/inside/internal/bar.bzl b/gazelle/bzl/testdata/private/nested/private/inside/internal/bar.bzl new file mode 100644 index 0000000..c8a4871 --- /dev/null +++ b/gazelle/bzl/testdata/private/nested/private/inside/internal/bar.bzl @@ -0,0 +1,6 @@ +""" +Test sample code. +""" + +def func(): + pass diff --git a/gazelle/bzl/testdata/private/private/BUILD.out b/gazelle/bzl/testdata/private/private/BUILD.out index eb2e935..f442a99 100644 --- a/gazelle/bzl/testdata/private/private/BUILD.out +++ b/gazelle/bzl/testdata/private/private/BUILD.out @@ -3,4 +3,5 @@ load("@bazel_skylib//:bzl_library.bzl", "bzl_library") bzl_library( name = "bar", srcs = ["bar.bzl"], + visibility = ["//:__subpackages__"], ) diff --git a/gazelle/bzl/testdata/relative_import/BUILD.in b/gazelle/bzl/testdata/relative_import/BUILD.in new file mode 100644 index 0000000..e69de29 --- /dev/null +++ b/gazelle/bzl/testdata/relative_import/BUILD.in diff --git a/gazelle/bzl/testdata/relative_import/BUILD.out b/gazelle/bzl/testdata/relative_import/BUILD.out new file mode 100644 index 0000000..2d39feb --- /dev/null +++ b/gazelle/bzl/testdata/relative_import/BUILD.out @@ -0,0 +1,14 @@ +load("@bazel_skylib//:bzl_library.bzl", "bzl_library") + +bzl_library( + name = "bar", + srcs = ["bar.bzl"], + visibility = ["//visibility:public"], +) + +bzl_library( + name = "foo", + srcs = ["foo.bzl"], + visibility = ["//visibility:public"], + deps = [":bar"], +) diff --git a/gazelle/bzl/testdata/relative_import/WORKSPACE b/gazelle/bzl/testdata/relative_import/WORKSPACE new file mode 100644 index 0000000..e69de29 --- /dev/null +++ b/gazelle/bzl/testdata/relative_import/WORKSPACE diff --git a/gazelle/bzl/testdata/relative_import/bar.bzl b/gazelle/bzl/testdata/relative_import/bar.bzl new file mode 100644 index 0000000..7ffea51 --- /dev/null +++ b/gazelle/bzl/testdata/relative_import/bar.bzl @@ -0,0 +1,6 @@ +""" +Doc string +""" + +def func(): + pass diff --git a/gazelle/bzl/testdata/relative_import/foo.bzl b/gazelle/bzl/testdata/relative_import/foo.bzl new file mode 100644 index 0000000..829cce3 --- /dev/null +++ b/gazelle/bzl/testdata/relative_import/foo.bzl @@ -0,0 +1,7 @@ +""" +Doc string +""" + +load(":bar.bzl", "func") + +func() diff --git a/gazelle/bzl/testdata/relative_import/nested/dir/BUILD.in b/gazelle/bzl/testdata/relative_import/nested/dir/BUILD.in new file mode 100644 index 0000000..e69de29 --- /dev/null +++ b/gazelle/bzl/testdata/relative_import/nested/dir/BUILD.in diff --git a/gazelle/bzl/testdata/relative_import/nested/dir/BUILD.out b/gazelle/bzl/testdata/relative_import/nested/dir/BUILD.out new file mode 100644 index 0000000..2d39feb --- /dev/null +++ b/gazelle/bzl/testdata/relative_import/nested/dir/BUILD.out @@ -0,0 +1,14 @@ +load("@bazel_skylib//:bzl_library.bzl", "bzl_library") + +bzl_library( + name = "bar", + srcs = ["bar.bzl"], + visibility = ["//visibility:public"], +) + +bzl_library( + name = "foo", + srcs = ["foo.bzl"], + visibility = ["//visibility:public"], + deps = [":bar"], +) diff --git a/gazelle/bzl/testdata/relative_import/nested/dir/bar.bzl b/gazelle/bzl/testdata/relative_import/nested/dir/bar.bzl new file mode 100644 index 0000000..7ffea51 --- /dev/null +++ b/gazelle/bzl/testdata/relative_import/nested/dir/bar.bzl @@ -0,0 +1,6 @@ +""" +Doc string +""" + +def func(): + pass diff --git a/gazelle/bzl/testdata/relative_import/nested/dir/foo.bzl b/gazelle/bzl/testdata/relative_import/nested/dir/foo.bzl new file mode 100644 index 0000000..829cce3 --- /dev/null +++ b/gazelle/bzl/testdata/relative_import/nested/dir/foo.bzl @@ -0,0 +1,7 @@ +""" +Doc string +""" + +load(":bar.bzl", "func") + +func() diff --git a/gazelle/bzl/testdata/workspace_name/BUILD.in b/gazelle/bzl/testdata/workspace_name/BUILD.in new file mode 100644 index 0000000..e69de29 --- /dev/null +++ b/gazelle/bzl/testdata/workspace_name/BUILD.in diff --git a/gazelle/bzl/testdata/workspace_name/BUILD.out b/gazelle/bzl/testdata/workspace_name/BUILD.out new file mode 100644 index 0000000..2d39feb --- /dev/null +++ b/gazelle/bzl/testdata/workspace_name/BUILD.out @@ -0,0 +1,14 @@ +load("@bazel_skylib//:bzl_library.bzl", "bzl_library") + +bzl_library( + name = "bar", + srcs = ["bar.bzl"], + visibility = ["//visibility:public"], +) + +bzl_library( + name = "foo", + srcs = ["foo.bzl"], + visibility = ["//visibility:public"], + deps = [":bar"], +) diff --git a/gazelle/bzl/testdata/workspace_name/WORKSPACE b/gazelle/bzl/testdata/workspace_name/WORKSPACE new file mode 100644 index 0000000..2fa2441 --- /dev/null +++ b/gazelle/bzl/testdata/workspace_name/WORKSPACE @@ -0,0 +1 @@ +workspace(name = "com_example") diff --git a/gazelle/bzl/testdata/workspace_name/bar.bzl b/gazelle/bzl/testdata/workspace_name/bar.bzl new file mode 100644 index 0000000..7ffea51 --- /dev/null +++ b/gazelle/bzl/testdata/workspace_name/bar.bzl @@ -0,0 +1,6 @@ +""" +Doc string +""" + +def func(): + pass diff --git a/gazelle/bzl/testdata/workspace_name/foo.bzl b/gazelle/bzl/testdata/workspace_name/foo.bzl new file mode 100644 index 0000000..eb8d33c --- /dev/null +++ b/gazelle/bzl/testdata/workspace_name/foo.bzl @@ -0,0 +1,7 @@ +""" +Doc string +""" + +load("//:bar.bzl", "func") + +func() diff --git a/internal_deps.bzl b/internal_deps.bzl deleted file mode 100644 index c7dacd8..0000000 --- a/internal_deps.bzl +++ /dev/null @@ -1,27 +0,0 @@ -# Copyright 2019 The Bazel Authors. All rights reserved. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -"""Dependencies that are needed for running skylib tests.""" - -load( - "@bazel_federation//:repositories.bzl", - "bazel", - "bazel_stardoc", - "rules_pkg", -) - -def bazel_skylib_internal_deps(): - bazel() - bazel_stardoc() - rules_pkg() diff --git a/internal_setup.bzl b/internal_setup.bzl deleted file mode 100644 index e3189ed..0000000 --- a/internal_setup.bzl +++ /dev/null @@ -1,18 +0,0 @@ -# Copyright 2019 The Bazel Authors. All rights reserved. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -"""Setup function that must be invoked before running skylib tests.""" - -def bazel_skylib_internal_setup(): - pass # placeholder function for the federation @@ -71,6 +71,7 @@ bzl_library( srcs = ["unittest.bzl"], deps = [ ":new_sets", + ":partial", ":sets", ":types", ], diff --git a/lib/partial.bzl b/lib/partial.bzl index e2f24b7..a642d96 100644 --- a/lib/partial.bzl +++ b/lib/partial.bzl @@ -19,6 +19,11 @@ Partial function objects allow some parameters are bound before the call. Similar to https://docs.python.org/3/library/functools.html#functools.partial. """ +# create instance singletons to avoid unnecessary allocations +_a_dict_type = type({}) +_a_tuple_type = type(()) +_a_struct_type = type(struct()) + def _call(partial, *args, **kwargs): """Calls a partial created using `make`. @@ -46,16 +51,22 @@ def _make(func, *args, **kwargs): 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 @@ -63,24 +74,30 @@ def _make(func, *args, **kwargs): 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 + "!") + 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 @@ -90,16 +107,20 @@ def _make(func, *args, **kwargs): 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!". @@ -107,11 +128,13 @@ def _make(func, *args, **kwargs): 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) + ``` Args: func: The function to be called. @@ -124,7 +147,30 @@ def _make(func, *args, **kwargs): """ return struct(function = func, args = args, kwargs = kwargs) +def _is_instance(v): + """Returns True if v is a partial created using `make`. + + Args: + v: The value to check. + + Returns: + True if v was created by `make`, False otherwise. + """ + + # Note that in bazel 3.7.0 and earlier, type(v.function) is the same + # as the type of a function even if v.function is a rule. But we + # cannot rely on this in later bazels due to breaking change + # https://github.com/bazelbuild/bazel/commit/e379ece1908aafc852f9227175dd3283312b4b82 + # + # Since this check is heuristic anyway, we simply check for the + # presence of a "function" attribute without checking its type. + return type(v) == _a_struct_type and \ + hasattr(v, "function") and \ + hasattr(v, "args") and type(v.args) == _a_tuple_type and \ + hasattr(v, "kwargs") and type(v.kwargs) == _a_dict_type + partial = struct( make = _make, call = _call, + is_instance = _is_instance, ) diff --git a/lib/structs.bzl b/lib/structs.bzl index f291152..78066ad 100644 --- a/lib/structs.bzl +++ b/lib/structs.bzl @@ -25,10 +25,14 @@ def _to_dict(s): transformation is only applied to the struct's fields and not to any nested values. """ - attributes = dir(s) - attributes.remove("to_json") - attributes.remove("to_proto") - return {key: getattr(s, key) for key in attributes} + + # to_json()/to_proto() are disabled by --incompatible_struct_has_no_methods + # and will be removed entirely in a future Bazel release. + return { + key: getattr(s, key) + for key in dir(s) + if key != "to_json" and key != "to_proto" + } structs = struct( to_dict = _to_dict, diff --git a/lib/unittest.bzl b/lib/unittest.bzl index 0cdbd94..3757b08 100644 --- a/lib/unittest.bzl +++ b/lib/unittest.bzl @@ -20,6 +20,7 @@ assertions used to within tests. """ load(":new_sets.bzl", new_sets = "sets") +load(":partial.bzl", "partial") load(":types.bzl", "types") # The following function should only be called from WORKSPACE files and workspace macros. @@ -35,7 +36,14 @@ TOOLCHAIN_TYPE = "@bazel_skylib//toolchains/unittest:toolchain_type" _UnittestToolchainInfo = provider( doc = "Execution platform information for rules in the bazel_skylib repository.", - fields = ["file_ext", "success_templ", "failure_templ", "join_on"], + fields = [ + "file_ext", + "success_templ", + "failure_templ", + "join_on", + "escape_chars_with", + "escape_other_chars_with", + ], ) def _unittest_toolchain_impl(ctx): @@ -46,6 +54,8 @@ def _unittest_toolchain_impl(ctx): success_templ = ctx.attr.success_templ, failure_templ = ctx.attr.failure_templ, join_on = ctx.attr.join_on, + escape_chars_with = ctx.attr.escape_chars_with, + escape_other_chars_with = ctx.attr.escape_other_chars_with, ), ), ] @@ -53,10 +63,59 @@ def _unittest_toolchain_impl(ctx): unittest_toolchain = rule( implementation = _unittest_toolchain_impl, attrs = { - "failure_templ": attr.string(mandatory = True), - "file_ext": attr.string(mandatory = True), - "join_on": attr.string(mandatory = True), - "success_templ": attr.string(mandatory = True), + "failure_templ": attr.string( + mandatory = True, + doc = ( + "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." + ), + ), + "file_ext": attr.string( + mandatory = True, + doc = ( + "File extension for test script, including leading dot." + ), + ), + "join_on": attr.string( + mandatory = True, + doc = ( + "String used to join the lines in the failure " + + "message before including the resulting string " + + "in the script specified in `failure_templ`." + ), + ), + "success_templ": attr.string( + mandatory = True, + doc = ( + "Test script generated when the test passes. " + + "Should exit with status 0." + ), + ), + "escape_chars_with": attr.string_dict( + doc = ( + "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`." + ), + ), + "escape_other_chars_with": attr.string( + default = "", + doc = ( + "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 `\\`." + ), + ), }, ) @@ -126,7 +185,10 @@ def _make(impl, attrs = {}): toolchains = [TOOLCHAIN_TYPE], ) -_ActionInfo = provider(fields = ["actions", "bin_path"]) +_ActionInfo = provider( + doc = "Information relating to the target under test.", + fields = ["actions", "bin_path"], +) def _action_retrieving_aspect_impl(target, ctx): return [ @@ -147,7 +209,9 @@ def _make_analysis_test( expect_failure = False, attrs = {}, fragments = [], - config_settings = {}): + config_settings = {}, + extra_target_under_test_aspects = [], + doc = ""): """Creates an analysis test rule from its implementation function. An analysis test verifies the behavior of a "real" rule target by examining @@ -185,6 +249,9 @@ def _make_analysis_test( 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 + 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. + doc: A description of the rule that can be extracted by documentation generating tools. Returns: A rule definition that should be stored in a global whose name ends in @@ -205,13 +272,14 @@ def _make_analysis_test( target_attr_kwargs["cfg"] = test_transition attrs["target_under_test"] = attr.label( - aspects = [_action_retrieving_aspect], + aspects = [_action_retrieving_aspect] + extra_target_under_test_aspects, mandatory = True, **target_attr_kwargs ) return rule( impl, + doc = doc, attrs = attrs, fragments = fragments, test = True, @@ -229,10 +297,10 @@ def _suite(name, *test_rules): 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: + You can use this function to create the targets and wrap them in a single + test_suite target. If a test rule requires no arguments, you can simply list + it as an argument. If you wish to supply attributes explicitly, you can do so + using `partial.make()`. For instance, in your `.bzl` file, you could write: ``` def your_test_suite(): @@ -240,7 +308,7 @@ def _suite(name, *test_rules): "your_test_suite", your_test, your_other_test, - yet_another_test, + partial.make(yet_another_test, timeout = "short"), ) ``` @@ -266,7 +334,10 @@ def _suite(name, *test_rules): test_names = [] for index, test_rule in enumerate(test_rules): test_name = "%s_test_%d" % (name, index) - test_rule(name = test_name) + if partial.is_instance(test_rule): + partial.call(test_rule, name = test_name) + else: + test_rule(name = test_name) test_names.append(test_name) native.test_suite( @@ -326,7 +397,15 @@ def _end(env): tc = env.ctx.toolchains[TOOLCHAIN_TYPE].unittest_toolchain_info testbin = env.ctx.actions.declare_file(env.ctx.label.name + tc.file_ext) if env.failures: - cmd = tc.failure_templ % tc.join_on.join(env.failures) + failure_message_lines = "\n".join(env.failures).split("\n") + escaped_failure_message_lines = [ + "".join([ + tc.escape_chars_with.get(c, tc.escape_other_chars_with) + c + for c in line.elems() + ]) + for line in failure_message_lines + ] + cmd = tc.failure_templ % tc.join_on.join(escaped_failure_message_lines) else: cmd = tc.success_templ @@ -488,6 +567,67 @@ def _target_under_test(env): fail("test rule does not have a target_under_test") return result +def _loading_test_impl(ctx): + tc = ctx.toolchains[TOOLCHAIN_TYPE].unittest_toolchain_info + content = tc.success_templ + if ctx.attr.failure_message: + content = tc.failure_templ % ctx.attr.failure_message + + testbin = ctx.actions.declare_file("loading_test_" + ctx.label.name + tc.file_ext) + ctx.actions.write( + output = testbin, + content = content, + is_executable = True, + ) + return [DefaultInfo(executable = testbin)] + +_loading_test = rule( + implementation = _loading_test_impl, + attrs = { + "failure_message": attr.string(), + }, + toolchains = [TOOLCHAIN_TYPE], + test = True, +) + +def _loading_make(name): + """Creates a loading phase test environment and test_suite. + + Args: + name: name of the suite of tests to create + + Returns: + loading phase environment passed to other loadingtest functions + """ + native.test_suite( + name = name + "_tests", + tags = [name + "_test_case"], + ) + return struct(name = name) + +def _loading_assert_equals(env, test_case, expected, actual): + """Creates a test case for asserting state at LOADING phase. + + Args: + env: Loading test env created from loadingtest.make + test_case: Name of the test case + expected: Expected value to test + actual: Actual value received. + + Returns: + None, creates test case + """ + + msg = None + if expected != actual: + msg = 'Expected "%s", but got "%s"' % (expected, actual) + + _loading_test( + name = "%s_%s" % (env.name, test_case), + failure_message = msg, + tags = [env.name + "_test_case"], + ) + asserts = struct( expect_failure = _expect_failure, equals = _assert_equals, @@ -514,3 +654,8 @@ analysistest = struct( target_bin_dir_path = _target_bin_dir_path, target_under_test = _target_under_test, ) + +loadingtest = struct( + make = _loading_make, + equals = _loading_assert_equals, +) diff --git a/rules/BUILD b/rules/BUILD index 26cda0c..f7017bb 100644 --- a/rules/BUILD +++ b/rules/BUILD @@ -49,16 +49,11 @@ bzl_library( srcs = ["common_settings.bzl"], ) -# Exported for build_test.bzl to make sure of, it is an implementation detail -# of the rule and should not be directly used by anything else. -exports_files(["empty_test.sh"]) - filegroup( name = "test_deps", testonly = True, srcs = [ "BUILD", - "empty_test.sh", ] + glob(["*.bzl"]), ) @@ -73,14 +68,6 @@ filegroup( ], ) -filegroup( - name = "bins", - srcs = glob(["*.sh"]), - visibility = [ - "//:__pkg__", - ], -) - # export bzl files for the documentation exports_files( glob(["*.bzl"]), diff --git a/rules/analysis_test.bzl b/rules/analysis_test.bzl index 46d32dd..3420d48 100644 --- a/rules/analysis_test.bzl +++ b/rules/analysis_test.bzl @@ -16,7 +16,7 @@ def _analysis_test_impl(ctx): """Implementation function for analysis_test. """ - _ignore = [ctx] + _ignore = [ctx] # @unused return [AnalysisTestResultInfo( success = True, message = "All targets succeeded analysis", diff --git a/rules/build_test.bzl b/rules/build_test.bzl index edcb50a..9ec8ab1 100644 --- a/rules/build_test.bzl +++ b/rules/build_test.bzl @@ -16,6 +16,31 @@ load("//lib:new_sets.bzl", "sets") +def _empty_test_impl(ctx): + extension = ".bat" if ctx.attr.is_windows else ".sh" + content = "exit 0" if ctx.attr.is_windows else "#!/usr/bin/env bash\nexit 0" + executable = ctx.actions.declare_file(ctx.label.name + extension) + ctx.actions.write( + output = executable, + is_executable = True, + content = content, + ) + + return [DefaultInfo( + files = depset([executable]), + executable = executable, + runfiles = ctx.runfiles(files = ctx.files.data), + )] + +_empty_test = rule( + implementation = _empty_test_impl, + attrs = { + "data": attr.label_list(allow_files = True), + "is_windows": attr.bool(mandatory = True), + }, + test = True, +) + def build_test(name, targets, **kwargs): """Test rule checking that other targets build. @@ -23,9 +48,6 @@ def build_test(name, targets, **kwargs): 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: ``` @@ -41,7 +63,7 @@ def build_test(name, targets, **kwargs): Args: name: The name of the test rule. targets: A list of targets to ensure build. - **kwargs: The <a href="https://docs.bazel.build/versions/master/be/common-definitions.html#common-attributes-tests">common attributes for tests</a>. + **kwargs: The <a href="https://docs.bazel.build/versions/main/be/common-definitions.html#common-attributes-tests">common attributes for tests</a>. """ if len(targets) == 0: fail("targets must be non-empty", "targets") @@ -75,16 +97,18 @@ def build_test(name, targets, **kwargs): outs = [full_name + ".out"], testonly = 1, visibility = ["//visibility:private"], - # TODO: Does this need something else for Windows? cmd = "touch $@", + cmd_bat = "type nul > $@", **genrule_args ) - native.sh_test( + _empty_test( name = name, - # TODO: Does this need something else for Windows? - srcs = ["@bazel_skylib//rules:empty_test.sh"], data = test_data, size = kwargs.pop("size", "small"), # Default to small for test size + is_windows = select({ + "@bazel_tools//src/conditions:host_windows": True, + "//conditions:default": False, + }), **kwargs ) diff --git a/rules/common_settings.bzl b/rules/common_settings.bzl index e80ab09..7f56a7f 100644 --- a/rules/common_settings.bzl +++ b/rules/common_settings.bzl @@ -18,7 +18,7 @@ These rules return a BuildSettingInfo with the value of the build setting. For label-typed settings, use the native label_flag and label_setting rules. More documentation on how to use build settings at -https://docs.bazel.build/versions/master/skylark/config.html#user-defined-build-settings +https://docs.bazel.build/versions/main/skylark/config.html#user-defined-build-settings """ BuildSettingInfo = provider( diff --git a/rules/diff_test.bzl b/rules/diff_test.bzl index 93cf363..49a1968 100644 --- a/rules/diff_test.bzl +++ b/rules/diff_test.bzl @@ -44,21 +44,31 @@ for /F "tokens=2* usebackq" %%i in (`findstr.exe /l /c:"!F1! " "%MF%"`) do ( set RF1=!RF1:/=\\! ) if "!RF1!" equ "" ( - echo>&2 ERROR: !F1! not found - exit /b 1 + if exist "{file1}" ( + set RF1="{file1}" + set RF1=!RF1:/=\\! + ) else ( + echo>&2 ERROR: !F1! not found + exit /b 1 + ) ) for /F "tokens=2* usebackq" %%i in (`findstr.exe /l /c:"!F2! " "%MF%"`) do ( set RF2=%%i set RF2=!RF2:/=\\! ) if "!RF2!" equ "" ( - echo>&2 ERROR: !F2! not found - exit /b 1 + if exist "{file2}" ( + set RF2="{file2}" + set RF2=!RF2:/=\\! + ) else ( + echo>&2 ERROR: !F2! not found + exit /b 1 + ) ) fc.exe 2>NUL 1>NUL /B "!RF1!" "!RF2!" if %ERRORLEVEL% neq 0 ( if %ERRORLEVEL% equ 1 ( - echo>&2 FAIL: files "{file1}" and "{file2}" differ + echo>&2 FAIL: files "{file1}" and "{file2}" differ. {fail_msg} exit /b 1 ) else ( fc.exe /B "!RF1!" "!RF2!" @@ -66,6 +76,7 @@ if %ERRORLEVEL% neq 0 ( ) ) """.format( + fail_msg = ctx.attr.failure_message, file1 = _runfiles_path(ctx.file.file1), file2 = _runfiles_path(ctx.file.file2), ), @@ -75,7 +86,7 @@ if %ERRORLEVEL% neq 0 ( test_bin = ctx.actions.declare_file(ctx.label.name + "-test.sh") ctx.actions.write( output = test_bin, - content = r"""#!/bin/bash + content = r"""#!/usr/bin/env bash set -euo pipefail F1="{file1}" F2="{file2}" @@ -95,10 +106,11 @@ else exit 1 fi if ! diff "$RF1" "$RF2"; then - echo >&2 "FAIL: files \"{file1}\" and \"{file2}\" differ" + echo >&2 "FAIL: files \"{file1}\" and \"{file2}\" differ. {fail_msg}" exit 1 fi """.format( + fail_msg = ctx.attr.failure_message, file1 = _runfiles_path(ctx.file.file1), file2 = _runfiles_path(ctx.file.file2), ), @@ -112,6 +124,7 @@ fi _diff_test = rule( attrs = { + "failure_message": attr.string(), "file1": attr.label( allow_single_file = True, mandatory = True, @@ -135,7 +148,7 @@ def diff_test(name, file1, file2, **kwargs): name: The name of the test rule. file1: Label of the file to compare to <code>file2</code>. file2: Label of the file to compare to <code>file1</code>. - **kwargs: The <a href="https://docs.bazel.build/versions/master/be/common-definitions.html#common-attributes-tests">common attributes for tests</a>. + **kwargs: The <a href="https://docs.bazel.build/versions/main/be/common-definitions.html#common-attributes-tests">common attributes for tests</a>. """ _diff_test( name = name, diff --git a/rules/empty_test.sh b/rules/empty_test.sh deleted file mode 100755 index fde58b3..0000000 --- a/rules/empty_test.sh +++ /dev/null @@ -1,3 +0,0 @@ -#!/bin/bash -# This is a support file for build_test.bzl, it shouldn't be used by anything else. -exit 0 diff --git a/rules/native_binary.bzl b/rules/native_binary.bzl index 7d885a0..9a1725f 100644 --- a/rules/native_binary.bzl +++ b/rules/native_binary.bzl @@ -72,11 +72,11 @@ def native_binary(name, src, out, data = None, **kwargs): 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. Args: - name: The name of the test rule. + name: The name of the rule. src: label; path of the pre-built executable out: output; an output name for the copy of the binary. (Bazel requires that this rule make a copy of 'src'.) data: list of labels; data dependencies - **kwargs: The <a href="https://docs.bazel.build/versions/master/be/common-definitions.html#common-attributes-binaries">common attributes for binaries</a>. + **kwargs: The <a href="https://docs.bazel.build/versions/main/be/common-definitions.html#common-attributes-binaries">common attributes for binaries</a>. """ _native_binary( name = name, @@ -101,7 +101,7 @@ def native_test(name, src, out, data = None, **kwargs): src: label; path of the pre-built executable out: output; an output name for the copy of the binary. (Bazel requires that this rule make a copy of 'src'.) data: list of labels; data dependencies - **kwargs: The <a href="https://docs.bazel.build/versions/master/be/common-definitions.html#common-attributes-tests">common attributes for tests</a>. + **kwargs: The <a href="https://docs.bazel.build/versions/main/be/common-definitions.html#common-attributes-tests">common attributes for tests</a>. """ _native_test( name = name, diff --git a/rules/private/copy_file_private.bzl b/rules/private/copy_file_private.bzl index 75cb027..44f133a 100644 --- a/rules/private/copy_file_private.bzl +++ b/rules/private/copy_file_private.bzl @@ -65,11 +65,10 @@ def _copy_file_impl(ctx): target_file = ctx.file.src, is_executable = ctx.attr.is_executable, ) + elif ctx.attr.is_windows: + copy_cmd(ctx, ctx.file.src, ctx.outputs.out) else: - if ctx.attr.is_windows: - copy_cmd(ctx, ctx.file.src, ctx.outputs.out) - else: - copy_bash(ctx, ctx.file.src, ctx.outputs.out) + copy_bash(ctx, ctx.file.src, ctx.outputs.out) files = depset(direct = [ctx.outputs.out]) runfiles = ctx.runfiles(files = [ctx.outputs.out]) diff --git a/rules/run_binary.bzl b/rules/run_binary.bzl index 10f1ab5..c251019 100644 --- a/rules/run_binary.bzl +++ b/rules/run_binary.bzl @@ -76,7 +76,7 @@ run_binary = rule( ), "env": attr.string_dict( doc = "Environment variables of the action.<br/><br/>Subject to " + - " <code><a href=\"https://docs.bazel.build/versions/master/be/make-variables.html#location\">$(location)</a></code>" + + " <code><a href=\"https://docs.bazel.build/versions/main/be/make-variables.html#location\">$(location)</a></code>" + " expansion.", ), "srcs": attr.label_list( @@ -91,7 +91,7 @@ run_binary = rule( ), "args": attr.string_list( doc = "Command line arguments of the binary.<br/><br/>Subject to" + - "<code><a href=\"https://docs.bazel.build/versions/master/be/make-variables.html#location\">$(location)</a></code>" + + "<code><a href=\"https://docs.bazel.build/versions/main/be/make-variables.html#location\">$(location)</a></code>" + " expansion.", ), }, diff --git a/tests/analysis_test_test.sh b/tests/analysis_test_test.sh index db9bbac..2edae15 100755 --- a/tests/analysis_test_test.sh +++ b/tests/analysis_test_test.sh @@ -1,4 +1,4 @@ -#!/bin/bash +#!/usr/bin/env bash # Copyright 2019 The Bazel Authors. All rights reserved. # diff --git a/tests/common_settings_test.sh b/tests/common_settings_test.sh index 531e830..1e3d03d 100755 --- a/tests/common_settings_test.sh +++ b/tests/common_settings_test.sh @@ -1,4 +1,4 @@ -#!/bin/bash +#!/usr/bin/env bash # Copyright 2019 The Bazel Authors. All rights reserved. # diff --git a/tests/copy_file/BUILD b/tests/copy_file/BUILD index 79ab7ba..2e6914c 100644 --- a/tests/copy_file/BUILD +++ b/tests/copy_file/BUILD @@ -80,8 +80,8 @@ genrule( output_to_bindir = 1, tools = [ ":bin_gen", - ":bin_src", ":bin_gen_symlink", + ":bin_src", ":bin_src_symlink", ], ) @@ -147,8 +147,8 @@ copy_file( name = "copy_xsrc_symlink", src = "a_with_exec_bit.txt", out = "xout/a-out-symlink.sh", - is_executable = True, allow_symlink = True, + is_executable = True, ) copy_file( @@ -162,12 +162,12 @@ copy_file( name = "copy_xgen_symlink", src = ":gen", out = "xout/gen-out-symlink.sh", - is_executable = True, allow_symlink = True, + is_executable = True, ) genrule( name = "gen", outs = ["b.txt"], - cmd = "echo -e '#!/bin/bash\necho potato' > $@", + cmd = "echo -e '#!/usr/bin/env bash\necho potato' > $@", ) diff --git a/tests/copy_file/a.txt b/tests/copy_file/a.txt index acd332a..37b2322 100644 --- a/tests/copy_file/a.txt +++ b/tests/copy_file/a.txt @@ -1,2 +1,2 @@ -#!/bin/bash +#!/usr/bin/env bash echo aaa diff --git a/tests/copy_file/a_with_exec_bit.txt b/tests/copy_file/a_with_exec_bit.txt index acd332a..37b2322 100755 --- a/tests/copy_file/a_with_exec_bit.txt +++ b/tests/copy_file/a_with_exec_bit.txt @@ -1,2 +1,2 @@ -#!/bin/bash +#!/usr/bin/env bash echo aaa diff --git a/tests/copy_file/copy_file_tests.sh b/tests/copy_file/copy_file_tests.sh index dfee635..737afd7 100755 --- a/tests/copy_file/copy_file_tests.sh +++ b/tests/copy_file/copy_file_tests.sh @@ -1,3 +1,5 @@ +#!/usr/bin/env bash + # Copyright 2019 The Bazel Authors. All rights reserved. # # Licensed under the Apache License, Version 2.0 (the "License"); @@ -40,25 +42,25 @@ source "$(rlocation bazel_skylib/tests/unittest.bash)" \ function test_copy_src() { cat "$(rlocation bazel_skylib/tests/copy_file/out/a-out.txt)" >"$TEST_log" - expect_log '^#!/bin/bash$' + expect_log '^#!/usr/bin/env bash$' expect_log '^echo aaa$' } function test_copy_src_symlink() { cat "$(rlocation bazel_skylib/tests/copy_file/out/a-out-symlink.txt)" >"$TEST_log" - expect_log '^#!/bin/bash$' + expect_log '^#!/usr/bin/env bash$' expect_log '^echo aaa$' } function test_copy_gen() { cat "$(rlocation bazel_skylib/tests/copy_file/out/gen-out.txt)" >"$TEST_log" - expect_log '^#!/bin/bash$' + expect_log '^#!/usr/bin/env bash$' expect_log '^echo potato$' } function test_copy_gen_symlink() { cat "$(rlocation bazel_skylib/tests/copy_file/out/gen-out-symlink.txt)" >"$TEST_log" - expect_log '^#!/bin/bash$' + expect_log '^#!/usr/bin/env bash$' expect_log '^echo potato$' } diff --git a/tests/diff_test/diff_test_tests.sh b/tests/diff_test/diff_test_tests.sh index ed894c2..4b58e6c 100755 --- a/tests/diff_test/diff_test_tests.sh +++ b/tests/diff_test/diff_test_tests.sh @@ -1,3 +1,5 @@ +#!/usr/bin/env bash + # Copyright 2019 The Bazel Authors. All rights reserved. # # Licensed under the Apache License, Version 2.0 (the "License"); diff --git a/tests/partial_tests.bzl b/tests/partial_tests.bzl index 6d778c3..73a579b 100644 --- a/tests/partial_tests.bzl +++ b/tests/partial_tests.bzl @@ -76,9 +76,27 @@ def _make_call_test(ctx): make_call_test = unittest.make(_make_call_test) +def _is_instance_test(ctx): + """Unit test for partial.is_instance.""" + env = unittest.begin(ctx) + + # We happen to use make_call_test here, but it could be any valid test rule. + asserts.true(env, partial.is_instance(partial.make(make_call_test))) + asserts.true(env, partial.is_instance(partial.make(make_call_test, timeout = "short"))) + asserts.true(env, partial.is_instance(partial.make(make_call_test, timeout = "short", tags = ["foo"]))) + asserts.false(env, partial.is_instance(None)) + asserts.false(env, partial.is_instance({})) + asserts.false(env, partial.is_instance(struct(foo = 1))) + asserts.false(env, partial.is_instance(struct(function = "not really function"))) + + return unittest.end(env) + +is_instance_test = unittest.make(_is_instance_test) + def partial_test_suite(): """Creates the test targets and test suite for partial.bzl tests.""" unittest.suite( "partial_tests", make_call_test, + is_instance_test, ) diff --git a/tests/run_binary/BUILD b/tests/run_binary/BUILD index f511c03..85c10f3 100644 --- a/tests/run_binary/BUILD +++ b/tests/run_binary/BUILD @@ -82,7 +82,7 @@ write_file( "@echo>>%OUT% ENV_PATH_CMD=(%ENV_PATH_CMD%)", ], "//conditions:default": [ - "#!/bin/bash", + "#!/usr/bin/env bash", "echo > \"$OUT\" \"arg1=($1)\"", "echo >> \"$OUT\" \"arg2=($2)\"", "echo >> \"$OUT\" \"ENV_LOCATION=($ENV_LOCATION)\"", diff --git a/tests/selects_tests.bzl b/tests/selects_tests.bzl index 28f3ac4..a7697f2 100644 --- a/tests/selects_tests.bzl +++ b/tests/selects_tests.bzl @@ -129,7 +129,10 @@ def _set_conditions(condition_list): ans["//command_line_option:features"] = ["notmyfeature"] return ans -_BooleanInfo = provider() +_BooleanInfo = provider( + doc = "value for boolean tests", + fields = ["value"], +) def _boolean_attr_impl(ctx): return [_BooleanInfo(value = ctx.attr.myboolean)] @@ -153,9 +156,6 @@ def _expect_doesnt_match(ctx): asserts.equals(env, False, attrval) return analysistest.end(env) -def _config_setting_group_test(name, config_settings): - return analysistest.make() - ################################################### # and_config_setting_group_matches_test ################################################### diff --git a/tests/shell_tests.bzl b/tests/shell_tests.bzl index 32d517f..5b83f9f 100644 --- a/tests/shell_tests.bzl +++ b/tests/shell_tests.bzl @@ -69,7 +69,7 @@ def _shell_args_test_gen_impl(ctx): "back`echo q`uote", ] script_content = "\n".join([ - "#!/bin/bash", + "#!/usr/bin/env bash", "myarray=" + shell.array_literal(args), 'output=$(echo "${myarray[@]}")', # For logging: diff --git a/tests/unittest.bash b/tests/unittest.bash index 3bd07c7..a43678d 100755 --- a/tests/unittest.bash +++ b/tests/unittest.bash @@ -1,4 +1,4 @@ -#!/bin/bash +#!/usr/bin/env bash # # Copyright 2015 The Bazel Authors. All rights reserved. # @@ -21,7 +21,7 @@ # A typical test suite looks like so: # # ------------------------------------------------------------------------ -# #!/bin/bash +# #!/usr/bin/env bash # # source path/to/unittest.bash || exit 1 # diff --git a/tests/unittest_test.sh b/tests/unittest_test.sh index baed490..4795b7e 100755 --- a/tests/unittest_test.sh +++ b/tests/unittest_test.sh @@ -1,4 +1,4 @@ -#!/bin/bash +#!/usr/bin/env bash # Copyright 2019 The Bazel Authors. All rights reserved. # @@ -73,6 +73,7 @@ exports_files(["*.bzl"]) EOF ln -sf "$(rlocation bazel_skylib/lib/dicts.bzl)" lib/dicts.bzl ln -sf "$(rlocation bazel_skylib/lib/new_sets.bzl)" lib/new_sets.bzl + ln -sf "$(rlocation bazel_skylib/lib/partial.bzl)" lib/partial.bzl ln -sf "$(rlocation bazel_skylib/lib/sets.bzl)" lib/sets.bzl ln -sf "$(rlocation bazel_skylib/lib/types.bzl)" lib/types.bzl ln -sf "$(rlocation bazel_skylib/lib/unittest.bzl)" lib/unittest.bzl @@ -82,10 +83,11 @@ EOF # Create test files. mkdir -p testdir - cat > testdir/BUILD <<EOF + cat > testdir/BUILD <<'EOF' load("//tests:unittest_tests.bzl", "basic_passing_test", "basic_failing_test", + "failure_message_test", "fail_unexpected_passing_test", "fail_unexpected_passing_fake_rule") @@ -93,10 +95,26 @@ basic_passing_test(name = "basic_passing_test") basic_failing_test(name = "basic_failing_test") +failure_message_test( + name = "shell_escape_failure_message_test", + message = "Contains $FOO", +) + +failure_message_test( + name = "cmd_escape_failure_message_test", + message = "Contains %FOO%", +) + +failure_message_test( + name = "eof_failure_message_test", + message = "\nEOF\n more after EOF", +) + fail_unexpected_passing_test( name = "fail_unexpected_passing_test", target_under_test = ":fail_unexpected_passing_fake_target", ) + fail_unexpected_passing_fake_rule( name = "fail_unexpected_passing_fake_target", tags = ["manual"]) @@ -122,6 +140,36 @@ function test_basic_failing_test() { expect_log "In test _basic_failing_test from //tests:unittest_tests.bzl: Expected \"1\", but got \"2\"" } +function test_shell_escape_failure_message_test() { + local -r pkg="${FUNCNAME[0]}" + create_pkg "$pkg" + + bazel test testdir:shell_escape_failure_message_test --test_output=all --verbose_failures \ + >"$TEST_log" 2>&1 && fail "Expected test to fail" || true + + expect_log 'In test _failure_message_test from //tests:unittest_tests.bzl: Expected "", but got "Contains $FOO"' +} + +function test_cmd_escape_failure_message_test() { + local -r pkg="${FUNCNAME[0]}" + create_pkg "$pkg" + + bazel test testdir:cmd_escape_failure_message_test --test_output=all --verbose_failures \ + >"$TEST_log" 2>&1 && fail "Expected test to fail" || true + + expect_log 'In test _failure_message_test from //tests:unittest_tests.bzl: Expected "", but got "Contains %FOO%"' +} + +function test_eof_failure_message_test() { + local -r pkg="${FUNCNAME[0]}" + create_pkg "$pkg" + + bazel test testdir:eof_failure_message_test --test_output=all --verbose_failures \ + >"$TEST_log" 2>&1 && fail "Expected test to fail" || true + + expect_log '^ more after EOF' +} + function test_fail_unexpected_passing_test() { local -r pkg="${FUNCNAME[0]}" create_pkg "$pkg" diff --git a/tests/unittest_tests.bzl b/tests/unittest_tests.bzl index 3d5a198..2f326a0 100644 --- a/tests/unittest_tests.bzl +++ b/tests/unittest_tests.bzl @@ -14,11 +14,13 @@ """Unit tests for unittest.bzl.""" -load("//lib:unittest.bzl", "analysistest", "asserts", "unittest") +load("//lib:partial.bzl", "partial") +load("//lib:unittest.bzl", "analysistest", "asserts", "loadingtest", "unittest") ################################### -####### fail_basic_test ########### +####### basic_failing_test ######## ################################### + def _basic_failing_test(ctx): """Unit tests for a basic library verification test that fails.""" env = unittest.begin(ctx) @@ -30,6 +32,27 @@ def _basic_failing_test(ctx): basic_failing_test = unittest.make(_basic_failing_test) ################################### +####### failure_message_test ###### +################################### + +def _failure_message_test(ctx): + """Failing unit test with arbitrary content in the message.""" + env = unittest.begin(ctx) + + if not ctx.attr.message: + unittest.fail(env, "Message must be non-empty.") + asserts.equals(env, "", ctx.attr.message) + + return unittest.end(env) + +failure_message_test = unittest.make( + _failure_message_test, + attrs = { + "message": attr.string(), + }, +) + +################################### ####### basic_passing_test ######## ################################### def _basic_passing_test(ctx): @@ -42,6 +65,19 @@ def _basic_passing_test(ctx): basic_passing_test = unittest.make(_basic_passing_test) +################################################# +####### basic_passing_short_timeout_test ######## +################################################# +def _basic_passing_short_timeout_test(ctx): + """Unit tests for a basic library verification test.""" + env = unittest.begin(ctx) + + asserts.equals(env, ctx.attr.timeout, "short") + + return unittest.end(env) + +basic_passing_short_timeout_test = unittest.make(_basic_passing_short_timeout_test) + ################################### ####### change_setting_test ####### ################################### @@ -54,7 +90,10 @@ def _change_setting_test(ctx): return analysistest.end(env) -_ChangeSettingInfo = provider() +_ChangeSettingInfo = provider( + doc = "min_os_version for change_setting_test", + fields = ["min_os_version"], +) def _change_setting_fake_rule(ctx): return [_ChangeSettingInfo(min_os_version = ctx.fragments.cpp.minimum_os_version())] @@ -83,7 +122,7 @@ def _failure_testing_test(ctx): return analysistest.end(env) def _failure_testing_fake_rule(ctx): - ignore = [ctx] + _ignore = [ctx] # @unused fail("This rule should never work") failure_testing_fake_rule = rule( @@ -107,7 +146,7 @@ def _fail_unexpected_passing_test(ctx): return analysistest.end(env) def _fail_unexpected_passing_fake_rule(ctx): - _ignore = [ctx] + _ignore = [ctx] # @unused return [] fail_unexpected_passing_fake_rule = rule( @@ -177,10 +216,58 @@ inspect_actions_test = analysistest.make( _inspect_actions_test, ) +#################################### +####### inspect_aspect_test ####### +#################################### +_AddedByAspectInfo = provider( + doc = "Example provider added by example aspect", + fields = { + "value": "(str)", + }, +) + +def _example_aspect_impl(target, ctx): + _ignore = [target, ctx] # @unused + return [ + _AddedByAspectInfo(value = "attached by aspect"), + ] + +example_aspect = aspect( + implementation = _example_aspect_impl, +) + +def _inspect_aspect_test(ctx): + """Test verifying aspect run on a target.""" + env = analysistest.begin(ctx) + + tut = env.ctx.attr.target_under_test + asserts.equals(env, "attached by aspect", tut[_AddedByAspectInfo].value) + return analysistest.end(env) + +def _inspect_aspect_fake_rule(ctx): + out_file = ctx.actions.declare_file("out.txt") + ctx.actions.run_shell( + command = "echo 'hello' > %s" % out_file.basename, + outputs = [out_file], + ) + return [DefaultInfo(files = depset([out_file]))] + +inspect_aspect_fake_rule = rule( + implementation = _inspect_aspect_fake_rule, +) + +inspect_aspect_test = analysistest.make( + _inspect_aspect_test, + extra_target_under_test_aspects = [example_aspect], +) + ######################################## ####### inspect_output_dirs_test ####### ######################################## -_OutputDirInfo = provider(fields = ["bin_path"]) +_OutputDirInfo = provider( + doc = "bin_path for inspect_output_dirs_test", + fields = ["bin_path"], +) def _inspect_output_dirs_test(ctx): """Test verifying output directories used by a test.""" @@ -221,6 +308,13 @@ inspect_output_dirs_test = analysistest.make( }, ) +def _loading_phase_test(env): + loadingtest.equals(env, "self_glob", ["unittest_tests.bzl"], native.glob(["unittest_tests.bzl"])) + + # now use our own calls to assert we created a test case rule and test_suite for it. + loadingtest.equals(env, "test_exists", True, native.existing_rule(env.name + "_self_glob") != None) + loadingtest.equals(env, "suite_exists", True, native.existing_rule(env.name + "_tests") != None) + ######################################### # buildifier: disable=unnamed-macro @@ -234,6 +328,7 @@ def unittest_passing_tests_suite(): unittest.suite( "unittest_tests", basic_passing_test, + partial.make(basic_passing_short_timeout_test, timeout = "short"), ) change_setting_test( @@ -272,6 +367,15 @@ def unittest_passing_tests_suite(): tags = ["manual"], ) + inspect_aspect_test( + name = "inspect_aspect_test", + target_under_test = ":inspect_aspect_fake_target", + ) + inspect_aspect_fake_rule( + name = "inspect_aspect_fake_target", + tags = ["manual"], + ) + inspect_output_dirs_test( name = "inspect_output_dirs_test", target_under_test = ":inspect_output_dirs_fake_target", @@ -280,3 +384,6 @@ def unittest_passing_tests_suite(): name = "inspect_output_dirs_fake_target", tags = ["manual"], ) + + loading_env = loadingtest.make("selftest") + _loading_phase_test(loading_env) diff --git a/tests/write_file/BUILD b/tests/write_file/BUILD index 9ea3609..e4f2a94 100644 --- a/tests/write_file/BUILD +++ b/tests/write_file/BUILD @@ -113,7 +113,7 @@ write_file( name = "write_nonempty_bin", out = "out/nonempty.sh", content = [ - "#!/bin/bash", + "#!/usr/bin/env bash", "echo potato", ], is_executable = True, diff --git a/tests/write_file/write_file_tests.sh b/tests/write_file/write_file_tests.sh index 2464230..e7039d0 100755 --- a/tests/write_file/write_file_tests.sh +++ b/tests/write_file/write_file_tests.sh @@ -1,3 +1,5 @@ +#!/usr/bin/env bash + # Copyright 2019 The Bazel Authors. All rights reserved. # # Licensed under the Apache License, Version 2.0 (the "License"); @@ -50,8 +52,8 @@ function test_write_empty_text() { function test_write_nonempty_text() { cat "$(rlocation bazel_skylib/tests/write_file/out/nonempty.txt)" >"$TEST_log" - expect_log '^aaa$' - expect_log '^bbb$' + expect_log '^aaa' + expect_log '^bbb' } function test_write_empty_bin() { @@ -60,7 +62,7 @@ function test_write_empty_bin() { function test_write_nonempty_bin() { cat "$(rlocation bazel_skylib/tests/write_file/nonempty-bin-out.txt)" >"$TEST_log" - expect_log '^potato$' + expect_log '^potato' } run_suite "write_file_tests test suite" diff --git a/toolchains/unittest/BUILD b/toolchains/unittest/BUILD index 03ceff4..dd23962 100644 --- a/toolchains/unittest/BUILD +++ b/toolchains/unittest/BUILD @@ -9,6 +9,7 @@ toolchain_type( unittest_toolchain( name = "cmd", + escape_chars_with = {"%": "%"}, failure_templ = """@echo off echo %s exit /b 1 @@ -30,14 +31,13 @@ toolchain( unittest_toolchain( name = "bash", + escape_other_chars_with = "\\", failure_templ = """#!/bin/sh -cat <<'EOF' -%s -EOF +echo %s exit 1 """, file_ext = ".sh", - join_on = "\n", + join_on = "\necho ", success_templ = "#!/bin/sh\nexit 0", visibility = ["//visibility:public"], ) diff --git a/version.bzl b/version.bzl index 3906779..324adb5 100644 --- a/version.bzl +++ b/version.bzl @@ -13,4 +13,4 @@ # limitations under the License. """The version of bazel-skylib.""" -version = "1.0.3" +version = "1.2.1" |