Documentation

Edit

Workspace Rules

bind

bind(name, actual, compatible_with, deprecation, distribs, features, licenses, restricted_to, tags, testonly, visibility)

Gives a target an alias in the //external package.

The //external 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.

Examples

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

bind(
    name = "javacc-latest",
    actual = "//third_party/javacc-v2",
)

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

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

bind(
    name = "openssl",
    actual = "@my-ssl//src:openssl-lib",
)

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

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

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

cc_library(
    name = "openssl-lib",
    srcs = ["openssl.cc"],
    hdrs = ["openssl.h"],
)

Then sign_in.cc's includes might look like this:

#include "sign_in.h"
#include "src/openssl.h"

Arguments

Attributes
name

Name; required

A unique name for this rule.

actual

Label; optional

The target to be aliased.

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

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

git_repository

git_repository(name, commit, init_submodules, remote, sha256, tag)

Warning: this rule has several limitations. We recommend using http_archive instead for more robust and secure performance.

git_repository has several issues:

  • Security - http_archive allows a sha256 to be specified, which ensures that the downloaded code is exactly what was expected.
  • Reliability - http_archive allows the user to specify multiple URLs to attempt downloads from. Most services have downtime occasionally, so specifying multiple remotes decreases the chances of being unable to download a dependency.
  • Speed - http_archive multiplexes downloads to get the fastest possible rate. You can also generally download a tarball that is a "shallow clone" of the repository, which decreases the size of the download.
  • Library issues - This implementation uses jGit, which we've discovered several issues with. It also lacks support for some authentication types you might use with your system git.

Many git repository hosts serve tarballs of the repository, so depend on those if possible. For GitHub, this takes the form:

http_archive(
    name = "",
    urls = ["https://github.com/<user>/<repo>/archive/<commit or tag>.tar.gz"],
)
If you are using a private repository, prefer the Skylark git repository rules, which will use your system's git install (instead of jGit). These rules are built into Bazel and have the same API as the native rules.

Clones a Git repository, checks out the specified tag, or commit, and makes its targets available for binding.

Examples

Suppose the current repository contains the source code for a chat program, rooted at the directory ~/chat-app. It needs to depend on an SSL library which is available in the remote Git repository http://example.com/openssl/openssl.git. The chat app depends on version 1.0.2 of the SSL library, which is tagged by the v1.0.2 Git tag.

This Git repository contains the following directory structure:

WORKSPACE
src/
  BUILD
  openssl.cc
  openssl.h

src/BUILD contains the following target definition:

cc_library(
    name = "openssl-lib",
    srcs = ["openssl.cc"],
    hdrs = ["openssl.h"],
)

Targets in the ~/chat-app repository can depend on this target if the following lines are added to ~/chat-app/WORKSPACE:

git_repository(
    name = "my_ssl",
    remote = "http://example.com/openssl/openssl.git",
    tag = "v1.0.2",
)

Then targets would specify @my_ssl//src:openssl-lib as a dependency.

Arguments

Attributes
name

Name; required

A unique name for this rule.

commit

String; optional

The commit hash to check out in the repository.

Note that one of either commit or tag must be defined.

init_submodules

Boolean; optional; default is 0

Whether to clone submodules in the repository.

Currently, only cloning the top-level submodules is supported

remote

String; required

The URI of the remote Git repository.

This must be a HTTP URL. There is currently no support for authentication.

sha256

String; optional

The expected SHA-256 hash of the file downloaded. Specifying this forces the repository to be downloaded as a tarball. Currently, this is only supported for public GitHub repositories.

This must match the SHA-256 hash of the file downloaded. It is a security risk to omit the SHA-256 as remote files can change. At best omitting this field will make your build non-hermetic. It is optional to make development easier but should be set before shipping.

tag

String; optional

The Git tag to check out in the repository.

Note that one of either commit or tag must be defined.

http_archive

http_archive(name, sha256, strip_prefix, type, url, urls)

Downloads a Bazel repository as a compressed archive file, decompresses it, and makes its targets available for binding. The repository should already contain a BUILD file. If it does not, use new_http_archive instead.

It supports Zip-formatted archives (with the .zip extension) and tarballs (.tar.gz and .tgz extensions).

Examples

Suppose the current repository contains the source code for a chat program, rooted at the directory ~/chat-app. It needs to depend on an SSL library which is available from http://example.com/openssl.zip. This .zip file contains the following directory structure:

