Add stardoc targets for public bzl files (#67)
These targets act as regression tests for users who consume the bzl
files in their won rules for their own docs. In addition to the stardoc
targets, all missing docs from upstream `bazelbuild/bazel` have been
added for parity with https://bazel.build/reference/be/shell
diff --git a/MODULE.bazel b/MODULE.bazel
index c264ce0..4fa13cb 100644
--- a/MODULE.bazel
+++ b/MODULE.bazel
@@ -14,4 +14,5 @@
bazel_dep(name = "rules_shellcheck", version = "0.6.2", dev_dependency = True)
bazel_dep(name = "rules_testing", version = "0.9.0", dev_dependency = True)
+bazel_dep(name = "stardoc", version = "0.8.1", dev_dependency = True)
bazel_dep(name = "with_cfg.bzl", version = "0.14.1", dev_dependency = True)
diff --git a/docs/BUILD.bazel b/docs/BUILD.bazel
new file mode 100644
index 0000000..c1f2166
--- /dev/null
+++ b/docs/BUILD.bazel
@@ -0,0 +1,63 @@
+load("@stardoc//stardoc:stardoc.bzl", "stardoc")
+
+stardoc(
+ name = "sh_binary",
+ out = "sh_binary.md",
+ input = "//shell:sh_binary.bzl",
+ deps = ["//shell:rules_bzl"],
+)
+
+stardoc(
+ name = "sh_binary_info",
+ out = "sh_binary_info.md",
+ input = "//shell:sh_binary_info.bzl",
+ deps = ["//shell:rules_bzl"],
+)
+
+stardoc(
+ name = "sh_info",
+ out = "sh_info.md",
+ input = "//shell:sh_info.bzl",
+ deps = ["//shell:rules_bzl"],
+)
+
+stardoc(
+ name = "sh_library",
+ out = "sh_library.md",
+ input = "//shell:sh_library.bzl",
+ deps = ["//shell:rules_bzl"],
+)
+
+stardoc(
+ name = "sh_test",
+ out = "sh_test.md",
+ input = "//shell:sh_test.bzl",
+ deps = ["//shell:rules_bzl"],
+)
+
+stardoc(
+ name = "sh_toolchain",
+ out = "sh_toolchain.md",
+ input = "//shell/toolchains:sh_toolchain.bzl",
+ deps = ["//shell/toolchains:toolchains_bzl"],
+)
+
+stardoc(
+ name = "repositories",
+ out = "repositories.md",
+ input = "//shell:repositories.bzl",
+ deps = ["//shell:rules_bzl"],
+)
+
+filegroup(
+ name = "docs",
+ srcs = [
+ ":repositories.md",
+ ":sh_binary.md",
+ ":sh_binary_info.md",
+ ":sh_info.md",
+ ":sh_library.md",
+ ":sh_test.md",
+ ":sh_toolchain.md",
+ ],
+)
diff --git a/shell/BUILD b/shell/BUILD
index 4148901..758c3f7 100644
--- a/shell/BUILD
+++ b/shell/BUILD
@@ -17,13 +17,32 @@
visibility = ["//visibility:public"],
)
-bzl_library(
- name = "rules_bzl",
- srcs = [
+exports_files(
+ [
+ "repositories.bzl",
"sh_binary.bzl",
+ "sh_binary_info.bzl",
+ "sh_info.bzl",
"sh_library.bzl",
"sh_test.bzl",
],
visibility = ["//visibility:public"],
- deps = ["//shell/private:private_bzl"],
+)
+
+bzl_library(
+ name = "rules_bzl",
+ srcs = [
+ "repositories.bzl",
+ "sh_binary.bzl",
+ "sh_binary_info.bzl",
+ "sh_info.bzl",
+ "sh_library.bzl",
+ "sh_test.bzl",
+ ],
+ visibility = ["//visibility:public"],
+ deps = [
+ "//shell/private:private_bzl",
+ "//shell/private/repositories:bazel_tools_bzl",
+ "//shell/private/repositories:repositories_bzl",
+ ],
)
diff --git a/shell/private/repositories/BUILD b/shell/private/repositories/BUILD
index e69de29..1a7aae3 100644
--- a/shell/private/repositories/BUILD
+++ b/shell/private/repositories/BUILD
@@ -0,0 +1,17 @@
+load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
+
+bzl_library(
+ name = "repositories_bzl",
+ srcs = ["sh_config.bzl"],
+ visibility = ["//shell:__pkg__"],
+)
+
+bzl_library(
+ name = "bazel_tools_bzl",
+ srcs = [
+ "@bazel_tools//tools/build_defs/repo:cache.bzl",
+ "@bazel_tools//tools/build_defs/repo:http.bzl",
+ "@bazel_tools//tools/build_defs/repo:utils.bzl",
+ ],
+ visibility = ["//shell:__pkg__"],
+)
diff --git a/shell/private/sh_executable.bzl b/shell/private/sh_executable.bzl
index 9561f3d..915ea6e 100644
--- a/shell/private/sh_executable.bzl
+++ b/shell/private/sh_executable.bzl
@@ -189,19 +189,18 @@
_sh_executable_impl,
doc = doc,
attrs = {
- "srcs": attr.label_list(
- allow_files = True,
+ "data": attr.label_list(
doc = """
-The file containing the shell script.
+Files needed by this rule at runtime. May list file or rule targets. Generally allows any target.
<p>
- This attribute must be a singleton list, whose element is the shell script.
- This script must be executable, and may be a source file or a generated file.
- All other files required at runtime (whether scripts or data) belong in the
- <code>data</code> attribute.
+ The <code>runfiles</code> of targets in the <code>data</code> attribute appear in the
+ <code>*.runfiles</code> area of any executable which is output by or has a runtime dependency
+ on this target. This may include data files or binaries used when this target's
+ <code>srcs</code> are executed. See the
+ <a href="https://bazel.build/reference/be/common-definitions#typical.data">data dependencies</a>
+ section for more information about how to depend on and use data files.
</p>
""",
- ),
- "data": attr.label_list(
allow_files = True,
flags = ["SKIP_CONSTRAINTS_OVERRIDE"],
),
@@ -219,14 +218,47 @@
</p>
""",
),
- "_runfiles_dep": attr.label(
- default = Label("//shell/runfiles"),
+ "env": attr.string_dict(
+ doc = """
+Specifies additional environment variables to set when the target is executed by
+<code>bazel run</code> (for <code>sh_binary</code>) or <code>bazel test</code> (for
+<code>sh_test</code>).
+<p>
+ Values are subject to
+ <a href="https://bazel.build/reference/be/make-variables#predefined_label_variables">$(location)</a>
+ and
+ <a href="https://bazel.build/reference/be/make-variables">"Make variable"</a> substitution.
+</p>
+<p>
+ <em class="harmful">NOTE: The environment variables are not set when you run the target
+ outside of Bazel (for example, by manually executing the binary in <code>bazel-bin/</code>).</em>
+</p>
+""",
),
- "env": attr.string_dict(),
- "env_inherit": attr.string_list(),
+ "env_inherit": attr.string_list(
+ doc = """
+Specifies additional environment variables to inherit from the external environment when the
+target is executed by <code>bazel test</code>. Has no effect on <code>bazel run</code>.
+""",
+ ),
+ "srcs": attr.label_list(
+ allow_files = True,
+ doc = """
+The file containing the shell script.
+<p>
+ This attribute must be a singleton list, whose element is the shell script.
+ This script must be executable, and may be a source file or a generated file.
+ All other files required at runtime (whether scripts or data) belong in the
+ <code>data</code> attribute.
+</p>
+""",
+ ),
"use_bash_launcher": attr.bool(
doc = "Use a bash launcher initializing the runfiles library",
),
+ "_runfiles_dep": attr.label(
+ default = Label("//shell/runfiles"),
+ ),
"_windows_constraint": attr.label(
default = "@platforms//os:windows",
),
diff --git a/shell/private/sh_library.bzl b/shell/private/sh_library.bzl
index 8bf463d..61b9540 100644
--- a/shell/private/sh_library.bzl
+++ b/shell/private/sh_library.bzl
@@ -91,17 +91,6 @@
</pre>
""",
attrs = {
- "srcs": attr.label_list(
- allow_files = True,
- doc = """
-The list of input files.
-<p>
- This attribute should be used to list shell script source files that belong to
- this library. Scripts can load other scripts using the shell's <code>source</code>
- or <code>.</code> command.
-</p>
-""",
- ),
"data": attr.label_list(
allow_files = True,
flags = ["SKIP_CONSTRAINTS_OVERRIDE"],
@@ -120,6 +109,17 @@
</p>
""",
),
+ "srcs": attr.label_list(
+ allow_files = True,
+ doc = """
+The list of input files.
+<p>
+ This attribute should be used to list shell script source files that belong to
+ this library. Scripts can load other scripts using the shell's <code>source</code>
+ or <code>.</code> command.
+</p>
+""",
+ ),
},
provides = [ShInfo],
)
diff --git a/shell/private/sh_test.bzl b/shell/private/sh_test.bzl
index eaffd9e..b4ed6eb 100644
--- a/shell/private/sh_test.bzl
+++ b/shell/private/sh_test.bzl
@@ -41,11 +41,6 @@
test = True,
fragments = ["coverage"],
extra_attrs = {
- "_lcov_merger": attr.label(
- cfg = config.exec(exec_group = "test"),
- default = configuration_field(fragment = "coverage", name = "output_generator"),
- executable = True,
- ),
# Add the script as an attribute in order for sh_test to output code coverage results for
# code covered by CC binaries invocations.
"_collect_cc_coverage": attr.label(
@@ -53,5 +48,10 @@
default = "@bazel_tools//tools/test:collect_cc_coverage",
executable = True,
),
+ "_lcov_merger": attr.label(
+ cfg = config.exec(exec_group = "test"),
+ default = configuration_field(fragment = "coverage", name = "output_generator"),
+ executable = True,
+ ),
},
)
diff --git a/shell/toolchains/BUILD b/shell/toolchains/BUILD
index e69de29..717b68e 100644
--- a/shell/toolchains/BUILD
+++ b/shell/toolchains/BUILD
@@ -0,0 +1,12 @@
+load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
+
+bzl_library(
+ name = "toolchains_bzl",
+ srcs = ["sh_toolchain.bzl"],
+ visibility = ["//visibility:public"],
+)
+
+exports_files(
+ ["sh_toolchain.bzl"],
+ visibility = ["//visibility:public"],
+)
diff --git a/shell/toolchains/sh_toolchain.bzl b/shell/toolchains/sh_toolchain.bzl
index 64d2d3c..b9a9916 100644
--- a/shell/toolchains/sh_toolchain.bzl
+++ b/shell/toolchains/sh_toolchain.bzl
@@ -28,10 +28,6 @@
sh_toolchain = rule(
doc = "A runtime toolchain for shell targets.",
attrs = {
- "path": attr.string(
- doc = "Absolute path to the shell interpreter.",
- mandatory = True,
- ),
"launcher": attr.label(
doc = "The generic launcher binary to use to run sh_binary/sh_test targets (only used when targeting Windows).",
cfg = "target",
@@ -44,6 +40,10 @@
allow_single_file = True,
executable = True,
),
+ "path": attr.string(
+ doc = "Absolute path to the shell interpreter.",
+ mandatory = True,
+ ),
},
implementation = _sh_toolchain_impl,
)
