The following functions can be loaded from
@bazel_tools//tools/build_defs/repo:http.bzl.
http_archive
http_archive(name, build_file, build_file_content, canonical_id, netrc, patch_args, patch_cmds, patch_cmds_win, patch_tool, patches, sha256, strip_prefix, type, url, urls, workspace_file, workspace_file_content)
Downloads a Bazel repository as a compressed archive file, decompresses it, and makes its targets available for binding.
It supports the following file extensions: "zip", "jar", "war", "tar",
"tar.gz", "tgz", "tar.xz", and tar.bz2.
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/
openssl.cc
openssl.h
In the local repository, the user creates a openssl.BUILD 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:
load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
http_archive(
name = "my_ssl",
urls = ["http://example.com/openssl.zip"],
sha256 = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
build_file = "@//:openssl.BUILD",
)
Then targets would specify @my_ssl//:openssl-lib as a dependency.
Attributes
name |
Name; required
A unique name for this repository. |
build_file |
Label; optional
The file to use as the BUILD file for this repository.This attribute is an absolute label (use '@//' for the main repo). 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. Either build_file or build_file_content can be specified, but not both. |
build_file_content |
String; optional
The content for the BUILD file for this repository. Either build_file or build_file_content can be specified, but not both. |
canonical_id |
String; optional
A canonical id of the archive downloaded. If specified and non-empty, bazel will not take the archive from cache, unless it was added to the cache by a request with the same canonical id. |
netrc |
String; optional
Location of the .netrc file to use for authentication |
patch_args |
List of strings; optional
The arguments given to the patch tool. Defaults to -p0, however -p1 will usually be needed for patches generated by git. If multiple -p arguments are specified, the last one will take effect.If arguments other than -p are specified, Bazel will fall back to use patch command line tool instead of the Bazel-native patch implementation. When falling back to patch command line tool and patch_tool attribute is not specified, `patch` will be used. |
patch_cmds |
List of strings; optional
Sequence of Bash commands to be applied on Linux/Macos after patches are applied. |
patch_cmds_win |
List of strings; optional
Sequence of Powershell commands to be applied on Windows after patches are applied. If this attribute is not set, patch_cmds will be executed on Windows, which requires Bash binary to exist. |
patch_tool |
String; optional
The patch(1) utility to use. If this is specified, Bazel will use the specifed patch tool instead of the Bazel-native patch implementation. |
patches |
List of labels; optional
A list of files that are to be applied as patches after extracting the archive. By default, it uses the Bazel-native patch implementation which doesn't support fuzz match and binary patch, but Bazel will fall back to use patch command line tool if `patch_tool` attribute is specified or there are arguments other than `-p` in `patch_args` attribute. |
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. |
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"`, `"tar.gz"`, `"tgz"`, `"tar.xz"`, or `tar.bz2`. |
url |
String; optional
A URL to a file that will be made available to Bazel. This must be a file, http or https URL. Redirections are followed. Authentication is not supported. This parameter is to simplify the transition from the native http_archive rule. More flexibility can be achieved by the urls parameter that allows to specify alternative URLs to fetch from. |
urls |
List of strings; optional
A list of URLs to a file that will be made available to Bazel. Each entry must be a file, http or https URL. Redirections are followed. Authentication is not supported. |
workspace_file |
Label; optional
The file to use as the `WORKSPACE` file for this repository. Either `workspace_file` or `workspace_file_content` can be specified, or neither, but not both. |
workspace_file_content |
String; optional
The content for the WORKSPACE file for this repository. Either `workspace_file` or `workspace_file_content` can be specified, or neither, but not both. |
http_file
http_file(name, canonical_id, downloaded_file_path, executable, netrc, sha256, 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:
load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_file")
http_file(
name = "my_deb",
urls = ["http://example.com/package.deb"],
sha256 = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
)
Targets would specify @my_deb//file as a dependency to depend on this file.
Attributes
name |
Name; required
A unique name for this repository. |
canonical_id |
String; optional
A canonical id of the archive downloaded. If specified and non-empty, bazel will not take the archive from cache, unless it was added to the cache by a request with the same canonical id. |
downloaded_file_path |
String; optional
Path assigned to the file downloaded |
executable |
Boolean; optional
If the downloaded file should be made executable. |
netrc |
String; optional
Location of the .netrc file to use for authentication |
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. |
urls |
List of strings; required
A list of URLs to a file that will be made available to Bazel. Each entry must be a file, http or https URL. Redirections are followed. Authentication is not supported. |
http_jar
http_jar(name, canonical_id, netrc, sha256, url, urls)
Downloads a jar from a URL and makes it available as java_import
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:
load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_jar")
http_jar(
name = "my_ssl",
url = "http://example.com/openssl-0.2.jar",
sha256 = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
)
Targets would specify <code>@my_ssl//jar</code> as a dependency to depend on this jar.
You may also reference files on the current system (localhost) by using “file:///path/to/file”
if you are on Unix-based systems. If you’re on Windows, use “file:///c:/path/to/file”. In both
examples, note the three slashes (/) – the first two slashes belong to file:// and the third
one belongs to the absolute path to the file.
Attributes
name |
Name; required
A unique name for this repository. |
canonical_id |
String; optional
A canonical id of the archive downloaded. If specified and non-empty, bazel will not take the archive from cache, unless it was added to the cache by a request with the same canonical id. |
netrc |
String; optional
Location of the .netrc file to use for authentication |
sha256 |
String; optional
The expected SHA-256 of the file downloaded. |
url |
String; optional
The URL to fetch the jar from. It must end in `.jar`. |
urls |
List of strings; optional
A list of URLS the jar can be fetched from. They have to end in `.jar`. |