WORKSPACE
src/
  BUILD
  openssl.cc
  openssl.h

src/BUILD contains the following target definition:

cc_library(
    name = "openssl-lib",
    srcs = ["openssl.cc"],
    hdrs = ["openssl.h"],
)

Targets in the ~/chat-app repository can depend on this target if the following lines are added to ~/chat-app/WORKSPACE:

http_archive(
    name = "my_ssl",
    url = "http://example.com/openssl.zip",
    sha256 = "03a58ac630e59778f328af4bcc4acb4f80208ed4",
)

Then targets would specify @my_ssl//src:openssl-lib as a dependency.

Arguments

Attributes
name

Name; required

A unique name for this rule.

sha256

String; optional

The expected SHA-256 hash of the file downloaded.

This must match the SHA-256 hash of the file downloaded. It is a security risk to omit the SHA-256 as remote files can change. At best omitting this field will make your build non-hermetic. It is optional to make development easier but should be set before shipping.

strip_prefix

String; optional

A directory prefix to strip from the extracted files.

Many archives contain a top-level directory that contains all of the useful files in archive. Instead of needing to specify this prefix over and over in the build_file, this field can be used to strip it from all of the extracted files.

For example, suppose you are using foo-lib-latest.zip, which contains the directory foo-lib-1.2.3/ under which there is a WORKSPACE file and are src/, lib/, and test/ directories that contain the actual code you wish to build. Specify strip_prefix = "foo-lib-1.2.3" to use the foo-lib-1.2.3 directory as your top-level directory.

Note that if there are files outside of this directory, they will be discarded and inaccessible (e.g., a top-level license file). This includes files/directories that start with the prefix but are not in the directory (e.g., foo-lib-1.2.3.release-notes). If the specified prefix does not match a directory in the archive, Bazel will return an error.

type

String; optional

The archive type of the downloaded file.

By default, the archive type is determined from the file extension of the URL. If the file has no extension, you can explicitly specify one of the following: `"zip"`, `"jar"`, `"war"`, `"tar.gz"`, `"tgz"`, `"tar.xz"`, and `tar.bz2`

url

String; optional

(Deprecated) A URL referencing an archive file containing a Bazel repository.

This value has the same meaning as a urls list with a single item. This must not be specified if urls is also specified.

urls

List of strings; optional

List of mirror URLs referencing the same archive file containing a Bazel repository.

This must be an http, https, or file URL. Archives of type .zip, .jar, .war, .tar.gz, .tgz, tar.bz2, or tar.xz are supported. There is no support for authentication.

http_file

http_file(name, executable, sha256, url, urls)

Downloads a file from a URL and makes it available to be used as a file group.

Examples

Suppose you need to have a debian package for your custom rules. This package is available from http://example.com/package.deb. Then you can add to your WORKSPACE file:

 http_file(
    name = "my_deb",
    url = "http://example.com/package.deb",
    sha256 = "03a58ac630e59778f328af4bcc4acb4f80208ed4",
 )
 

Targets would specify @my_deb//file as a dependency to depend on this file.

Arguments

Attributes
name

Name; required

A unique name for this rule.

executable

Boolean; optional; default is 0

If the downloaded file should be made executable. Defaults to False.
sha256

String; optional

The expected SHA-256 of the file downloaded.

This must match the SHA-256 of the file downloaded. It is a security risk to omit the SHA-256 as remote files can change. At best omitting this field will make your build non-hermetic. It is optional to make development easier but should be set before shipping.

url

String; optional

(Deprecated) A URL to a file that will be made available to Bazel.

This value has the same meaning as a urls list with a single item. This must not be specified if urls is also specified.

urls

List of strings; optional

List of mirror URLs referencing the same file that will be made available to Bazel.

This must be an http, https, or file URL. Authentication is not supported.

http_jar

http_jar(name, sha256, url)

Downloads a jar from a URL and makes it available to be used as a Java dependency.

Downloaded files must have a .jar extension.

Examples

Suppose the current repository contains the source code for a chat program, rooted at the directory ~/chat-app. It needs to depend on an SSL library which is available from http://example.com/openssl-0.2.jar.

Targets in the ~/chat-app repository can depend on this target if the following lines are added to ~/chat-app/WORKSPACE:

http_jar(
    name = "my_ssl",
    url = "http://example.com/openssl-0.2.jar",
    sha256 = "03a58ac630e59778f328af4bcc4acb4f80208ed4",
)

Targets would specify @my_ssl//jar as a dependency to depend on this jar.

