<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">Workspace 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/workspace" %}
{% include "_buttons.html" %}


<p>
Workspace rules are used to pull in <a href="/versions/7.0.0/docs/external">external dependencies</a>, typically
source code located outside the main repository.
</p>

<p><em>Note:</em> besides the native workspace rules, Bazel also embeds various
<a href="/versions/7.0.0/rules/lib/repo/index">Starlark workspace rules</a>, in particular those to deal
with git repositories or archives hosted on the web.
</p>



<h2>Rules</h2>
<ul>
  <li>
    <a href="#bind">
      bind    </a>
  </li>
  <li>
    <a href="#local_repository">
      local_repository    </a>
  </li>
  <li>
    <a href="#new_local_repository">
      new_local_repository    </a>
  </li>
</ul>

  <h2 id="bind">
    bind
  </h2>

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

  <pre class="rule-signature">bind(<a href="#bind.name">name</a>, <a href="#bind.actual">actual</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.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><em>Warning: use of <code>bind()</code> is not recommended. See "<a
href="https://github.com/bazelbuild/bazel/issues/1952">Consider removing bind</a>" for a long
discussion of its issues and alternatives. In particular, consider the use of
<a href="https://bazel.build/versions/7.0.0/rules/repository_rules#attributes"><code>repo_mapping</code>
repository attributes</a>.</em></p>

<p><em>Warning: <code>select()</code> cannot be used in <code>bind()</code>. See the <a
href="/versions/7.0.0/docs/configurable-attributes#bind-select">Configurable Attributes FAQ</a> for
details.</em></p>

<p>Gives a target an alias in the <code>//external</code> package.</p>

<p>The <code>//external</code> package is not a "normal" package: there is no external/ directory,
  so it can be thought of as a "virtual package" that contains all bound targets.</p>

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

<p>To give a target an alias, <code>bind</code> it in the <i>WORKSPACE</i> file.  For example,
  suppose there is a <code>java_library</code> target called
  <code>//third_party/javacc-v2</code>.  This can be aliased by adding the following to the
  <i>WORKSPACE</i> file:</p>

<pre class="code">
bind(
    name = "javacc-latest",
    actual = "//third_party/javacc-v2",
)
</pre>

<p>Now targets can depend on <code>//external:javacc-latest</code> instead of
  <code>//third_party/javacc-v2</code>. If javacc-v3 is released, the <code>bind</code> rule can be
  updated and all of the BUILD files depending on <code>//external:javacc-latest</code> will now
  depend on javacc-v3 without needing to be edited.</p>

<p>Bind can also be used to make targets in external repositories available to your workspace.
  For example, if there is a remote repository named <code>@my-ssl</code> imported in the
  <i>WORKSPACE</i> file and it has a cc_library target <code>//src:openssl-lib</code>, you can
  create an alias for this target using <code>bind</code>:</p>

<pre class="code">
bind(
    name = "openssl",
    actual = "@my-ssl//src:openssl-lib",
)
</pre>

<p>Then, in a BUILD file in your workspace, the bound target can be used as follows:</p>

<pre class="code">
cc_library(
    name = "sign-in",
    srcs = ["sign_in.cc"],
    hdrs = ["sign_in.h"],
    deps = ["//external:openssl"],
)
</pre>

<p>Within <code>sign_in.cc</code> and <code>sign_in.h</code>, the header files exposed by
  <code>//external:openssl</code> can be referred to using their path relative to their repository
  root.  For example, if the rule definition for <code>@my-ssl//src:openssl-lib</code> looks like
  this:</p>

<pre class="code">
cc_library(
    name = "openssl-lib",
    srcs = ["openssl.cc"],
    hdrs = ["openssl.h"],
)
</pre>

<p>Then <code>sign_in.cc</code>'s includes might look like this:</p>

<pre class="code">
#include "sign_in.h"
#include "src/openssl.h"
</pre>



  <h3 id="bind_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="bind.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="bind.actual">
          <code>actual</code>
        </td>
        <td>
                    <p><a href="/versions/7.0.0/concepts/labels">Label</a>; default is <code>None</code></p>
                            The target to be aliased.

        <p>This target must exist, but can be any type of rule (including bind).</p>

        <p>If this attribute is omitted, rules referring to this target in <code>//external</code>
        will simply not see this dependency edge. Note that this is different from omitting the
        <code>bind</code> rule completely: it is an error if an <code>//external</code> dependency
        does not have an associated <code>bind</code> rule.
        </p>

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

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

  <pre class="rule-signature">local_repository(<a href="#local_repository.name">name</a>, <a href="#local_repository.path">path</a>, <a href="#local_repository.repo_mapping">repo_mapping</a>)</pre>


<p>Allows targets from a local directory to be bound. This means that the current repository can
  use targets defined in this other directory. See the <a href="/versions/7.0.0/reference/be/workspace.html#bind_examples">bind
  section</a> for more details.</p>

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

<p>Suppose the current repository is a chat client, rooted at the directory <i>~/chat-app</i>. It
  would like to use an SSL library which is defined in a different repository: <i>~/ssl</i>.  The
  SSL library has a target <code>//src:openssl-lib</code>.</p>

<p>The user can add a dependency on this target by adding the following lines to
  <i>~/chat-app/WORKSPACE</i>:</p>

<pre class="code">
local_repository(
    name = "my-ssl",
    path = "/home/user/ssl",
)
</pre>

<p>Targets would specify <code>@my-ssl//src:openssl-lib</code> as a dependency to depend on this
library.</p>



  <h3 id="local_repository_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="local_repository.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="local_repository.path">
          <code>path</code>
        </td>
        <td>
                    <p>String; required</p>
                            The path to the local repository's directory.

        <p>This must be a path to the directory containing the repository's
        <i>WORKSPACE</i> file. The path can be either absolute or relative to the main repository's
        <i>WORKSPACE</i> file.</p>

        </td>
      </tr>
                      <tr>
        <td id="local_repository.repo_mapping">
          <code>repo_mapping</code>
        </td>
        <td>
                    <p>Dictionary: String -> String; default is <code>{}</code></p>
                            A dictionary from local repository name to global repository name. This allows controls over
        workspace dependency resolution for dependencies of this repository.

        <p>For example, an entry <code>"@foo": "@bar"</code> declares that, for any time this
        repository depends on <code>"@foo"</code> (such as a dependency on
        <code>"@foo//some:target"</code>), it should actually resolve that dependency within
        globally-declared <code>"@bar"</code> (<code>"@bar//some:target"</code>).

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

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

  <pre class="rule-signature">new_local_repository(<a href="#new_local_repository.name">name</a>, <a href="#new_local_repository.build_file">build_file</a>, <a href="#new_local_repository.build_file_content">build_file_content</a>, <a href="#new_local_repository.path">path</a>, <a href="#new_local_repository.repo_mapping">repo_mapping</a>, <a href="#new_local_repository.workspace_file">workspace_file</a>, <a href="#new_local_repository.workspace_file_content">workspace_file_content</a>)</pre>


<p>Allows a local directory to be turned into a Bazel repository. This means that the current
  repository can define and use targets from anywhere on the filesystem.</p>

<p>This rule creates a Bazel repository by creating a WORKSPACE file and subdirectory containing
symlinks to the BUILD file and path given.  The build file should create targets relative to the
<code>path</code>. For directories that already contain a WORKSPACE file and a BUILD file, the
<a href="#local_repository"><code>local_repository</code></a> rule can be used.

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

<p>Suppose the current repository is a chat client, rooted at the directory <i>~/chat-app</i>. It
  would like to use an SSL library which is defined in a different directory: <i>~/ssl</i>.</p>

<p>The user can add a dependency by creating a BUILD file for the SSL library
(~/chat-app/BUILD.my-ssl) containing:

<pre class="code">
java_library(
    name = "openssl",
    srcs = glob(['*.java'])
    visibility = ["//visibility:public"],
)
</pre>

<p>Then they can add the following lines to <i>~/chat-app/WORKSPACE</i>:</p>

<pre class="code">
new_local_repository(
    name = "my-ssl",
    path = "/home/user/ssl",
    build_file = "BUILD.my-ssl",
)
</pre>

<p>This will create a <code>@my-ssl</code> repository that symlinks to <i>/home/user/ssl</i>.
Targets can depend on this library by adding <code>@my-ssl//:openssl</code> to a target's
dependencies.</p>

<p>You can also use <code>new_local_repository</code> to include single files, not just
directories. For example, suppose you had a jar file at /home/username/Downloads/piano.jar. You
could add just that file to your build by adding the following to your WORKSPACE file:

<pre class="code">
new_local_repository(
    name = "piano",
    path = "/home/username/Downloads/piano.jar",
    build_file = "BUILD.piano",
)
</pre>

<p>And creating the following BUILD.piano file:</p>

<pre class="code">
java_import(
    name = "play-music",
    jars = ["piano.jar"],
    visibility = ["//visibility:public"],
)
</pre>

Then targets can depend on <code>@piano//:play-music</code> to use piano.jar.



  <h3 id="new_local_repository_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="new_local_repository.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="new_local_repository.build_file">
          <code>build_file</code>
        </td>
        <td>
                    <p><a href="/versions/7.0.0/concepts/labels#target-names">Name</a>; default is <code>None</code></p>
                            A file to use as a BUILD file for this directory.

        <p>Either build_file or build_file_content must be specified.</p>

        <p>This attribute is a label relative to the main workspace. The file does not need to be
        named BUILD, but can be. (Something like BUILD.new-repo-name may work well for
        distinguishing it from the repository's actual BUILD files.)</p>

        </td>
      </tr>
                      <tr>
        <td id="new_local_repository.build_file_content">
          <code>build_file_content</code>
        </td>
        <td>
                    <p>String; default is <code>""</code></p>
                            The content for the BUILD file for this repository.

        <p>Either build_file or build_file_content must be specified.</p>

        </td>
      </tr>
                      <tr>
        <td id="new_local_repository.path">
          <code>path</code>
        </td>
        <td>
                    <p>String; required</p>
                            A path on the local filesystem.

        <p>This can be either absolute or relative to the main repository's WORKSPACE file.</p>

        </td>
      </tr>
                      <tr>
        <td id="new_local_repository.repo_mapping">
          <code>repo_mapping</code>
        </td>
        <td>
                    <p>Dictionary: String -> String; default is <code>{}</code></p>
                            A dictionary from local repository name to global repository name. This allows controls over
        workspace dependency resolution for dependencies of this repository.

        <p>For example, an entry <code>"@foo": "@bar"</code> declares that, for any time this
        repository depends on <code>"@foo"</code> (such as a dependency on
        <code>"@foo//some:target"</code>), it should actually resolve that dependency within
        globally-declared <code>"@bar"</code> (<code>"@bar//some:target"</code>).

        </td>
      </tr>
                      <tr>
        <td id="new_local_repository.workspace_file">
          <code>workspace_file</code>
        </td>
        <td>
                    <p><a href="/versions/7.0.0/concepts/labels#target-names">Name</a>; default is <code>None</code></p>
                            The file to use as the WORKSPACE file for this repository.

         <p>Either workspace_file or workspace_file_content can be specified, but not both.</p>

         <p>This attribute is a label relative to the main workspace. The file does not need to be
        named WORKSPACE, but can be. (Something like WORKSPACE.new-repo-name may work well for
        distinguishing it from the repository's actual WORKSPACE files.)</p>

        </td>
      </tr>
                      <tr>
        <td id="new_local_repository.workspace_file_content">
          <code>workspace_file_content</code>
        </td>
        <td>
                    <p>String; default is <code>""</code></p>
                            The content for the WORKSPACE file for this repository.

         <p>Either workspace_file or workspace_file_content can be specified, but not both.</p>

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

<!-- Generated footer -->

</body>
</html>
