http_archive
An http_archive()
rule is used to download and extract archives from the Internet to be used as dependencies for other rules. These rules are downloaded by running fetch
, or can be downloaded as part of build
by setting .buckconfig
Function Signature
def http_archive(
*,
name: str,
default_target_platform: None | str = None,
target_compatible_with: list[str] = [],
compatible_with: list[str] = [],
exec_compatible_with: list[str] = [],
visibility: list[str] = [],
within_view: list[str] = ["PUBLIC"],
metadata: OpaqueMetadata = {},
tests: list[str] = [],
modifiers: OpaqueMetadata = [],
_apple_platforms: dict[str, str] = {},
contacts: list[str] = [],
default_host_platform: None | str = None,
excludes: list[str] = [],
exec_deps: str = "prelude//http_archive/tools:exec_deps",
labels: list[str] = [],
licenses: list[str] = [],
out: None | str = None,
sha1: None | str = None,
sha256: None | str = None,
size_bytes: None | int = None,
strip_prefix: None | str = None,
sub_targets: list[str] | dict[str, list[str]] = [],
type: None | str = None,
urls: list[str] = [],
vpnless_urls: list[str] = [],
) -> None
Parameters
-
name
: (required)name of the target
-
default_target_platform
: (defaults to:None
)specifies the default target platform, used when no platforms are specified on the command line
-
target_compatible_with
: (defaults to:[]
)a list of constraints that are required to be satisfied for this target to be compatible with a configuration
-
compatible_with
: (defaults to:[]
)a list of constraints that are required to be satisfied for this target to be compatible with a configuration
-
exec_compatible_with
: (defaults to:[]
)a list of constraints that are required to be satisfied for this target to be compatible with an execution platform
-
visibility
: (defaults to:[]
)a list of visibility patterns restricting what targets can depend on this one
-
within_view
: (defaults to:["PUBLIC"]
)a list of visibility patterns restricting what this target can depend on
-
metadata
: (defaults to:{}
)a key-value map of metadata associated with this target
-
tests
: (defaults to:[]
)a list of targets that provide tests for this one
-
modifiers
: (defaults to:[]
)an array of modifiers associated with this target
-
excludes
: (defaults to:[]
)An optional list of regex patterns. All file paths in the extracted archive which match any of the given patterns will be omitted.
-
exec_deps
: (defaults to:"prelude//http_archive/tools:exec_deps"
)When using http_archive as an anon target, the rule invoking the anon target needs to mirror this attribute into its own attributes, and forward the provider into the anon target invocation.
When using http_archive normally not as an anon target, the default value is always fine.
-
out
: (defaults to:None
)An optional name to call the directory that the downloaded artifact is extracted into. Buck will generate a default name if one is not provided that uses the
name
of the rule. -
sha256
: (defaults to:None
)The
SHA-256
hash of the downloaded artifact. Buck verifies this is correct and fails the fetch command if it doesn't match in order to guarantee repeatable builds. -
strip_prefix
: (defaults to:None
)If set, files under this path will be extracted to the root of the output directory. Siblings or cousins to this prefix will not be extracted at all.
For example, if a tarball has the layout:
- foo/bar/bar-0.1.2/data.dat
- foo/baz/baz-0.2.3
- foo_prime/bar-0.1.2
Only
data.dat
will be extracted, and it will be extracted into the output directory specified inout
. -
sub_targets
: (defaults to:[]
)A list of filepaths within the archive to be made accessible as sub-targets. For example if we have an http_archive with
name = "archive"
andsub_targets = ["src/lib.rs"]
, then other targets would be able to refer to that file as":archive[src/lib.rs]"
.Or, a dict of sub_target name to list of files to be in that subtarget. For example, with
http_archive(
name = "archive",
...
sub_targets = {
"group_1": ["a.txt", "b.txt"],
"a.txt": ["a.txt"]
},
)... you get two sub targets:
:archive[group_1]
consisting of two files, and:archive[a.txt]
consisting of one file. -
type
: (defaults to:None
)Normally, archive type is determined by the file's extension. If
type
is set, then autodetection is overridden, and the specified type is used instead.Supported values are:
zip
,tar
,tar.gz
,tar.bz2
,tar.xz
, andtar.zst
. -
urls
: (defaults to:[]
)A list of urls to attempt to download from. They are tried in order, and subsequent ones are only tried if the download fails. If validation fails, a new URL is not used. Supported protocols are "http", "https", and "mvn".
-
vpnless_urls
: (defaults to:[]
)Additional URLs from which this resource can be downloaded when off VPN. Meta-internal only.
Examples
Using http_archive()
, third party packages can be downloaded from
an https
URL and used in other library types.
http_archive(
name = 'thrift-archive',
urls = [
'https://internal-mirror.example.com/bin/thrift-compiler-0.1.tar.gz.badextension',
],
sha256 = '7baa80df284117e5b945b19b98d367a85ea7b7801bd358ff657946c3bd1b6596',
type='tar.gz',
strip_prefix='thrift-compiler-0.1'
)
genrule(
name = 'thrift-compiler-bin',
out = 'thrift',
cmd = 'cp $(location :thrift-archive)/bin/thrift $OUT',
executable = True,
)
genrule(
name="my-thrift-lib-cpp2",
cmd="$(exe :thrift-compiler-bin) --gen cpp2 -o $OUT $(location //:thrift-file)",
out="gen-cpp2",
)