Arguments

Attributes
name

Name; required

A unique name for this rule.

sha256

String; optional

The expected SHA-256 of the file downloaded.

This must match the SHA-256 of the file downloaded. It is a security risk to omit the SHA-256 as remote files can change. At best omitting this field will make your build non-hermetic. It is optional to make development easier but should be set before shipping.

url

String; required

A URL to an archive file containing a Bazel repository.

This must be an http or https URL that ends with .jar.

local_repository

local_repository(name, path)

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 bind section for more details.

Examples

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

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

local_repository(
    name = "my-ssl",
    path = "/home/user/ssl",
)

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

Arguments

Attributes
name

Name; required

A unique name for this rule.

path

String; required

The path to the local repository's directory.

This must be an absolute path to the directory containing the repository's WORKSPACE file.

maven_jar

maven_jar(name, artifact, repository, server, sha1)

Downloads a jar from Maven and makes it available to be used as a Java dependency.

Naming

Note that the maven_jar name is used as a repository name, so it is limited by the rules governing workspace names: it cannot contain dashes nor dots (see the documentation on workspace names for the exact specification). By convention, maven_jar names should match the artifact name, replacing illegal characters with underscores and leaving off the version. For example, a rule with artifact = "org.apache.commons:commons-lang3:3.4" should have name = "org_apache_commons_commons_lang3".

Examples

Suppose that the current repostory contains a java_library target that needs to depend on Guava. Using Maven, this dependency would be defined in the pom.xml file as:
<dependency>
    <groupId>com.google.guava</groupId>
    <artifactId>guava</artifactId>
    <version>18.0</version>
</dependency>
With Bazel, add the following lines to the WORKSPACE file:
maven_jar(
    name = "com_google_guava_guava",
    artifact = "com.google.guava:guava:18.0",
    sha1 = "cce0823396aa693798f8882e64213b1772032b09",
)

Targets can specify @com_google_guava_guava//jar as a dependency to depend on this jar.

Arguments

Attributes
name

Name; required

A unique name for this rule.

artifact

String; optional

A description of a Maven artifact using Maven coordinates.

These descriptions are of the form <groupId>:<artifactId>:<version>, see the documentation below for an example.

repository

String; optional

A URL for a Maven repository to fetch the jar from.

Either this or server can be specified. Defaults to Maven Central ("central.maven.org").

server

String; optional

A maven_server to use for this artifact.

Either this or repository can be specified.

sha1

String; optional

A SHA-1 hash of the desired jar.

If the downloaded jar does not match this hash, Bazel will error out. It is a security risk to omit the SHA-1 as remote files can change. At best omitting this field will make your build non-hermetic. It is optional to make development easier but should be set before shipping.

maven_server

maven_server(name, settings_file, url)

How to access a Maven repository.

This is a combination of a <repository> definition from a pom.xml file and a <server> definition from a settings.xml file.

Using maven_server

maven_jar rules can specify the name of a maven_server in their server field. For example, suppose we have the following WORKSPACE file:

maven_jar(
    name = "junit",
    artifact = "junit:junit-dep:4.10",
    server = "my_server",
)

maven_server(
    name = "my_server",
    url = "http://intranet.mycorp.net",
)
This specifies that junit should be downloaded from http://intranet.mycorp.net using the authentication information found in ~/.m2/settings.xml (specifically, the settings for the server with the id my_server).

Specifying a default server

If you create a maven_server with the name "default" it will be used for any maven_jar that does not specify a server nor repository. If there is no maven_server named default, the default will be fetching from Maven Central with no authentication enabled.

Arguments

Attributes
name

Name; required

A unique name for this rule.

settings_file

String; optional

A path to a settings.xml file. Used for testing. If unspecified, this defaults to using $M2_HOME/conf/settings.xml for the global settings and $HOME/.m2/settings.xml for the user settings.
url

String; optional

A URL for accessing the server.

For example, Maven Central (which is the default and does not need to be defined) would be specified as url = "http://central.maven.org/maven2/".

new_git_repository

new_git_repository(name, build_file, build_file_content, init_submodules, remote, sha256)

Warning: this rule has several limitations. We recommend using new_http_archive instead for more robust and secure performance.

