- The sh_binary rule is used to declare executable shell scripts.
- (sh_binary is a misnomer: its outputs aren't necessarily binaries.) This rule ensures
- that all dependencies are built, and appear in the runfiles area at execution time.
- We recommend that you name your sh_binary() rules after the name of the script minus
- the extension (e.g. .sh); the rule name and the file name must be distinct.
- sh_binary respects shebangs, so any available interpreter may be used (eg.
- #!/bin/zsh)
-
For a simple shell script with no dependencies and some data files: -
--sh_binary( - name = "foo", - srcs = ["foo.sh"], - data = glob(["datafiles/*.txt"]), -) -+ The `sh_binary` rule is used to declare executable shell scripts. + (`sh_binary` is a misnomer: its outputs aren't necessarily binaries.) This rule ensures + that all dependencies are built, and appear in the `runfiles` area at execution time. + We recommend that you name your `sh_binary()` rules after the name of the script minus + the extension (e.g. `.sh`); the rule name and the file name must be distinct. + `sh_binary` respects shebangs, so any available interpreter may be used (eg. + `#!/bin/zsh`) + + #### Example + + For a simple shell script with no dependencies and some data files: + + ```starlark + sh_binary( + name = "foo", + srcs = ["foo.sh"], + data = glob(["datafiles/*.txt"]), + ) + ``` """, executable = True, ) diff --git a/shell/private/sh_executable.bzl b/shell/private/sh_executable.bzl index 359667b..b1fea70 100644 --- a/shell/private/sh_executable.bzl +++ b/shell/private/sh_executable.bzl @@ -187,12 +187,11 @@ def make_sh_executable_rule(doc, extra_attrs = {}, **kwargs): allow_files = True, doc = """ The file containing the shell script. -
- 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
- data attribute.
-
deps
-at Typical attributes defined by
-most build rules.
-
- This attribute should be used to list other sh_library rules that provide
- interpreted program source code depended on by the code in srcs. The files
- provided by these rules will be present among the runfiles of this target.
-
- The main use for this rule is to aggregate together a logical
- "library" consisting of related scripts—programs in an
- interpreted language that does not require compilation or linking,
- such as the Bourne shell—and any data those programs need at
- run-time. Such "libraries" can then be used from
- the data attribute of one or
- more sh_binary rules.
-
- You can use the filegroup rule to aggregate data
- files.
-
- In interpreted programming languages, there's not always a clear
- distinction between "code" and "data": after all, the program is
- just "data" from the interpreter's point of view. For this reason
- this rule has three attributes which are all essentially equivalent:
- srcs, deps and data.
- The current implementation does not distinguish between the elements of these lists.
- All three attributes accept rules, source files and generated files.
- It is however good practice to use the attributes for their usual purpose (as with other rules).
-
+```starlark
sh_library(
name = "foo",
data = [
@@ -82,18 +76,17 @@ sh_library(
":deploy_foo", # another sh_binary with srcs
],
)
-
+```
""",
attrs = {
"srcs": attr.label_list(
allow_files = True,
doc = """
The list of input files.
-
- 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 source
- or . command.
-
deps
-at Typical attributes defined by
-most build rules.
-
- This attribute should be used to list other sh_library rules that provide
- interpreted program source code depended on by the code in srcs. The files
- provided by these rules will be present among the runfiles of this target.
-
A sh_test() rule creates a test written as a Bourne shell script.
See the -attributes common to all test rules (*_test).
+See the +[attributes common to all test rules (*_test)](https://bazel.build/reference/be/common-definitions#common-attributes-tests). -
+```
sh_test(
name = "foo_integration_test",
size = "small",
@@ -36,7 +36,7 @@ sh_test(
deps = [":foo_sh_lib"],
data = glob(["testdata/*.txt"]),
)
-
+```
""",
test = True,
fragments = ["coverage"],