docs/versions/7.0.0/reference/be/shell.mdx

<html devsite>
<head>
  <meta name="project_path" value="/_project.yaml">
  <meta name="book_path" value="/versions/7.0.0/_book.yaml">
</head>
<body>
<!--
 This document is synchronized with Bazel releases.
 To edit, submit changes to the Bazel source code.
-->

<!-- Generated by //src/main/java/com/google/devtools/build/docgen:build-encyclopedia.zip -->
<html>
<body>

<h1 class="page-title">Shell Rules</h1>

{% dynamic setvar source_file "src/main/java/com/google/devtools/build/docgen/templates/be/rules.vm" %}
{% dynamic setvar version "7.0.0" %}
{% dynamic setvar original_path "/reference/be/shell" %}
{% include "_buttons.html" %}



<h2>Rules</h2>
<ul>
  <li>
    <a href="#sh_binary">
      sh_binary    </a>
  </li>
  <li>
    <a href="#sh_library">
      sh_library    </a>
  </li>
  <li>
    <a href="#sh_test">
      sh_test    </a>
  </li>
</ul>

  <h2 id="sh_binary">
    sh_binary
  </h2>

  <a class="button button-with-icon" href="https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/bazel/rules/sh/BazelShBinaryRule.java" target="_blank">
  View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span>
  </a>

  <pre class="rule-signature">sh_binary(<a href="#sh_binary.name">name</a>, <a href="#sh_binary.deps">deps</a>, <a href="#sh_binary.srcs">srcs</a>, <a href="common-definitions.html#typical.data">data</a>, <a href="common-definitions.html#binary.args">args</a>, <a href="common-definitions.html#common.compatible_with">compatible_with</a>, <a href="common-definitions.html#common.deprecation">deprecation</a>, <a href="common-definitions.html#common.distribs">distribs</a>, <a href="common-definitions.html#binary.env">env</a>, <a href="common-definitions.html#common.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_properties">exec_properties</a>, <a href="common-definitions.html#common.features">features</a>, <a href="common-definitions.html#typical.licenses">licenses</a>, <a href="common-definitions.html#binary.output_licenses">output_licenses</a>, <a href="common-definitions.html#common.restricted_to">restricted_to</a>, <a href="common-definitions.html#common.tags">tags</a>, <a href="common-definitions.html#common.target_compatible_with">target_compatible_with</a>, <a href="common-definitions.html#common.testonly">testonly</a>, <a href="common-definitions.html#common.toolchains">toolchains</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre>


<p>
  The <code>sh_binary</code> rule is used to declare executable shell scripts.
  (<code>sh_binary</code> is a misnomer: its outputs aren't necessarily binaries.) This rule ensures
  that all dependencies are built, and appear in the <code>runfiles</code> area at execution time.
  We recommend that you name your <code>sh_binary()</code> rules after the name of the script minus
  the extension (e.g. <code>.sh</code>); the rule name and the file name must be distinct.
  <code>sh_binary</code> respects shebangs, so any available interpreter may be used (eg.
  <code>#!/bin/zsh</code>)
</p>

<h4 id="sh_binary_examples">Example</h4>

<p>For a simple shell script with no dependencies and some data files:
</p>

<pre class="code">
sh_binary(
    name = "foo",
    srcs = ["foo.sh"],
    data = glob(["datafiles/*.txt"]),
)
</pre>



  <h3 id="sh_binary_args">Arguments</h3>
  <table class="table table-condensed table-bordered table-params">
    <colgroup>
      <col class="col-param" />
      <col class="param-description" />
    </colgroup>
    <thead>
      <tr>
        <th colspan="2">Attributes</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td id="sh_binary.name"><code>name</code></td>
        <td>
          <p><a href="/versions/7.0.0/concepts/labels#target-names">Name</a>; required</p>
          <p>A unique name for this target.</p>

        </td>
      </tr>
                <tr>
        <td id="sh_binary.deps">
          <code>deps</code>
        </td>
        <td>
                    <p>List of <a href="/versions/7.0.0/concepts/labels">labels</a>; default is <code>[]</code></p>
                              The list of "library" targets to be aggregated into this target.
          See general comments about <code>deps</code>
          at <a href="/versions/7.0.0/reference/be/common-definitions#typical.deps">Typical attributes defined by
          most build rules</a>.
          <p>
            This attribute should be used to list other <code>sh_library</code> rules that provide
            interpreted program source code depended on by the code in <code>srcs</code>. The files
            provided by these rules will be present among the <code>runfiles</code> of this target.
          </p>

        </td>
      </tr>
                      <tr>
        <td id="sh_binary.srcs">
          <code>srcs</code>
        </td>
        <td>
                    <p>List of <a href="/versions/7.0.0/concepts/labels">labels</a>; required</p>
                              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>

        </td>
      </tr>
                                                                                                                                                                                        </tbody>
  </table>
  <h2 id="sh_library">
    sh_library
  </h2>

  <a class="button button-with-icon" href="https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/bazel/rules/sh/BazelShLibraryRule.java" target="_blank">
  View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span>
  </a>

  <pre class="rule-signature">sh_library(<a href="#sh_library.name">name</a>, <a href="#sh_library.deps">deps</a>, <a href="#sh_library.srcs">srcs</a>, <a href="common-definitions.html#typical.data">data</a>, <a href="common-definitions.html#common.compatible_with">compatible_with</a>, <a href="common-definitions.html#common.deprecation">deprecation</a>, <a href="common-definitions.html#common.distribs">distribs</a>, <a href="common-definitions.html#common.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_properties">exec_properties</a>, <a href="common-definitions.html#common.features">features</a>, <a href="common-definitions.html#typical.licenses">licenses</a>, <a href="common-definitions.html#common.restricted_to">restricted_to</a>, <a href="common-definitions.html#common.tags">tags</a>, <a href="common-definitions.html#common.target_compatible_with">target_compatible_with</a>, <a href="common-definitions.html#common.testonly">testonly</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre>


<p>
  The main use for this rule is to aggregate together a logical
  "library" consisting of related scripts&mdash;programs in an
  interpreted language that does not require compilation or linking,
  such as the Bourne shell&mdash;and any data those programs need at
  run-time. Such "libraries" can then be used from
  the <code>data</code> attribute of one or
  more <code>sh_binary</code> rules.
</p>

<p>
  You can use the <a href="/versions/7.0.0/reference/be/general.html#filegroup"><code>filegroup</code></a> rule to aggregate data
  files.
</p>

<p>
  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:
  <code>srcs</code>, <code>deps</code> and <code>data</code>.
  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).
</p>

<h4 id="sh_library_examples">Examples</h4>

<pre class="code">
sh_library(
    name = "foo",
    data = [
        ":foo_service_script",  # an sh_binary with srcs
        ":deploy_foo",  # another sh_binary with srcs
    ],
)
</pre>



  <h3 id="sh_library_args">Arguments</h3>
  <table class="table table-condensed table-bordered table-params">
    <colgroup>
      <col class="col-param" />
      <col class="param-description" />
    </colgroup>
    <thead>
      <tr>
        <th colspan="2">Attributes</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td id="sh_library.name"><code>name</code></td>
        <td>
          <p><a href="/versions/7.0.0/concepts/labels#target-names">Name</a>; required</p>
          <p>A unique name for this target.</p>

        </td>
      </tr>
                <tr>
        <td id="sh_library.deps">
          <code>deps</code>
        </td>
        <td>
                    <p>List of <a href="/versions/7.0.0/concepts/labels">labels</a>; default is <code>[]</code></p>
                              The list of "library" targets to be aggregated into this target.
          See general comments about <code>deps</code>
          at <a href="/versions/7.0.0/reference/be/common-definitions#typical.deps">Typical attributes defined by
          most build rules</a>.
          <p>
            This attribute should be used to list other <code>sh_library</code> rules that provide
            interpreted program source code depended on by the code in <code>srcs</code>. The files
            provided by these rules will be present among the <code>runfiles</code> of this target.
          </p>

        </td>
      </tr>
                      <tr>
        <td id="sh_library.srcs">
          <code>srcs</code>
        </td>
        <td>
                    <p>List of <a href="/versions/7.0.0/concepts/labels">labels</a>; default is <code>[]</code></p>
                            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>

        </td>
      </tr>
                                                                                                                                                </tbody>
  </table>
  <h2 id="sh_test">
    sh_test
  </h2>

  <a class="button button-with-icon" href="https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/bazel/rules/sh/BazelShTestRule.java" target="_blank">
  View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span>
  </a>

  <pre class="rule-signature">sh_test(<a href="#sh_test.name">name</a>, <a href="#sh_test.deps">deps</a>, <a href="#sh_test.srcs">srcs</a>, <a href="common-definitions.html#typical.data">data</a>, <a href="common-definitions.html#test.args">args</a>, <a href="common-definitions.html#common.compatible_with">compatible_with</a>, <a href="common-definitions.html#common.deprecation">deprecation</a>, <a href="common-definitions.html#common.distribs">distribs</a>, <a href="common-definitions.html#test.env">env</a>, <a href="common-definitions.html#test.env_inherit">env_inherit</a>, <a href="common-definitions.html#common.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_properties">exec_properties</a>, <a href="common-definitions.html#common.features">features</a>, <a href="common-definitions.html#test.flaky">flaky</a>, <a href="common-definitions.html#typical.licenses">licenses</a>, <a href="common-definitions.html#test.local">local</a>, <a href="common-definitions.html#common.restricted_to">restricted_to</a>, <a href="common-definitions.html#test.shard_count">shard_count</a>, <a href="common-definitions.html#test.size">size</a>, <a href="common-definitions.html#common.tags">tags</a>, <a href="common-definitions.html#common.target_compatible_with">target_compatible_with</a>, <a href="common-definitions.html#common.testonly">testonly</a>, <a href="common-definitions.html#test.timeout">timeout</a>, <a href="common-definitions.html#common.toolchains">toolchains</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre>


<p>A <code>sh_test()</code> rule creates a test written as a Bourne shell script.</p>

<p>See the <a href="/versions/7.0.0/reference/be/common-definitions#common-attributes-tests">
attributes common to all test rules (*_test)</a>.</p>

<h4 id="sh_test_examples">Examples</h4>

<pre class="code">
sh_test(
    name = "foo_integration_test",
    size = "small",
    srcs = ["foo_integration_test.sh"],
    deps = [":foo_sh_lib"],
    data = glob(["testdata/*.txt"]),
)
</pre>



  <h3 id="sh_test_args">Arguments</h3>
  <table class="table table-condensed table-bordered table-params">
    <colgroup>
      <col class="col-param" />
      <col class="param-description" />
    </colgroup>
    <thead>
      <tr>
        <th colspan="2">Attributes</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td id="sh_test.name"><code>name</code></td>
        <td>
          <p><a href="/versions/7.0.0/concepts/labels#target-names">Name</a>; required</p>
          <p>A unique name for this target.</p>

        </td>
      </tr>
                <tr>
        <td id="sh_test.deps">
          <code>deps</code>
        </td>
        <td>
                    <p>List of <a href="/versions/7.0.0/concepts/labels">labels</a>; default is <code>[]</code></p>
                              The list of "library" targets to be aggregated into this target.
          See general comments about <code>deps</code>
          at <a href="/versions/7.0.0/reference/be/common-definitions#typical.deps">Typical attributes defined by
          most build rules</a>.
          <p>
            This attribute should be used to list other <code>sh_library</code> rules that provide
            interpreted program source code depended on by the code in <code>srcs</code>. The files
            provided by these rules will be present among the <code>runfiles</code> of this target.
          </p>

        </td>
      </tr>
                      <tr>
        <td id="sh_test.srcs">
          <code>srcs</code>
        </td>
        <td>
                    <p>List of <a href="/versions/7.0.0/concepts/labels">labels</a>; required</p>
                              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>

        </td>
      </tr>
                                                                                                                                                                                                                                          </tbody>
  </table>

<!-- Generated footer -->

</body>
</html>