ContextQMD
Back to Bazel

Workspace

docs/versions/7.5.0/reference/be/workspace.mdx

9.2.016.7 KB
Original Source
<html devsite> <head> <meta name="project_path" value="/_project.yaml"> <meta name="book_path" value="/versions/7.5.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.5.0" %} {% dynamic setvar original_path "/reference/be/workspace" %} {% include "_buttons.html" %}

<p> Workspace rules are used to pull in <a href="/versions/7.5.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.5.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.5.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.5.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.5.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.5.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.5.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.5.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.5.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.5.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.5.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>