diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/BUILD | 210 | ||||
| -rwxr-xr-x | docs/analysis_test_doc.md | 6 | ||||
| -rwxr-xr-x | docs/build_test_doc.md | 4 | ||||
| -rwxr-xr-x | docs/bzl_library.md | 88 | ||||
| -rwxr-xr-x | docs/collections_doc.md | 6 | ||||
| -rwxr-xr-x | docs/common_settings_doc.md | 52 | ||||
| -rwxr-xr-x | docs/copy_directory_doc.md | 63 | ||||
| -rwxr-xr-x | docs/copy_file_doc.md | 2 | ||||
| -rwxr-xr-x | docs/dicts_doc.md | 48 | ||||
| -rwxr-xr-x | docs/diff_test_doc.md | 11 | ||||
| -rwxr-xr-x | docs/expand_template_doc.md | 32 | ||||
| -rw-r--r-- | docs/maintainers_guide.md | 121 | ||||
| -rwxr-xr-x | docs/native_binary_doc.md | 49 | ||||
| -rwxr-xr-x | docs/new_sets_doc.md | 30 | ||||
| -rwxr-xr-x | docs/partial_doc.md | 6 | ||||
| -rwxr-xr-x | docs/paths_doc.md | 16 | ||||
| -rw-r--r-- | docs/private/BUILD | 1 | ||||
| -rw-r--r-- | docs/private/stardoc_with_diff_test.bzl | 111 | ||||
| -rwxr-xr-x | docs/regenerate_docs.sh | 27 | ||||
| -rwxr-xr-x | docs/run_binary_doc.md | 18 | ||||
| -rwxr-xr-x | docs/select_file_doc.md | 28 | ||||
| -rwxr-xr-x | docs/selects_doc.md | 6 | ||||
| -rwxr-xr-x | docs/shell_doc.md | 4 | ||||
| -rwxr-xr-x | docs/structs_doc.md | 2 | ||||
| -rwxr-xr-x | docs/subpackages_doc.md | 96 | ||||
| -rwxr-xr-x | docs/types_doc.md | 20 | ||||
| -rwxr-xr-x | docs/unittest_doc.md | 74 | ||||
| -rwxr-xr-x | docs/versions_doc.md | 19 | ||||
| -rwxr-xr-x | docs/write_file_doc.md | 4 |
29 files changed, 854 insertions, 300 deletions
@@ -1,137 +1,153 @@ -load("@io_bazel_stardoc//stardoc:stardoc.bzl", "stardoc") +load("//docs/private:stardoc_with_diff_test.bzl", "stardoc_with_diff_test", "update_docs") licenses(["notice"]) -# Note that due to a bug in Bazel 0.22.0, these targets cannot be built without -# the --incompatible_remap_main_repo flag. -stardoc( - name = "build_test_docs", - out = "build_test_doc_gen.md", - input = "//rules:build_test.bzl", - deps = ["//rules:build_test"], +stardoc_with_diff_test( + name = "analysis_test", + bzl_library_target = "//rules:analysis_test", + out_label = "//docs:analysis_test_doc.md", ) -stardoc( - name = "analysis_test_docs", - out = "analysis_test_doc_gen.md", - input = "//rules:analysis_test.bzl", +stardoc_with_diff_test( + name = "build_test", + bzl_library_target = "//rules:build_test", + out_label = "//docs:build_test_doc.md", ) -stardoc( - name = "collections_docs", - out = "collections_doc_gen.md", - input = "//lib:collections.bzl", - deps = ["//lib:collections"], +stardoc_with_diff_test( + name = "bzl_library", + bzl_library_target = "//:bzl_library", + out_label = "//docs:bzl_library.md", ) -stardoc( - name = "dicts_docs", - out = "dicts_doc_gen.md", - input = "//lib:dicts.bzl", - deps = ["//lib:dicts"], +stardoc_with_diff_test( + name = "collections", + bzl_library_target = "//lib:collections", + out_label = "//docs:collections_doc.md", ) -stardoc( - name = "partial_docs", - out = "partial_doc_gen.md", - input = "//lib:partial.bzl", - deps = ["//lib:partial"], +stardoc_with_diff_test( + name = "common_settings", + bzl_library_target = "//rules:common_settings", + out_label = "//docs:common_settings_doc.md", ) -stardoc( - name = "paths_docs", - out = "paths_doc_gen.md", - input = "//lib:paths.bzl", - deps = ["//lib:paths"], +stardoc_with_diff_test( + name = "copy_directory", + bzl_library_target = "//rules:copy_directory", + out_label = "//docs:copy_directory_doc.md", ) -stardoc( - name = "selects_docs", - out = "selects_doc_gen.md", - input = "//lib:selects.bzl", - deps = ["//lib:selects"], +stardoc_with_diff_test( + name = "copy_file", + bzl_library_target = "//rules:copy_file", + out_label = "//docs:copy_file_doc.md", ) -stardoc( - name = "new_sets_docs", - out = "new_sets_doc_gen.md", - input = "//lib:new_sets.bzl", - deps = ["//lib:new_sets"], +stardoc_with_diff_test( + name = "dicts", + bzl_library_target = "//lib:dicts", + out_label = "//docs:dicts_doc.md", ) -stardoc( - name = "shell_docs", - out = "shell_doc_gen.md", - input = "//lib:shell.bzl", - deps = ["//lib:shell"], +stardoc_with_diff_test( + name = "diff_test", + bzl_library_target = "//rules:diff_test", + out_label = "//docs:diff_test_doc.md", ) -stardoc( - name = "structs_docs", - out = "structs_doc_gen.md", - input = "//lib:structs.bzl", - deps = ["//lib:structs"], +stardoc_with_diff_test( + name = "expand_template", + bzl_library_target = "//rules:expand_template", + out_label = "//docs:expand_template_doc.md", ) -stardoc( - name = "types_docs", - out = "types_doc_gen.md", - input = "//lib:types.bzl", - deps = ["//lib:types"], +stardoc_with_diff_test( + name = "native_binary", + bzl_library_target = "//rules:native_binary", + out_label = "//docs:native_binary_doc.md", ) -stardoc( - name = "unittest_docs", - out = "unittest_doc_gen.md", - input = "//lib:unittest.bzl", - deps = ["//lib:unittest"], +stardoc_with_diff_test( + name = "new_sets", + bzl_library_target = "//lib:new_sets", + out_label = "//docs:new_sets_doc.md", ) -stardoc( - name = "versions_docs", - out = "versions_doc_gen.md", - input = "//lib:versions.bzl", - deps = ["//lib:versions"], +stardoc_with_diff_test( + name = "partial", + bzl_library_target = "//lib:partial", + out_label = "//docs:partial_doc.md", ) -stardoc( - name = "copy_file_docs", - out = "copy_file_doc_gen.md", - input = "//rules:copy_file.bzl", - deps = ["//rules:copy_file"], +stardoc_with_diff_test( + name = "paths", + bzl_library_target = "//lib:paths", + out_label = "//docs:paths_doc.md", ) -stardoc( - name = "write_file_docs", - out = "write_file_doc_gen.md", - input = "//rules:write_file.bzl", - deps = ["//rules:write_file"], +stardoc_with_diff_test( + name = "run_binary", + bzl_library_target = "//rules:run_binary", + out_label = "//docs:run_binary_doc.md", ) -stardoc( - name = "diff_test_docs", - out = "diff_test_doc_gen.md", - input = "//rules:diff_test.bzl", - deps = ["//rules:diff_test"], +stardoc_with_diff_test( + name = "selects", + bzl_library_target = "//lib:selects", + out_label = "//docs:selects_doc.md", ) -stardoc( - name = "native_binary_docs", - out = "native_binary_doc_gen.md", - input = "//rules:native_binary.bzl", - deps = ["//rules:native_binary"], +stardoc_with_diff_test( + name = "select_file", + bzl_library_target = "//rules:select_file", + out_label = "//docs:select_file_doc.md", ) -stardoc( - name = "run_binary_docs", - out = "run_binary_doc_gen.md", - input = "//rules:run_binary.bzl", - deps = ["//rules:run_binary"], +stardoc_with_diff_test( + name = "shell", + bzl_library_target = "//lib:shell", + out_label = "//docs:shell_doc.md", ) -stardoc( - name = "common_settings_docs", - out = "common_settings_doc_gen.md", - input = "//rules:common_settings.bzl", - deps = ["//rules:common_settings"], +stardoc_with_diff_test( + name = "structs", + bzl_library_target = "//lib:structs", + out_label = "//docs:structs_doc.md", +) + +stardoc_with_diff_test( + name = "subpackages", + bzl_library_target = "//lib:subpackages", + out_label = "//docs:subpackages_doc.md", +) + +stardoc_with_diff_test( + name = "types", + bzl_library_target = "//lib:types", + out_label = "//docs:types_doc.md", +) + +stardoc_with_diff_test( + name = "unittest", + bzl_library_target = "//lib:unittest", + out_label = "//docs:unittest_doc.md", +) + +stardoc_with_diff_test( + name = "versions", + bzl_library_target = "//lib:versions", + out_label = "//docs:versions_doc.md", +) + +stardoc_with_diff_test( + name = "write_file", + bzl_library_target = "//rules:write_file", + out_label = "//docs:write_file_doc.md", +) + +# update_docs must be at the bottom of the BUILD file +update_docs( + name = "update", + docs_folder = "docs", ) diff --git a/docs/analysis_test_doc.md b/docs/analysis_test_doc.md index 1a564ae..ebb95a4 100755 --- a/docs/analysis_test_doc.md +++ b/docs/analysis_test_doc.md @@ -2,7 +2,7 @@ A test verifying other targets can be successfully analyzed as part of a `bazel test` -<a id="#analysis_test"></a> +<a id="analysis_test"></a> ## analysis_test @@ -42,7 +42,7 @@ Test rule checking that other targets can be successfully analyzed. | 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 | | +| <a id="analysis_test-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | | +| <a id="analysis_test-targets"></a>targets | - | <a href="https://bazel.build/concepts/labels">List of labels</a> | required | | diff --git a/docs/build_test_doc.md b/docs/build_test_doc.md index 332dc58..ba13978 100755 --- a/docs/build_test_doc.md +++ b/docs/build_test_doc.md @@ -2,7 +2,7 @@ A test verifying other targets build as part of a `bazel test` -<a id="#build_test"></a> +<a id="build_test"></a> ## build_test @@ -36,6 +36,6 @@ Typical usage: | :------------- | :------------- | :------------- | | <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 | +| <a id="build_test-kwargs"></a>kwargs | The [common attributes for tests](https://bazel.build/reference/be/common-definitions#common-attributes-tests). | none | diff --git a/docs/bzl_library.md b/docs/bzl_library.md new file mode 100755 index 0000000..f4b0dc7 --- /dev/null +++ b/docs/bzl_library.md @@ -0,0 +1,88 @@ +<!-- Generated with Stardoc: http://skydoc.bazel.build --> + +Skylib module containing a library rule for aggregating rules files. + +<a id="bzl_library"></a> + +## bzl_library + +<pre> +bzl_library(<a href="#bzl_library-name">name</a>, <a href="#bzl_library-deps">deps</a>, <a href="#bzl_library-srcs">srcs</a>) +</pre> + +Creates a logical collection of Starlark .bzl and .scl files. + +Example: + Suppose your project has the following structure: + + ``` + [workspace]/ + WORKSPACE + BUILD + checkstyle/ + BUILD + checkstyle.bzl + lua/ + BUILD + lua.bzl + luarocks.bzl + ``` + + In this case, you can have `bzl_library` targets in `checkstyle/BUILD` and + `lua/BUILD`: + + `checkstyle/BUILD`: + + ```python + load("@bazel_skylib//:bzl_library.bzl", "bzl_library") + + bzl_library( + name = "checkstyle-rules", + srcs = ["checkstyle.bzl"], + ) + ``` + + `lua/BUILD`: + + ```python + load("@bazel_skylib//:bzl_library.bzl", "bzl_library") + + bzl_library( + name = "lua-rules", + srcs = [ + "lua.bzl", + "luarocks.bzl", + ], + ) + ``` + + +**ATTRIBUTES** + + +| Name | Description | Type | Mandatory | Default | +| :------------- | :------------- | :------------- | :------------- | :------------- | +| <a id="bzl_library-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | | +| <a id="bzl_library-deps"></a>deps | List of other <code>bzl_library</code> targets that are required by the Starlark files listed in <code>srcs</code>. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | <code>[]</code> | +| <a id="bzl_library-srcs"></a>srcs | List of <code>.bzl</code> and <code>.scl</code> files that are processed to create this target. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | <code>[]</code> | + + +<a id="StarlarkLibraryInfo"></a> + +## StarlarkLibraryInfo + +<pre> +StarlarkLibraryInfo(<a href="#StarlarkLibraryInfo-srcs">srcs</a>, <a href="#StarlarkLibraryInfo-transitive_srcs">transitive_srcs</a>) +</pre> + +Information on contained Starlark rules. + +**FIELDS** + + +| Name | Description | +| :------------- | :------------- | +| <a id="StarlarkLibraryInfo-srcs"></a>srcs | Top level rules files. | +| <a id="StarlarkLibraryInfo-transitive_srcs"></a>transitive_srcs | Transitive closure of rules files required for interpretation of the srcs | + + diff --git a/docs/collections_doc.md b/docs/collections_doc.md index 1138850..cd9db8b 100755 --- a/docs/collections_doc.md +++ b/docs/collections_doc.md @@ -2,7 +2,7 @@ Skylib module containing functions that operate on collections. -<a id="#collections.after_each"></a> +<a id="collections.after_each"></a> ## collections.after_each @@ -25,7 +25,7 @@ Inserts `separator` after each item in `iterable`. A new list with `separator` after each item in `iterable`. -<a id="#collections.before_each"></a> +<a id="collections.before_each"></a> ## collections.before_each @@ -48,7 +48,7 @@ Inserts `separator` before each item in `iterable`. A new list with `separator` before each item in `iterable`. -<a id="#collections.uniq"></a> +<a id="collections.uniq"></a> ## collections.uniq diff --git a/docs/common_settings_doc.md b/docs/common_settings_doc.md index 736e48c..b224f52 100755 --- a/docs/common_settings_doc.md +++ b/docs/common_settings_doc.md @@ -6,10 +6,10 @@ 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 +https://bazel.build/extending/config#user-defined-build-settings -<a id="#bool_flag"></a> +<a id="bool_flag"></a> ## bool_flag @@ -24,10 +24,10 @@ A bool-typed build setting that can be set on the command line | 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_flag-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | | -<a id="#bool_setting"></a> +<a id="bool_setting"></a> ## bool_setting @@ -42,15 +42,15 @@ A bool-typed build setting that cannot be set on the command line | 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="bool_setting-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | | -<a id="#int_flag"></a> +<a id="int_flag"></a> ## int_flag <pre> -int_flag(<a href="#int_flag-name">name</a>) +int_flag(<a href="#int_flag-name">name</a>, <a href="#int_flag-make_variable">make_variable</a>) </pre> An int-typed build setting that can be set on the command line @@ -60,15 +60,16 @@ An int-typed build setting that can be set on the command line | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | -| <a id="int_flag-name"></a>name | A unique name for this target. | <a href="https://bazel.build/docs/build-ref.html#name">Name</a> | required | | +| <a id="int_flag-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | | +| <a id="int_flag-make_variable"></a>make_variable | If set, the build setting's value will be available as a Make variable with this name in the attributes of rules that list this build setting in their 'toolchains' attribute. | String | optional | <code>""</code> | -<a id="#int_setting"></a> +<a id="int_setting"></a> ## int_setting <pre> -int_setting(<a href="#int_setting-name">name</a>) +int_setting(<a href="#int_setting-name">name</a>, <a href="#int_setting-make_variable">make_variable</a>) </pre> An int-typed build setting that cannot be set on the command line @@ -78,15 +79,16 @@ An int-typed build setting that cannot be set on the command line | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | -| <a id="int_setting-name"></a>name | A unique name for this target. | <a href="https://bazel.build/docs/build-ref.html#name">Name</a> | required | | +| <a id="int_setting-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | | +| <a id="int_setting-make_variable"></a>make_variable | If set, the build setting's value will be available as a Make variable with this name in the attributes of rules that list this build setting in their 'toolchains' attribute. | String | optional | <code>""</code> | -<a id="#string_flag"></a> +<a id="string_flag"></a> ## string_flag <pre> -string_flag(<a href="#string_flag-name">name</a>, <a href="#string_flag-values">values</a>) +string_flag(<a href="#string_flag-name">name</a>, <a href="#string_flag-make_variable">make_variable</a>, <a href="#string_flag-values">values</a>) </pre> A string-typed build setting that can be set on the command line @@ -96,11 +98,12 @@ A string-typed build setting that can be set on the command line | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | -| <a id="string_flag-name"></a>name | A unique name for this target. | <a href="https://bazel.build/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_flag-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | | +| <a id="string_flag-make_variable"></a>make_variable | If set, the build setting's value will be available as a Make variable with this name in the attributes of rules that list this build setting in their 'toolchains' attribute. | String | optional | <code>""</code> | +| <a id="string_flag-values"></a>values | The list of allowed values for this setting. An error is raised if any other value is given. | List of strings | optional | <code>[]</code> | -<a id="#string_list_flag"></a> +<a id="string_list_flag"></a> ## string_list_flag @@ -115,10 +118,10 @@ A string list-typed build setting that can be set on the command line | 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_flag-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | | -<a id="#string_list_setting"></a> +<a id="string_list_setting"></a> ## string_list_setting @@ -133,15 +136,15 @@ A string list-typed build setting that cannot be set on the command line | 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_list_setting-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | | -<a id="#string_setting"></a> +<a id="string_setting"></a> ## string_setting <pre> -string_setting(<a href="#string_setting-name">name</a>, <a href="#string_setting-values">values</a>) +string_setting(<a href="#string_setting-name">name</a>, <a href="#string_setting-make_variable">make_variable</a>, <a href="#string_setting-values">values</a>) </pre> A string-typed build setting that cannot be set on the command line @@ -151,11 +154,12 @@ A string-typed build setting that cannot be set on the command line | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | -| <a id="string_setting-name"></a>name | A unique name for this target. | <a href="https://bazel.build/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="string_setting-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | | +| <a id="string_setting-make_variable"></a>make_variable | If set, the build setting's value will be available as a Make variable with this name in the attributes of rules that list this build setting in their 'toolchains' attribute. | String | optional | <code>""</code> | +| <a id="string_setting-values"></a>values | The list of allowed values for this setting. An error is raised if any other value is given. | List of strings | optional | <code>[]</code> | -<a id="#BuildSettingInfo"></a> +<a id="BuildSettingInfo"></a> ## BuildSettingInfo diff --git a/docs/copy_directory_doc.md b/docs/copy_directory_doc.md new file mode 100755 index 0000000..1177d20 --- /dev/null +++ b/docs/copy_directory_doc.md @@ -0,0 +1,63 @@ +<!-- Generated with Stardoc: http://skydoc.bazel.build --> + +A rule that copies a directory to another place. + +The rule uses a Bash command on Linux/macOS/non-Windows, and a cmd.exe command +on Windows (no Bash is required). + + +<a id="copy_directory"></a> + +## copy_directory + +<pre> +copy_directory(<a href="#copy_directory-name">name</a>, <a href="#copy_directory-src">src</a>, <a href="#copy_directory-out">out</a>, <a href="#copy_directory-kwargs">kwargs</a>) +</pre> + +Copies a directory 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). + +If using this rule with source directories, it is recommended that you use the +`--host_jvm_args=-DBAZEL_TRACK_SOURCE_DIRECTORIES=1` startup option so that changes +to files within source directories are detected. See +https://github.com/bazelbuild/bazel/commit/c64421bc35214f0414e4f4226cc953e8c55fa0d2 +for more context. + + +**PARAMETERS** + + +| Name | Description | Default Value | +| :------------- | :------------- | :------------- | +| <a id="copy_directory-name"></a>name | Name of the rule. | none | +| <a id="copy_directory-src"></a>src | The directory to make a copy of. Can be a source directory or TreeArtifact. | none | +| <a id="copy_directory-out"></a>out | Path of the output directory, relative to this package. | none | +| <a id="copy_directory-kwargs"></a>kwargs | further keyword arguments, e.g. <code>visibility</code> | none | + + +<a id="copy_directory_action"></a> + +## copy_directory_action + +<pre> +copy_directory_action(<a href="#copy_directory_action-ctx">ctx</a>, <a href="#copy_directory_action-src">src</a>, <a href="#copy_directory_action-dst">dst</a>, <a href="#copy_directory_action-is_windows">is_windows</a>) +</pre> + +Helper function that creates an action to copy a directory from src to dst. + +This helper is used by copy_directory. It is exposed as a public API so it can be used within +other rule implementations. + + +**PARAMETERS** + + +| Name | Description | Default Value | +| :------------- | :------------- | :------------- | +| <a id="copy_directory_action-ctx"></a>ctx | The rule context. | none | +| <a id="copy_directory_action-src"></a>src | The directory to make a copy of. Can be a source directory or TreeArtifact. | none | +| <a id="copy_directory_action-dst"></a>dst | The directory to copy to. Must be a TreeArtifact. | none | +| <a id="copy_directory_action-is_windows"></a>is_windows | If true, an cmd.exe action is created so there is no bash dependency. | <code>False</code> | + + diff --git a/docs/copy_file_doc.md b/docs/copy_file_doc.md index 47a1244..ed297a6 100755 --- a/docs/copy_file_doc.md +++ b/docs/copy_file_doc.md @@ -9,7 +9,7 @@ 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> +<a id="copy_file"></a> ## copy_file diff --git a/docs/dicts_doc.md b/docs/dicts_doc.md index 5e8bce6..2360325 100755 --- a/docs/dicts_doc.md +++ b/docs/dicts_doc.md @@ -2,7 +2,7 @@ Skylib module containing functions that operate on dictionaries. -<a id="#dicts.add"></a> +<a id="dicts.add"></a> ## dicts.add @@ -34,3 +34,49 @@ dictionary, and the sum of a single dictionary is a copy of itself. A new `dict` that has all the entries of the given dictionaries. +<a id="dicts.omit"></a> + +## dicts.omit + +<pre> +dicts.omit(<a href="#dicts.omit-dictionary">dictionary</a>, <a href="#dicts.omit-keys">keys</a>) +</pre> + +Returns a new `dict` that has all the entries of `dictionary` with keys not in `keys`. + +**PARAMETERS** + + +| Name | Description | Default Value | +| :------------- | :------------- | :------------- | +| <a id="dicts.omit-dictionary"></a>dictionary | A <code>dict</code>. | none | +| <a id="dicts.omit-keys"></a>keys | A sequence. | none | + +**RETURNS** + +A new `dict` that has all the entries of `dictionary` with keys not in `keys`. + + +<a id="dicts.pick"></a> + +## dicts.pick + +<pre> +dicts.pick(<a href="#dicts.pick-dictionary">dictionary</a>, <a href="#dicts.pick-keys">keys</a>) +</pre> + +Returns a new `dict` that has all the entries of `dictionary` with keys in `keys`. + +**PARAMETERS** + + +| Name | Description | Default Value | +| :------------- | :------------- | :------------- | +| <a id="dicts.pick-dictionary"></a>dictionary | A <code>dict</code>. | none | +| <a id="dicts.pick-keys"></a>keys | A sequence. | none | + +**RETURNS** + +A new `dict` that has all the entries of `dictionary` with keys in `keys`. + + diff --git a/docs/diff_test_doc.md b/docs/diff_test_doc.md index fd62a38..c9189ec 100755 --- a/docs/diff_test_doc.md +++ b/docs/diff_test_doc.md @@ -6,12 +6,12 @@ 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> +<a id="diff_test"></a> ## diff_test <pre> -diff_test(<a href="#diff_test-name">name</a>, <a href="#diff_test-file1">file1</a>, <a href="#diff_test-file2">file2</a>, <a href="#diff_test-kwargs">kwargs</a>) +diff_test(<a href="#diff_test-name">name</a>, <a href="#diff_test-file1">file1</a>, <a href="#diff_test-file2">file2</a>, <a href="#diff_test-failure_message">failure_message</a>, <a href="#diff_test-kwargs">kwargs</a>) </pre> A test that compares two files. @@ -25,8 +25,9 @@ The test succeeds if the files' contents match. | Name | Description | Default Value | | :------------- | :------------- | :------------- | | <a id="diff_test-name"></a>name | The name of the test rule. | none | -| <a id="diff_test-file1"></a>file1 | Label of the file to compare to <code>file2</code>. | none | -| <a id="diff_test-file2"></a>file2 | Label of the file to compare to <code>file1</code>. | none | -| <a id="diff_test-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 | +| <a id="diff_test-file1"></a>file1 | Label of the file to compare to <code>file2</code>. | none | +| <a id="diff_test-file2"></a>file2 | Label of the file to compare to <code>file1</code>. | none | +| <a id="diff_test-failure_message"></a>failure_message | Additional message to log if the files' contents do not match. | <code>None</code> | +| <a id="diff_test-kwargs"></a>kwargs | The [common attributes for tests](https://bazel.build/reference/be/common-definitions#common-attributes-tests). | none | diff --git a/docs/expand_template_doc.md b/docs/expand_template_doc.md new file mode 100755 index 0000000..6d6dd2a --- /dev/null +++ b/docs/expand_template_doc.md @@ -0,0 +1,32 @@ +<!-- Generated with Stardoc: http://skydoc.bazel.build --> + +A rule that performs template expansion. + + +<a id="expand_template"></a> + +## expand_template + +<pre> +expand_template(<a href="#expand_template-name">name</a>, <a href="#expand_template-out">out</a>, <a href="#expand_template-substitutions">substitutions</a>, <a href="#expand_template-template">template</a>) +</pre> + +Template expansion + +This performs a simple search over the template file for the keys in +substitutions, and replaces them with the corresponding values. + +There is no special syntax for the keys. To avoid conflicts, you would need to +explicitly add delimiters to the key strings, for example "{KEY}" or "@KEY@". + +**ATTRIBUTES** + + +| Name | Description | Type | Mandatory | Default | +| :------------- | :------------- | :------------- | :------------- | :------------- | +| <a id="expand_template-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | | +| <a id="expand_template-out"></a>out | The destination of the expanded file. | <a href="https://bazel.build/concepts/labels">Label</a> | required | | +| <a id="expand_template-substitutions"></a>substitutions | A dictionary mapping strings to their substitutions. | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a> | required | | +| <a id="expand_template-template"></a>template | The template file to expand. | <a href="https://bazel.build/concepts/labels">Label</a> | required | | + + diff --git a/docs/maintainers_guide.md b/docs/maintainers_guide.md index 8a009c2..f5408ce 100644 --- a/docs/maintainers_guide.md +++ b/docs/maintainers_guide.md @@ -25,7 +25,7 @@ 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 +2. Given a choice between breaking backwards compatibility 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. @@ -40,11 +40,13 @@ widespread pain, and shouldn't be done lightly. Therefore: 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.) +If a PR changes any docstring in an existing module, the corresponding +`stardoc_with_diff_test` in `docs` will fail. To fix the test, ask the PR +author to run `bazel run //docs:update`. + +If a PR adds a new module, make sure that the PR also adds a corresponding +`stardoc_with_diff_test` target in `docs/BUILD` and a corresponding `*doc.md` +file under `docs` (generated by `bazel run //docs:update`). ## Making a New Release @@ -70,24 +72,33 @@ Name 1, Name 2, Name 3 (alphabetically from `git log`) -------------------------------------------------------------------------------- -2. Bump `version` in version.bzl to the new version. +2. Bump `version` in version.bzl, MODULE.bazel, *and* gazelle/MODULE.bazel to + the new version. + TODO(#386): add a test to make sure all the versions are in sync. 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" +4. `bazel build //distribution` +5. Copy the `bazel-skylib-$VERSION.tar.gz` and + `bazel-skylib-gazelle-plugin-$VERSION.tar.gz` tarballs to the mirror (you'll + need Bazel developer gcloud credentials; assuming you are a Bazel developer, + you can obtain them via `gcloud init`): + +```bash +gsutil cp bazel-bin/distribution/bazel-skylib{,-gazelle-plugin}-$VERSION.tar.gz gs://bazel-mirror/github.com/bazelbuild/bazel-skylib/releases/download/$VERSION/ +gsutil setmeta -h "Cache-Control: public, max-age=31536000" gs://bazel-mirror/github.com/bazelbuild/bazel-skylib/releases/download/$VERSION/bazel-skylib{,-gazelle-plugin}-$VERSION.tar.gz ``` -6. Run `sha256sum bazel-bin/distro/bazel-skylib-$VERSION.tar.gz`; you'll need - the checksum for the release notes. +6. Obtain checksums for release notes: + +```bash +sha256sum bazel-bin/distribution/bazel-skylib-$VERSION.tar.gz +sha256sum bazel-bin/distribution/bazel-skylib-gazelle-plugin-$VERSION.tar.gz +```` + 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: + `bazel-skylib-$VERSION.tar.gz` and + `bazel-skylib-gazelle-plugin-$VERSION.tar.gz` to the release. For the + release notes, use the CHANGELOG.md entry plus the following template: -------------------------------------------------------------------------------- @@ -95,20 +106,88 @@ gsutil setmeta -h "Cache-Control: public, max-age=31536000" "gs://bazel-mirror/g ``` load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive") + http_archive( name = "bazel_skylib", + sha256 = "$SHA256SUM" 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() ``` +***Additional WORKSPACE setup for the Gazelle plugin*** + +```starlark +http_archive( + name = "bazel_skylib_gazelle_plugin", + sha256 = "$SHA256SUM_GAZELLE_PLUGIN", + urls = [ + "https://mirror.bazel.build/github.com/bazelbuild/bazel-skylib/releases/download/$VERSION/bazel-skylib-gazelle-plugin-$VERSION.tar.gz", + "https://github.com/bazelbuild/bazel-skylib/releases/download/$VERSION/bazel-skylib-gazelle-plugin-$VERSION.tar.gz", + ], +) + +load("@bazel_skylib_gazelle_plugin//:workspace.bzl", "bazel_skylib_gazelle_plugin_workspace") + +bazel_skylib_gazelle_plugin_workspace() + +load("@bazel_skylib_gazelle_plugin//:setup.bzl", "bazel_skylib_gazelle_plugin_setup") + +bazel_skylib_gazelle_plugin_setup() +``` + **Using the rules** See [the source](https://github.com/bazelbuild/bazel-skylib/tree/$VERSION). ---------------------------------------------------------------------------------
\ No newline at end of file +-------------------------------------------------------------------------------- + +8. Obtain [Subresource Integrity](https://w3c.github.io/webappsec-subresource-integrity/#integrity-metadata-description) + format checksums for bzlmod: + +```bash +echo -n sha256-; cat bazel-bin/distribution/bazel-skylib-$VERSION.tar.gz | openssl dgst -sha256 -binary | base64 +echo -n sha256-; cat bazel-bin/distribution/bazel-skylib-gazelle-plugin-$VERSION.tar.gz | openssl dgst -sha256 -binary | base64 +``` + +9. Create a PR at [Bazel Central Registry](https://github.com/bazelbuild/bazel-central-registry) + to update the registry's versions of bazel_skylib and + bazel_skylib_gazelle_plugin. + + Use https://github.com/bazelbuild/bazel-central-registry/pull/403 as the + model; you will need to update `modules/bazel_skylib/metadata.json` and + `modules/bazel_skylib_gazelle_plugin/metadata.json` to list the new version + in `versions`, and create new $VERSION subdirectories for the updated + modules, using the latest existing version subdirectories as the guide. Use + Subresource Integrity checksums obtained above in the new `source.json` + files. + + Ensure that the MODULE.bazel files you add in the new $VERSION + subdirectories exactly match the MODULE.bazel file packaged in + bazel-skylib-$VERSION.tar.gz and bazel-skylib-gazelle-plugin-$VERSION.tar.gz + tarballs - or buildkite checks will fail. + +10. Once the Bazel Central Registry PR is merged, insert in the release + description after the WORKSPACE setup section: + +-------------------------------------------------------------------------------- + +**MODULE.bazel setup** + +```starlark +bazel_dep(name = "bazel_skylib", version = "$VERSION") +``` + +And for the Gazelle plugin: + +```starlark +bazel_dep(name = "bazel_skylib_gazelle_plugin", version = "$VERSION", dev_dependency = True) +``` + +-------------------------------------------------------------------------------- diff --git a/docs/native_binary_doc.md b/docs/native_binary_doc.md index 1a330ca..2b603be 100755 --- a/docs/native_binary_doc.md +++ b/docs/native_binary_doc.md @@ -5,57 +5,58 @@ 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="". +don't depend on Bash and work with --shell_executable="". -<a id="#native_binary"></a> +<a id="native_binary"></a> ## native_binary <pre> -native_binary(<a href="#native_binary-name">name</a>, <a href="#native_binary-src">src</a>, <a href="#native_binary-out">out</a>, <a href="#native_binary-data">data</a>, <a href="#native_binary-kwargs">kwargs</a>) +native_binary(<a href="#native_binary-name">name</a>, <a href="#native_binary-data">data</a>, <a href="#native_binary-out">out</a>, <a href="#native_binary-src">src</a>) </pre> + Wraps a pre-built binary or script with a binary rule. -You can "bazel run" this rule like any other binary rule, and use it as a tool in genrule.tools for example. You can also augment the binary with runfiles. +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** +**ATTRIBUTES** -| 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 | +| Name | Description | Type | Mandatory | Default | +| :------------- | :------------- | :------------- | :------------- | :------------- | +| <a id="native_binary-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | | +| <a id="native_binary-data"></a>data | data dependencies. See https://bazel.build/reference/be/common-definitions#typical.data | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | <code>[]</code> | +| <a id="native_binary-out"></a>out | An output name for the copy of the binary | String | required | | +| <a id="native_binary-src"></a>src | path of the pre-built executable | <a href="https://bazel.build/concepts/labels">Label</a> | required | | -<a id="#native_test"></a> +<a id="native_test"></a> ## native_test <pre> -native_test(<a href="#native_test-name">name</a>, <a href="#native_test-src">src</a>, <a href="#native_test-out">out</a>, <a href="#native_test-data">data</a>, <a href="#native_test-kwargs">kwargs</a>) +native_test(<a href="#native_test-name">name</a>, <a href="#native_test-data">data</a>, <a href="#native_test-out">out</a>, <a href="#native_test-src">src</a>) </pre> + Wraps a pre-built binary or script with a test rule. -You can "bazel test" this rule like any other test rule. You can also augment the binary with -runfiles. +You can "bazel test" this rule like any other test rule. You can also augment +the binary with runfiles. -**PARAMETERS** +**ATTRIBUTES** -| 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 | +| Name | Description | Type | Mandatory | Default | +| :------------- | :------------- | :------------- | :------------- | :------------- | +| <a id="native_test-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | | +| <a id="native_test-data"></a>data | data dependencies. See https://bazel.build/reference/be/common-definitions#typical.data | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | <code>[]</code> | +| <a id="native_test-out"></a>out | An output name for the copy of the binary | String | required | | +| <a id="native_test-src"></a>src | path of the pre-built executable | <a href="https://bazel.build/concepts/labels">Label</a> | required | | diff --git a/docs/new_sets_doc.md b/docs/new_sets_doc.md index e34107f..4f7fde2 100755 --- a/docs/new_sets_doc.md +++ b/docs/new_sets_doc.md @@ -11,7 +11,7 @@ Skylib module containing common hash-set algorithms. `types.is_set()` method in types.bzl. -<a id="#sets.make"></a> +<a id="sets.make"></a> ## sets.make @@ -36,7 +36,7 @@ All elements must be hashable. A set containing the passed in values. -<a id="#sets.copy"></a> +<a id="sets.copy"></a> ## sets.copy @@ -58,7 +58,7 @@ Creates a new set from another set. A new set containing the same elements as `s`. -<a id="#sets.to_list"></a> +<a id="sets.to_list"></a> ## sets.to_list @@ -80,7 +80,7 @@ Creates a list from the values in the set. A list of values inserted into the set. -<a id="#sets.insert"></a> +<a id="sets.insert"></a> ## sets.insert @@ -106,7 +106,7 @@ Element must be hashable. This mutates the original set. The set `s` with `e` included. -<a id="#sets.contains"></a> +<a id="sets.contains"></a> ## sets.contains @@ -129,7 +129,7 @@ Checks for the existence of an element in a set. True if the element exists in the set, False if the element does not. -<a id="#sets.is_equal"></a> +<a id="sets.is_equal"></a> ## sets.is_equal @@ -152,7 +152,7 @@ Returns whether two sets are equal. True if `a` is equal to `b`, False otherwise. -<a id="#sets.is_subset"></a> +<a id="sets.is_subset"></a> ## sets.is_subset @@ -175,7 +175,7 @@ Returns whether `a` is a subset of `b`. True if `a` is a subset of `b`, False otherwise. -<a id="#sets.disjoint"></a> +<a id="sets.disjoint"></a> ## sets.disjoint @@ -201,7 +201,7 @@ Two sets are disjoint if they have no elements in common. True if `a` and `b` are disjoint, False otherwise. -<a id="#sets.intersection"></a> +<a id="sets.intersection"></a> ## sets.intersection @@ -224,7 +224,7 @@ Returns the intersection of two sets. A set containing the elements that are in both `a` and `b`. -<a id="#sets.union"></a> +<a id="sets.union"></a> ## sets.union @@ -246,7 +246,7 @@ Returns the union of several sets. The set union of all sets in `*args`. -<a id="#sets.difference"></a> +<a id="sets.difference"></a> ## sets.difference @@ -269,7 +269,7 @@ Returns the elements in `a` that are not in `b`. A set containing the elements that are in `a` but not in `b`. -<a id="#sets.length"></a> +<a id="sets.length"></a> ## sets.length @@ -291,7 +291,7 @@ Returns the number of elements in a set. An integer representing the number of elements in the set. -<a id="#sets.remove"></a> +<a id="sets.remove"></a> ## sets.remove @@ -317,7 +317,7 @@ Element must be hashable. This mutates the original set. The set `s` with `e` removed. -<a id="#sets.repr"></a> +<a id="sets.repr"></a> ## sets.repr @@ -339,7 +339,7 @@ Returns a string value representing the set. A string representing the set. -<a id="#sets.str"></a> +<a id="sets.str"></a> ## sets.str diff --git a/docs/partial_doc.md b/docs/partial_doc.md index d772ec8..97d4094 100755 --- a/docs/partial_doc.md +++ b/docs/partial_doc.md @@ -7,7 +7,7 @@ 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> +<a id="partial.make"></a> ## partial.make @@ -123,7 +123,7 @@ partial.call(func, x=2) A new `partial` that can be called using `call` -<a id="#partial.call"></a> +<a id="partial.call"></a> ## partial.call @@ -147,7 +147,7 @@ Calls a partial created using `make`. Whatever the function in the partial returns. -<a id="#partial.is_instance"></a> +<a id="partial.is_instance"></a> ## partial.is_instance diff --git a/docs/paths_doc.md b/docs/paths_doc.md index e0d8116..e9d619d 100755 --- a/docs/paths_doc.md +++ b/docs/paths_doc.md @@ -7,7 +7,7 @@ path separators (forward slash, "/"); they do not handle Windows-style paths with backslash separators or drive letters. -<a id="#paths.basename"></a> +<a id="paths.basename"></a> ## paths.basename @@ -35,7 +35,7 @@ the final slash). The basename of the path, which includes the extension. -<a id="#paths.dirname"></a> +<a id="paths.dirname"></a> ## paths.dirname @@ -62,7 +62,7 @@ included, unless omitting them would make the dirname empty. The dirname of the path. -<a id="#paths.is_absolute"></a> +<a id="paths.is_absolute"></a> ## paths.is_absolute @@ -84,7 +84,7 @@ Returns `True` if `path` is an absolute path. `True` if `path` is an absolute path. -<a id="#paths.join"></a> +<a id="paths.join"></a> ## paths.join @@ -116,7 +116,7 @@ If any component is an absolute path, all previous components are discarded. A string containing the joined paths. -<a id="#paths.normalize"></a> +<a id="paths.normalize"></a> ## paths.normalize @@ -153,7 +153,7 @@ POSIX platforms; specifically: The normalized path. -<a id="#paths.relativize"></a> +<a id="paths.relativize"></a> ## paths.relativize @@ -185,7 +185,7 @@ the path both start with the same initial parent references. The portion of `path` that is relative to `start`. -<a id="#paths.replace_extension"></a> +<a id="paths.replace_extension"></a> ## paths.replace_extension @@ -211,7 +211,7 @@ If the path has no extension, the new extension is added to it. The path with the extension replaced (or added, if it did not have one). -<a id="#paths.split_extension"></a> +<a id="paths.split_extension"></a> ## paths.split_extension diff --git a/docs/private/BUILD b/docs/private/BUILD new file mode 100644 index 0000000..f8c832b --- /dev/null +++ b/docs/private/BUILD @@ -0,0 +1 @@ +# No targets in this package diff --git a/docs/private/stardoc_with_diff_test.bzl b/docs/private/stardoc_with_diff_test.bzl new file mode 100644 index 0000000..a8542f3 --- /dev/null +++ b/docs/private/stardoc_with_diff_test.bzl @@ -0,0 +1,111 @@ +# Copyright 2022 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. + +"""Helpers for keeping stardoc documentation up-to-date. + +These are currently a private API in bazel-skylib. +See discussion: +https://github.com/bazelbuild/bazel-skylib/pull/321#issuecomment-1081166216 + +If you need a similar feature, you can consider using a similar rule +available from a third-party: +https://github.com/aspect-build/bazel-lib/blob/main/docs/docs.md +""" + +load("@bazel_skylib//rules:diff_test.bzl", "diff_test") +load("@bazel_skylib//rules:write_file.bzl", "write_file") +load("@io_bazel_stardoc//stardoc:stardoc.bzl", "stardoc") + +def stardoc_with_diff_test( + name, + bzl_library_target, + out_label): + """Creates a stardoc target coupled with a `diff_test` for a given `bzl_library`. + + This is helpful for minimizing boilerplate in repos with lots of stardoc targets. + + Args: + name: the stardoc target name + bzl_library_target: the label of the `bzl_library` target to generate documentation for + out_label: the label of the output MD file + """ + out_file = out_label.replace("//", "").replace(":", "/") + + # Generate MD from .bzl + stardoc( + name = name, + out = out_file.replace(".md", "-docgen.md"), + input = bzl_library_target + ".bzl", + deps = [bzl_library_target], + ) + + # Ensure that the generated MD has been updated in the local source tree + diff_test( + name = out_file.replace("/", "_").replace(".md", "-difftest"), + failure_message = "Please run \"bazel run //docs:update\"", + # Source file + file1 = out_label, + # Output from stardoc rule above + file2 = out_file.replace(".md", "-docgen.md"), + tags = ["no_windows"], + ) + +def update_docs( + name = "update", + docs_folder = "docs"): + """Creates a `sh_binary` target which copies over generated doc files to the local source tree. + + This is to be used in tandem with `stardoc_with_diff_test()` to produce a convenient workflow + for generating, testing, and updating all doc files as follows: + + ``` bash + bazel build //{docs_folder}/... && bazel test //{docs_folder}/... && bazel run //{docs_folder}:update + ``` + + eg. + + ``` bash + bazel build //docs/... && bazel test //docs/... && bazel run //docs:update + ``` + + The `update_docs()` invocation must come after/below any `stardoc_with_diff_test()` invocations + in the BUILD file. + + Args: + name: the name of the `sh_binary` target + docs_folder: the name of the folder containing the doc files in the local source tree + """ + content = ["#!/usr/bin/env bash", "cd ${BUILD_WORKSPACE_DIRECTORY}"] + data = [] + for r in native.existing_rules().values(): + if r["kind"] == "stardoc": + doc_gen = r["out"] + if doc_gen.startswith(":"): + doc_gen = doc_gen[1:] + doc_dest = doc_gen.replace("-docgen.md", ".md") + data.append(doc_gen) + content.append("cp -fv bazel-bin/{0}/{1} {2}".format(docs_folder, doc_gen, doc_dest)) + + update_script = name + ".sh" + write_file( + name = "gen_" + name, + out = update_script, + content = content, + ) + + native.sh_binary( + name = name, + srcs = [update_script], + data = data, + ) diff --git a/docs/regenerate_docs.sh b/docs/regenerate_docs.sh deleted file mode 100755 index d16ea63..0000000 --- a/docs/regenerate_docs.sh +++ /dev/null @@ -1,27 +0,0 @@ -#!/usr/bin/env bash - -# 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. -# -# A script to manually regenerate the documentation contained in the docs/ directory. -# Should be run from the WORKSPACE root. - -set -euo pipefail - -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" - cp $filename $target_filename -done diff --git a/docs/run_binary_doc.md b/docs/run_binary_doc.md index 96bada5..50b62e4 100755 --- a/docs/run_binary_doc.md +++ b/docs/run_binary_doc.md @@ -6,7 +6,7 @@ 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> +<a id="run_binary"></a> ## run_binary @@ -14,18 +14,20 @@ Runs a binary as a build action. This rule does not require Bash (unlike native. run_binary(<a href="#run_binary-name">name</a>, <a href="#run_binary-args">args</a>, <a href="#run_binary-env">env</a>, <a href="#run_binary-outs">outs</a>, <a href="#run_binary-srcs">srcs</a>, <a href="#run_binary-tool">tool</a>) </pre> -Runs a binary as a build action.<br/><br/>This rule does not require Bash (unlike <code>native.genrule</code>). +Runs a binary as a build action. + +This rule does not require Bash (unlike `native.genrule`). **ATTRIBUTES** | 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 | | +| <a id="run_binary-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | | +| <a id="run_binary-args"></a>args | Command line arguments of the binary.<br><br>Subject to [<code>$(location)</code>](https://bazel.build/reference/be/make-variables#predefined_label_variables) expansion. | List of strings | optional | <code>[]</code> | +| <a id="run_binary-env"></a>env | Environment variables of the action.<br><br>Subject to [<code>$(location)</code>](https://bazel.build/reference/be/make-variables#predefined_label_variables) expansion. | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a> | optional | <code>{}</code> | +| <a id="run_binary-outs"></a>outs | Output files generated by the action.<br><br>These labels are available for <code>$(location)</code> expansion in <code>args</code> and <code>env</code>. | List of labels | required | | +| <a id="run_binary-srcs"></a>srcs | Additional inputs of the action.<br><br>These labels are available for <code>$(location)</code> expansion in <code>args</code> and <code>env</code>. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | <code>[]</code> | +| <a id="run_binary-tool"></a>tool | The tool to run in the action.<br><br>Must be the label of a *_binary rule, of a rule that generates an executable file, or of a file that can be executed as a subprocess (e.g. an .exe or .bat file on Windows or a binary with executable permission on Linux). This label is available for <code>$(location)</code> expansion in <code>args</code> and <code>env</code>. | <a href="https://bazel.build/concepts/labels">Label</a> | required | | diff --git a/docs/select_file_doc.md b/docs/select_file_doc.md new file mode 100755 index 0000000..33c3bc4 --- /dev/null +++ b/docs/select_file_doc.md @@ -0,0 +1,28 @@ +<!-- Generated with Stardoc: http://skydoc.bazel.build --> + + +select_file() build rule implementation. + +Selects a single file from the outputs of a target by given relative path. + + +<a id="select_file"></a> + +## select_file + +<pre> +select_file(<a href="#select_file-name">name</a>, <a href="#select_file-srcs">srcs</a>, <a href="#select_file-subpath">subpath</a>) +</pre> + +Selects a single file from the outputs of a target by given relative path + +**ATTRIBUTES** + + +| Name | Description | Type | Mandatory | Default | +| :------------- | :------------- | :------------- | :------------- | :------------- | +| <a id="select_file-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | | +| <a id="select_file-srcs"></a>srcs | The target producing the file among other outputs | <a href="https://bazel.build/concepts/labels">Label</a> | required | | +| <a id="select_file-subpath"></a>subpath | Relative path to the file | String | required | | + + diff --git a/docs/selects_doc.md b/docs/selects_doc.md index 8bfd964..8e2f31b 100755 --- a/docs/selects_doc.md +++ b/docs/selects_doc.md @@ -2,7 +2,7 @@ Skylib module containing convenience interfaces for select(). -<a id="#selects.with_or"></a> +<a id="selects.with_or"></a> ## selects.with_or @@ -48,7 +48,7 @@ to ``` -<a id="#selects.with_or_dict"></a> +<a id="selects.with_or_dict"></a> ## selects.with_or_dict @@ -74,7 +74,7 @@ macros. A dictionary usable by a native `select()`. -<a id="#selects.config_setting_group"></a> +<a id="selects.config_setting_group"></a> ## selects.config_setting_group diff --git a/docs/shell_doc.md b/docs/shell_doc.md index 0759434..bd559b9 100755 --- a/docs/shell_doc.md +++ b/docs/shell_doc.md @@ -2,7 +2,7 @@ Skylib module containing shell utility functions. -<a id="#shell.array_literal"></a> +<a id="shell.array_literal"></a> ## shell.array_literal @@ -33,7 +33,7 @@ A string that represents the sequence as a shell array; that is, parentheses containing the quoted elements. -<a id="#shell.quote"></a> +<a id="shell.quote"></a> ## shell.quote diff --git a/docs/structs_doc.md b/docs/structs_doc.md index a409d86..667aa46 100755 --- a/docs/structs_doc.md +++ b/docs/structs_doc.md @@ -2,7 +2,7 @@ Skylib module containing functions that operate on structs. -<a id="#structs.to_dict"></a> +<a id="structs.to_dict"></a> ## structs.to_dict diff --git a/docs/subpackages_doc.md b/docs/subpackages_doc.md new file mode 100755 index 0000000..8a0956f --- /dev/null +++ b/docs/subpackages_doc.md @@ -0,0 +1,96 @@ +<!-- Generated with Stardoc: http://skydoc.bazel.build --> + +Skylib module containing common functions for working with native.subpackages() + + +<a id="subpackages.all"></a> + +## subpackages.all + +<pre> +subpackages.all(<a href="#subpackages.all-exclude">exclude</a>, <a href="#subpackages.all-allow_empty">allow_empty</a>, <a href="#subpackages.all-fully_qualified">fully_qualified</a>) +</pre> + +List all direct subpackages of the current package regardless of directory depth. + +The returned list contains all subpackages, but not subpackages of subpackages. + +Example: +Assuming the following BUILD files exist: + + BUILD + foo/BUILD + foo/sub/BUILD + bar/BUILD + baz/deep/dir/BUILD + +If the current package is '//' all() will return ['//foo', '//bar', +'//baz/deep/dir']. //foo/sub is not included because it is a direct +subpackage of '//foo' not '//' + +NOTE: fail()s if native.subpackages() is not supported. + + +**PARAMETERS** + + +| Name | Description | Default Value | +| :------------- | :------------- | :------------- | +| <a id="subpackages.all-exclude"></a>exclude | see native.subpackages(exclude) | <code>[]</code> | +| <a id="subpackages.all-allow_empty"></a>allow_empty | see native.subpackages(allow_empty) | <code>False</code> | +| <a id="subpackages.all-fully_qualified"></a>fully_qualified | It true return fully qualified Labels for subpackages, otherwise returns subpackage path relative to current package. | <code>True</code> | + +**RETURNS** + +A mutable sorted list containing all sub-packages of the current Bazel +package. + + +<a id="subpackages.exists"></a> + +## subpackages.exists + +<pre> +subpackages.exists(<a href="#subpackages.exists-relative_path">relative_path</a>) +</pre> + +Checks to see if relative_path is a direct subpackage of the current package. + +Example: + + BUILD + foo/BUILD + foo/sub/BUILD + +If the current package is '//' (the top-level BUILD file): + subpackages.exists("foo") == True + subpackages.exists("foo/sub") == False + subpackages.exists("bar") == False + +NOTE: fail()s if native.subpackages() is not supported in the current Bazel version. + + +**PARAMETERS** + + +| Name | Description | Default Value | +| :------------- | :------------- | :------------- | +| <a id="subpackages.exists-relative_path"></a>relative_path | a path to a subpackage to test, must not be an absolute Label. | none | + +**RETURNS** + +True if 'relative_path' is a subpackage of the current package. + + +<a id="subpackages.supported"></a> + +## subpackages.supported + +<pre> +subpackages.supported() +</pre> + + + + + diff --git a/docs/types_doc.md b/docs/types_doc.md index 7ab0a6c..bdc9cba 100755 --- a/docs/types_doc.md +++ b/docs/types_doc.md @@ -2,7 +2,7 @@ Skylib module containing functions checking types. -<a id="#types.is_list"></a> +<a id="types.is_list"></a> ## types.is_list @@ -24,7 +24,7 @@ Returns True if v is an instance of a list. True if v is an instance of a list, False otherwise. -<a id="#types.is_string"></a> +<a id="types.is_string"></a> ## types.is_string @@ -46,7 +46,7 @@ Returns True if v is an instance of a string. True if v is an instance of a string, False otherwise. -<a id="#types.is_bool"></a> +<a id="types.is_bool"></a> ## types.is_bool @@ -68,7 +68,7 @@ Returns True if v is an instance of a bool. True if v is an instance of a bool, False otherwise. -<a id="#types.is_none"></a> +<a id="types.is_none"></a> ## types.is_none @@ -90,7 +90,7 @@ Returns True if v has the type of None. True if v is None, False otherwise. -<a id="#types.is_int"></a> +<a id="types.is_int"></a> ## types.is_int @@ -112,7 +112,7 @@ Returns True if v is an instance of a signed integer. True if v is an instance of a signed integer, False otherwise. -<a id="#types.is_tuple"></a> +<a id="types.is_tuple"></a> ## types.is_tuple @@ -134,7 +134,7 @@ Returns True if v is an instance of a tuple. True if v is an instance of a tuple, False otherwise. -<a id="#types.is_dict"></a> +<a id="types.is_dict"></a> ## types.is_dict @@ -156,7 +156,7 @@ Returns True if v is an instance of a dict. True if v is an instance of a dict, False otherwise. -<a id="#types.is_function"></a> +<a id="types.is_function"></a> ## types.is_function @@ -178,7 +178,7 @@ Returns True if v is an instance of a function. True if v is an instance of a function, False otherwise. -<a id="#types.is_depset"></a> +<a id="types.is_depset"></a> ## types.is_depset @@ -200,7 +200,7 @@ Returns True if v is an instance of a `depset`. True if v is an instance of a `depset`, False otherwise. -<a id="#types.is_set"></a> +<a id="types.is_set"></a> ## types.is_set diff --git a/docs/unittest_doc.md b/docs/unittest_doc.md index 5472d74..353d05b 100755 --- a/docs/unittest_doc.md +++ b/docs/unittest_doc.md @@ -2,12 +2,21 @@ 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. +Unlike most Skylib files, this exports four modules: +* `unittest` contains functions to declare and define unit tests for ordinary + Starlark functions; +* `analysistest` contains functions to declare and define tests for analysis + phase behavior of a rule, such as a given target's providers or registered + actions; +* `loadingtest` contains functions to declare and define tests for loading + phase behavior, such as macros and `native.*`; +* `asserts` contains the assertions used within tests. +See https://bazel.build/extending/concepts for background about macros, rules, +and the different phases of a build. -<a id="#unittest_toolchain"></a> + +<a id="unittest_toolchain"></a> ## unittest_toolchain @@ -23,16 +32,16 @@ unittest_toolchain(<a href="#unittest_toolchain-name">name</a>, <a href="#unitte | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | -| <a id="unittest_toolchain-name"></a>name | A unique name for this target. | <a href="https://bazel.build/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-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | | +| <a id="unittest_toolchain-escape_chars_with"></a>escape_chars_with | Dictionary of characters that need escaping in test failure message to prefix appended to escape those characters. For example, <code>{"%": "%", ">": "^"}</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/rules/lib/dict">Dictionary: String -> String</a> | optional | <code>{}</code> | +| <a id="unittest_toolchain-escape_other_chars_with"></a>escape_other_chars_with | String to prefix every character in test failure message which is not a key in <code>escape_chars_with</code> before including that in <code>success_templ</code>. For example, <code>""</code> would prefix every character in the failure message (except those in the keys of <code>escape_chars_with</code>) with <code>\</code>. | String | optional | <code>""</code> | | <a id="unittest_toolchain-failure_templ"></a>failure_templ | Test script template with a single <code>%s</code>. That placeholder is replaced with the lines in the failure message joined with the string specified in <code>join_with</code>. The resulting script should print the failure message and exit with non-zero status. | String | required | | | <a id="unittest_toolchain-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> +<a id="analysistest.make"></a> ## analysistest.make @@ -86,7 +95,7 @@ A rule definition that should be stored in a global whose name ends in `_test`. -<a id="#analysistest.begin"></a> +<a id="analysistest.begin"></a> ## analysistest.begin @@ -94,9 +103,9 @@ A rule definition that should be stored in a global whose name ends in analysistest.begin(<a href="#analysistest.begin-ctx">ctx</a>) </pre> -Begins a unit test. +Begins an analysis test. -This should be the first function called in a unit test implementation +This should be the first function called in an analysis test implementation function. It initializes a "test environment" that is used to collect assertion failures so that they can be reported and logged at the end of the test. @@ -112,11 +121,11 @@ test. **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 +`analysistest.end`. Do not rely on internal details about the fields in this struct as it may change. -<a id="#analysistest.end"></a> +<a id="analysistest.end"></a> ## analysistest.end @@ -142,7 +151,7 @@ that the results are reported. A list of providers needed to automatically register the analysis test result. -<a id="#analysistest.fail"></a> +<a id="analysistest.fail"></a> ## analysistest.fail @@ -161,7 +170,7 @@ Unconditionally causes the current test to fail. | <a id="analysistest.fail-msg"></a>msg | The message to log describing the failure. | none | -<a id="#analysistest.target_actions"></a> +<a id="analysistest.target_actions"></a> ## analysistest.target_actions @@ -183,7 +192,7 @@ Returns a list of actions registered by the target under test. A list of actions registered by the target under test -<a id="#analysistest.target_bin_dir_path"></a> +<a id="analysistest.target_bin_dir_path"></a> ## analysistest.target_bin_dir_path @@ -205,7 +214,7 @@ Returns ctx.bin_dir.path for the target under test. Output bin dir path string. -<a id="#analysistest.target_under_test"></a> +<a id="analysistest.target_under_test"></a> ## analysistest.target_under_test @@ -227,7 +236,7 @@ Returns the target under test. The target under test. -<a id="#asserts.expect_failure"></a> +<a id="asserts.expect_failure"></a> ## asserts.expect_failure @@ -250,7 +259,7 @@ This requires that the analysis test is created with `analysistest.make()` and | <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> +<a id="asserts.equals"></a> ## asserts.equals @@ -271,7 +280,7 @@ Asserts that the given `expected` and `actual` values are equal. | <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> +<a id="asserts.false"></a> ## asserts.false @@ -291,7 +300,7 @@ Asserts that the given `condition` is false. | <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> +<a id="asserts.set_equals"></a> ## asserts.set_equals @@ -312,7 +321,7 @@ Asserts that the given `expected` and `actual` sets are equal. | <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> +<a id="asserts.new_set_equals"></a> ## asserts.new_set_equals @@ -333,7 +342,7 @@ Asserts that the given `expected` and `actual` sets are equal. | <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> +<a id="asserts.true"></a> ## asserts.true @@ -353,7 +362,7 @@ Asserts that the given `condition` is true. | <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> +<a id="loadingtest.make"></a> ## loadingtest.make @@ -375,7 +384,7 @@ Creates a loading phase test environment and test_suite. loading phase environment passed to other loadingtest functions -<a id="#loadingtest.equals"></a> +<a id="loadingtest.equals"></a> ## loadingtest.equals @@ -400,7 +409,7 @@ Creates a test case for asserting state at LOADING phase. None, creates test case -<a id="#register_unittest_toolchains"></a> +<a id="register_unittest_toolchains"></a> ## register_unittest_toolchains @@ -412,12 +421,12 @@ Registers the toolchains for unittest users. -<a id="#unittest.make"></a> +<a id="unittest.make"></a> ## unittest.make <pre> -unittest.make(<a href="#unittest.make-impl">impl</a>, <a href="#unittest.make-attrs">attrs</a>) +unittest.make(<a href="#unittest.make-impl">impl</a>, <a href="#unittest.make-attrs">attrs</a>, <a href="#unittest.make-doc">doc</a>) </pre> Creates a unit test rule from its implementation function. @@ -453,6 +462,7 @@ Recall that names of test rules must end in `_test`. | :------------- | :------------- | :------------- | | <a id="unittest.make-impl"></a>impl | The implementation function of the unit test. | none | | <a id="unittest.make-attrs"></a>attrs | An optional dictionary to supplement the attrs passed to the unit test's <code>rule()</code> constructor. | <code>{}</code> | +| <a id="unittest.make-doc"></a>doc | A description of the rule that can be extracted by documentation generating tools. | <code>""</code> | **RETURNS** @@ -460,7 +470,7 @@ A rule definition that should be stored in a global whose name ends in `_test`. -<a id="#unittest.suite"></a> +<a id="unittest.suite"></a> ## unittest.suite @@ -516,7 +526,7 @@ name each target. | <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> +<a id="unittest.begin"></a> ## unittest.begin @@ -546,7 +556,7 @@ A test environment struct that must be passed to assertions and finally to struct as it may change. -<a id="#unittest.end"></a> +<a id="unittest.end"></a> ## unittest.end @@ -572,7 +582,7 @@ that the results are reported. A list of providers needed to automatically register the test result. -<a id="#unittest.fail"></a> +<a id="unittest.fail"></a> ## unittest.fail diff --git a/docs/versions_doc.md b/docs/versions_doc.md index 83ee7a7..8986737 100755 --- a/docs/versions_doc.md +++ b/docs/versions_doc.md @@ -2,7 +2,7 @@ Skylib module containing functions for checking Bazel versions. -<a id="#versions.get"></a> +<a id="versions.get"></a> ## versions.get @@ -14,7 +14,7 @@ Returns the current Bazel version -<a id="#versions.parse"></a> +<a id="versions.parse"></a> ## versions.parse @@ -24,7 +24,10 @@ versions.parse(<a href="#versions.parse-bazel_version">bazel_version</a>) Parses a version string into a 3-tuple of ints -int tuples can be compared directly using binary operators (<, >). +int tuples can be compared directly using binary operators (<, >). + +For a development build of Bazel, this returns an unspecified version tuple +that compares higher than any released version. **PARAMETERS** @@ -39,7 +42,7 @@ int tuples can be compared directly using binary operators (<, >). An int 3-tuple of a (major, minor, patch) version. -<a id="#versions.check"></a> +<a id="versions.check"></a> ## versions.check @@ -59,7 +62,7 @@ Check that the version of Bazel is valid within the specified range. | <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> +<a id="versions.is_at_most"></a> ## versions.is_at_most @@ -79,10 +82,10 @@ Check that a version is lower or equals to a threshold. **RETURNS** -True if version <= threshold. +True if version <= threshold. -<a id="#versions.is_at_least"></a> +<a id="versions.is_at_least"></a> ## versions.is_at_least @@ -102,6 +105,6 @@ Check that a version is higher or equals to a threshold. **RETURNS** -True if version >= threshold. +True if version >= threshold. diff --git a/docs/write_file_doc.md b/docs/write_file_doc.md index 8f39376..e7c99f6 100755 --- a/docs/write_file_doc.md +++ b/docs/write_file_doc.md @@ -10,7 +10,7 @@ file. Instead they use Starlark's built-in file writing action (ctx.actions.write). -<a id="#write_file"></a> +<a id="write_file"></a> ## write_file @@ -30,6 +30,6 @@ Creates a UTF-8 encoded text file. | <a id="write_file-content"></a>content | A list of strings. Lines of text, the contents of the file. Newlines are added automatically after every line except the last one. | <code>[]</code> | | <a id="write_file-is_executable"></a>is_executable | A boolean. Whether to make the output file executable. When True, the rule's output can be executed using <code>bazel run</code> and can be in the srcs of binary and test rules that require executable sources. | <code>False</code> | | <a id="write_file-newline"></a>newline | one of ["auto", "unix", "windows"]: line endings to use. "auto" for platform-determined, "unix" for LF, and "windows" for CRLF. | <code>"auto"</code> | -| <a id="write_file-kwargs"></a>kwargs | further keyword arguments, e.g. <code>visibility</code> | none | +| <a id="write_file-kwargs"></a>kwargs | further keyword arguments, e.g. <code>visibility</code> | none | |