new_git_repository has several issues:

  • Security - new_http_archive allows a sha256 to be specified, which ensures that the downloaded code is exactly what was expected.
  • Reliability - new_http_archive allows the user to specify multiple URLs to attempt downloads from. Most services have downtime occasionally, so specifying multiple remotes decreases the chances of being unable to download a dependency.
  • Speed - new_http_archive multiplexes downloads to get the fastest possible rate. You can also generally download a tarball that is a "shallow clone" of the repository, which decreases the size of the download.
  • Library issues - This implementation uses jGit, which we've discovered several issues with. It also lacks support for some authentication types you might use with your system git.

Many git repository hosts serve tarballs of the repository, so depend on those if possible. For GitHub, this takes the form:

new_http_archive(
    name = "",
    urls = ["https://github.com/<user>/<repo>/archive/<commit or tag>.tar.gz"],
    build_file = "",
)
If you are using a private repository, prefer the Skylark git repository rules, which will use your system's git install (instead of jGit). These rules are built into Bazel and have the same API as the native rules.

Clones a Git repository, checks out the specified tag, or commit, and makes its targets available for binding.

Examples

Suppose the current repository contains the source code for a chat program, rooted at the directory ~/chat-app. It needs to depend on an SSL library which is available in the remote Git repository http://example.com/openssl/openssl.git. The chat app depends on version 1.0.2 of the SSL library, which is tagged by the v1.0.2 Git tag.

This Git repository contains the following directory structure:

src/
  openssl.cc
  openssl.h

Targets in the ~/chat-app repository can depend on this target if the following lines are added to ~/chat-app/WORKSPACE:

new_git_repository(
    name = "my_ssl",
    remote = "http://example.com/openssl/openssl.git",
    tag = "v1.0.2",
    build_file_content = """
cc_library(
    name = "openssl-lib",
    srcs = ["src/openssl.cc"],
    hdrs = ["src/openssl.h"],
)""",
)

Then targets would specify @my_ssl//:openssl-lib as a dependency.

Arguments

Attributes
name

Name; required

A unique name for this rule.

build_file

String; optional

The file to use as the BUILD file for this repository.

Either build_file or build_file_content must be specified.

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.

build_file_content

String; optional

The content for the BUILD file for this repository.

Either build_file or build_file_content must be specified.

init_submodules

Boolean; optional; default is 0

Whether to clone submodules in the repository.

Currently, only cloning the top-level submodules is supported

remote

String; required

The URI of the remote Git repository.

This must be a HTTP URL. There is currently no support for authentication.

sha256

String; optional

The expected SHA-256 hash of the file downloaded. Specifying this forces the repository to be downloaded as a tarball. Currently, this is only supported for public GitHub repositories.

This must match the SHA-256 hash of the file downloaded. It is a security risk to omit the SHA-256 as remote files can change. At best omitting this field will make your build non-hermetic. It is optional to make development easier but should be set before shipping.

new_http_archive

new_http_archive(name, build_file, build_file_content, sha256, strip_prefix, type, url, urls, workspace_file, workspace_file_content)

Downloads a compressed archive file, decompresses it, and creates a Bazel repository by combining the archive with the provided BUILD file.

It supports Zip-formatted archives (with the .zip extension) and tarballs (.tar.gz and .tgz extensions).

Examples

Suppose the current repository contains the source code for a chat program, rooted at the directory ~/chat-app. It needs to depend on an SSL library which is available from http://example.com/openssl.zip. This .zip file contains the following directory structure:

src/
  openssl.cc
  openssl.h

In the local repository, the user creates a BUILD.ssl file which contains the following target definition:

cc_library(
    name = "openssl-lib",
    srcs = ["src/openssl.cc"],
    hdrs = ["src/openssl.h"],
)

Targets in the ~/chat-app repository can depend on this target if the following lines are added to ~/chat-app/WORKSPACE:

new_http_archive(
    name = "my_ssl",
    url = "http://example.com/openssl.zip",
    sha256 = "03a58ac630e59778f328af4bcc4acb4f80208ed4",
    build_file = "BUILD.ssl",
)

Targets would specify @my_ssl//:openssl-lib as a dependency to depend on this jar.

Arguments

Attributes
name

Name; required

A unique name for this rule.

build_file

String; optional

The file to use as the BUILD file for this repository.

Either build_file or build_file_content must be specified.

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.

build_file_content

String; optional

The content for the BUILD file for this repository.

Either build_file or build_file_content must be specified.

sha256

String; optional

The expected SHA-256 hash of the file downloaded.

This must match the SHA-256 hash of the file downloaded. It is a security risk to omit the SHA-256 as remote files can change. At best omitting this field will make your build non-hermetic. It is optional to make development easier but should be set before shipping.

strip_prefix

String; optional

A directory prefix to strip from the extracted files.

Many archives contain a top-level directory that contains all of the useful files in archive. Instead of needing to specify this prefix over and over in the build_file, this field can be used to strip it from all of the extracted files.

For example, suppose you are using foo-lib-latest.zip, which contains the directory foo-lib-1.2.3/ under which there are src/, lib/, and test/ directories that contain the actual code you wish to build. Specify strip_prefix = "foo-lib-1.2.3" and your build_file will not have to account for this top-level directory.

Note that if there are files outside of this directory, they will be discarded and inaccessible (e.g., a top-level license file). This includes files/directories that start with the prefix but are not in the directory (e.g., foo-lib-1.2.3.release-notes). If the specified prefix does not match a directory in the archive, Bazel will return an error.

type

String; optional

The archive type of the downloaded file.

By default, the archive type is determined from the file extension of the URL. If the file has no extension, you can explicitly specify one of the following: `"zip"`, `"jar"`, `"war"`, `"tar.gz"`, `"tgz"`, `"tar.xz"`, and `tar.bz2`

url

String; optional

(Deprecated) A URL referencing an archive file.

This value has the same meaning as a urls list with a single item. This must not be specified if urls is also specified.

urls

List of strings; optional

List of mirror URLs referencing the same archive file containing a Bazel repository.

This must be an http, https, or file URL. Archives of type .zip, .jar, .war, .tar.gz, .tgz, tar.bz2, or tar.xz are supported. There is no support for authentication.

workspace_file

String; optional

The file to use as the WORKSPACE file for this repository.

Either workspace_file or workspace_file_content can be specified, but not both.

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.

workspace_file_content

String; optional

The content for the WORKSPACE file for this repository.

Either workspace_file or workspace_file_content can be specified, but not both.

new_local_repository

new_local_repository(name, build_file, build_file_content, path)

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.

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 path.

Examples

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

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

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

Then they can add the following lines to ~/chat-app/WORKSPACE:

new_local_repository(
    name = "my-ssl",
    path = "/home/user/ssl",
    build_file = "BUILD.my-ssl",
)

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

You can also use new_local_repository 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:

new_local_repository(
    name = "piano",
    path = "/home/username/Downloads/piano.jar",
    build_file = "BUILD.piano",
)

And creating the following BUILD.piano file:

java_import(
    name = "play-music",
    jars = ["piano.jar"],
    visibility = ["//visibility:public"],
)
Then targets can depend on @piano//:play-music to use piano.jar.

Arguments

Attributes
name

Name; required

A unique name for this rule.

build_file

String; optional

A file to use as a BUILD file for this directory.

Either build_file or build_file_content must be specified.

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.

build_file_content

String; optional

The content for the BUILD file for this repository.

Either build_file or build_file_content must be specified.

path

String; required

A path on the local filesystem.

This must be an absolute path to an existing file or a directory.

xcode_config

xcode_config(name, deprecation, distribs, features, licenses, tags, testonly, visibility)

A single target of this rule can be referenced by the --xcode_config build flag to translate the --xcode_version flag into an accepted official xcode version. This allows selection of a an official xcode version from a number of registered aliases.

Arguments

Attributes
name

Name; required

A unique name for this rule.

xcode_version

xcode_version(name, default_ios_sdk_version, default_macosx_sdk_version, default_tvos_sdk_version, default_watchos_sdk_version, deprecation, distribs, features, licenses, tags, testonly, version, visibility)

Represents a single official xcode version with acceptable aliases for that xcode version. See the xcode_config rule.

Arguments

Attributes
name

Name; required

A unique name for this rule.

default_ios_sdk_version

String; optional; nonconfigurable

The ios sdk version that is used by default when this version of xcode is being used. The ios_sdk_version build flag will override the value specified here.
default_macosx_sdk_version

String; optional; nonconfigurable

The macosx sdk version that is used by default when this version of xcode is being used. The macosx_sdk_version build flag will override the value specified here.
default_tvos_sdk_version

String; optional; nonconfigurable

The tvos sdk version that is used by default when this version of xcode is being used. The tvos_sdk_version build flag will override the value specified here.
default_watchos_sdk_version

String; optional; nonconfigurable

The watchos sdk version that is used by default when this version of xcode is being used. The watchos_sdk_version build flag will override the value specified here.
version

String; required; nonconfigurable

The official version number of a version of Xcode.