The context of the repository rule containing helper functions and information about attributes. You get a repository_ctx object as an argument to the implementation
function when you create a repository rule.
Members
- attr
- delete
- download
- download_and_extract
- execute
- extract
- file
- getenv
- name
- os
- patch
- path
- read
- rename
- report_progress
- symlink
- template
- watch
- watch_tree
- which
- workspace_root
attr
struct repository_ctx.attr
delete
bool repository_ctx.delete(path)
Parameters
Parameter | Description |
---|---|
path
|
string; or path;
required Path of the file to delete, relative to the repository directory, or absolute. Can be a path or a string. |
download
unknown repository_ctx.download(url, output='', sha256='', executable=False, allow_fail=False, canonical_id='', auth={}, headers={}, *, integrity='', block=True)
success
, a flag which is true
if the download completed successfully, and if successful, a hash of the file with the fields sha256
and integrity
. When sha256
or integrity
is user specified, setting an explicit canonical_id
is highly recommended. e.g. get_default_canonical_id
Parameters
Parameter | Description |
---|---|
url
|
string; or Iterable of strings;
required List of mirror URLs referencing the same file. |
output
|
string; or Label; or path;
default is '' path to the output file, relative to the repository directory. |
sha256
|
string;
default is '' 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. If provided, the repository cache will first be checked for a file with the given hash; a download will only be attempted if the file was not found in the cache. After a successful download, the file will be added to the cache. |
executable
|
bool;
default is False Set the executable flag on the created file, false by default. |
allow_fail
|
bool;
default is False If set, indicate the error in the return value instead of raising an error for failed downloads. |
canonical_id
|
string;
default is '' If set, restrict cache hits to those cases where the file was added to the cache with the same canonical id. By default caching uses the checksum ( sha256 or integrity ).
|
auth
|
dict;
default is {} An optional dict specifying authentication information for some of the URLs. |
headers
|
dict;
default is {} An optional dict specifying http headers for all URLs. |
integrity
|
string;
default is '' Expected checksum of the file downloaded, in Subresource Integrity format. This must match the checksum of the file downloaded. It is a security risk to omit the checksum 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. If provided, the repository cache will first be checked for a file with the given checksum; a download will only be attempted if the file was not found in the cache. After a successful download, the file will be added to the cache. |
block
|
bool;
default is True If set to false, the call returns immediately and instead of the regular return value, it returns a token with one single method, wait(), which blocks until the download is finished and returns the usual return value or throws as usual. |
download_and_extract
struct repository_ctx.download_and_extract(url, output='', sha256='', type='', strip_prefix='', allow_fail=False, canonical_id='', auth={}, headers={}, *, integrity='', rename_files={})
success
, a flag which is true
if the download completed successfully, and if successful, a hash of the file with the fields sha256
and integrity
. When sha256
or integrity
is user specified, setting an explicit canonical_id
is highly recommended. e.g. get_default_canonical_id
Parameters
Parameter | Description |
---|---|
url
|
string; or Iterable of strings;
required List of mirror URLs referencing the same file. |
output
|
string; or Label; or path;
default is '' Path to the directory where the archive will be unpacked, relative to the repository directory. |
sha256
|
string;
default is '' 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. If provided, the repository cache will first be checked for a file with the given hash; a download will only be attempted if the file was not found in the cache. After a successful download, the file will be added to the cache. |
type
|
string;
default is '' 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 either "zip", "jar", "war", "aar", "nupkg", "tar", "tar.gz", "tgz", "tar.xz", "txz", ".tar.zst", ".tzst", "tar.bz2", ".tbz", ".ar", or ".deb" here. |
strip_prefix
|
string;
default is '' A directory prefix to strip from the extracted files. Many archives contain a top-level directory that contains all files in the archive. Instead of needing to specify this prefix over and over in the build_file , this field can
be used to strip it from extracted files.
For compatibility, this parameter may also be used under the deprecated name
|
allow_fail
|
bool;
default is False If set, indicate the error in the return value instead of raising an error for failed downloads. |
canonical_id
|
string;
default is '' If set, restrict cache hits to those cases where the file was added to the cache with the same canonical id. By default caching uses the checksum" ( sha256 or integrity ).
|
auth
|
dict;
default is {} An optional dict specifying authentication information for some of the URLs. |
headers
|
dict;
default is {} An optional dict specifying http headers for all URLs. |
integrity
|
string;
default is '' Expected checksum of the file downloaded, in Subresource Integrity format. This must match the checksum of the file downloaded. It is a security risk to omit the checksum 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. If provided, the repository cache will first be checked for a file with the given checksum; a download will only be attempted if the file was not found in the cache. After a successful download, the file will be added to the cache. |
rename_files
|
dict;
default is {} An optional dict specifying files to rename during the extraction. Archive entries with names exactly matching a key will be renamed to the value, prior to any directory prefix adjustment. This can be used to extract archives that contain non-Unicode filenames, or which have files that would extract to the same path on case-insensitive filesystems. |
execute
exec_result repository_ctx.execute(arguments, timeout=600, environment={}, quiet=True, working_directory="")
timeout
(in seconds, default 600 seconds). This method returns an exec_result
structure containing the output of the command. The environment
map can be used to override some environment variables to be passed to the process.
Parameters
Parameter | Description |
---|---|
arguments
|
sequence;
required List of arguments, the first element should be the path to the program to execute. |
timeout
|
int;
default is 600 Maximum duration of the command in seconds (default is 600 seconds). |
environment
|
dict;
default is {} Force some environment variables to be set to be passed to the process. The value can be None to remove the environment variable.
|
quiet
|
bool;
default is True If stdout and stderr should be printed to the terminal. |
working_directory
|
string;
default is "" Working directory for command execution. Can be relative to the repository root or absolute. The default is the repository root. |
extract
None
repository_ctx.extract(archive, output='', strip_prefix='', *, rename_files={}, watch_archive='auto')
Parameters
Parameter | Description |
---|---|
archive
|
string; or Label; or path;
required path to the archive that will be unpacked, relative to the repository directory. |
output
|
string; or Label; or path;
default is '' path to the directory where the archive will be unpacked, relative to the repository directory. |
strip_prefix
|
string;
default is '' a directory prefix to strip from the extracted files. Many archives contain a top-level directory that contains all files in the archive. Instead of needing to specify this prefix over and over in the build_file , this field can be
used to strip it from extracted files.
For compatibility, this parameter may also be used under the deprecated name
|
rename_files
|
dict;
default is {} An optional dict specifying files to rename during the extraction. Archive entries with names exactly matching a key will be renamed to the value, prior to any directory prefix adjustment. This can be used to extract archives that contain non-Unicode filenames, or which have files that would extract to the same path on case-insensitive filesystems. |
watch_archive
|
string;
default is 'auto' whether to watch the archive file. Can be the string 'yes', 'no', or 'auto'. Passing 'yes' is equivalent to immediately invoking the watch() method; passing 'no' does not attempt to watch the file; passing 'auto' will only attempt to watch the file when it is legal to do so (see watch() docs for more information.
|
file
None
repository_ctx.file(path, content='', executable=True, legacy_utf8=False)
Parameters
Parameter | Description |
---|---|
path
|
string; or Label; or path;
required Path of the file to create, relative to the repository directory. |
content
|
string;
default is '' The content of the file to create, empty by default. |
executable
|
bool;
default is True Set the executable flag on the created file, true by default. |
legacy_utf8
|
bool;
default is False No-op. This parameter is deprecated and will be removed in a future version of Bazel. |
getenv
string repository_ctx.getenv(name, default=None)
name
as a string if exists, or default
if it doesn't. When building incrementally, any change to the value of the variable named by name
will cause this repository to be re-fetched.
Parameters
Parameter | Description |
---|---|
name
|
string;
required Name of desired environment variable. |
default
|
string; or None ;
default is None Default value to return if name is not found.
|
None
.
name
string repository_ctx.name
os
repository_os repository_ctx.os
patch
None
repository_ctx.patch(patch_file, strip=0, *, watch_patch='auto')
Parameters
Parameter | Description |
---|---|
patch_file
|
string; or Label; or path;
required The patch file to apply, it can be label, relative path or absolute path. If it's a relative path, it will resolve to the repository directory. |
strip
|
int;
default is 0 Strip the specified number of leading components from file names. |
watch_patch
|
string;
default is 'auto' Whether to watch the patch file. Can be the string 'yes', 'no', or 'auto'. Passing 'yes' is equivalent to immediately invoking the watch() method; passing 'no' does not attempt to watch the file; passing 'auto' will only attempt to watch the file when it is legal to do so (see watch() docs for more information.
|
path
path repository_ctx.path(path)
Parameters
Parameter | Description |
---|---|
path
|
string; or Label; or path;
requiredstring , Label or path from which to create a path from.
|
read
string repository_ctx.read(path, *, watch='auto')
Parameters
Parameter | Description |
---|---|
path
|
string; or Label; or path;
required Path of the file to read from. |
watch
|
string;
default is 'auto' Whether to watch the file. Can be the string 'yes', 'no', or 'auto'. Passing 'yes' is equivalent to immediately invoking the watch() method; passing 'no' does not attempt to watch the file; passing 'auto' will only attempt to watch the file when it is legal to do so (see watch() docs for more information.
|
rename
None
repository_ctx.rename(src, dst)
src
to dst
. Parent directories are created as needed. Fails if the destination path
already exists. Both paths must be located within the repository.
Parameters
Parameter | Description |
---|---|
src
|
string; or Label; or path;
required The path of the existing file or directory to rename, relative to the repository directory. |
dst
|
string; or Label; or path;
required The new name to which the file or directory will be renamed to, relative to the repository directory. |
report_progress
None
repository_ctx.report_progress(status='')
Parameters
Parameter | Description |
---|---|
status
|
string;
default is '' string describing the current status of the fetch progress.
|
symlink
None
repository_ctx.symlink(target, link_name)
Parameters
Parameter | Description |
---|---|
target
|
string; or Label; or path;
required The path that the symlink should point to. |
link_name
|
string; or Label; or path;
required The path of the symlink to create. |
template
None
repository_ctx.template(path, template, substitutions={}, executable=True, *, watch_template='auto')
template
. Every occurrence in template
of a key of substitutions
will be replaced by the corresponding value. The result is written in path
. An optional executable
argument (default to true) can be set to turn on or off the executable bit.
Parameters
Parameter | Description |
---|---|
path
|
string; or Label; or path;
required Path of the file to create, relative to the repository directory. |
template
|
string; or Label; or path;
required Path to the template file. |
substitutions
|
dict;
default is {} Substitutions to make when expanding the template. |
executable
|
bool;
default is True Set the executable flag on the created file, true by default. |
watch_template
|
string;
default is 'auto' Whether to watch the template file. Can be the string 'yes', 'no', or 'auto'. Passing 'yes' is equivalent to immediately invoking the watch() method; passing 'no' does not attempt to watch the file; passing 'auto' will only attempt to watch the file when it is legal to do so (see watch() docs for more information.
|
watch
None
repository_ctx.watch(path)
"Changes" include changes to the contents of the file (if the path is a file); if the path was a file but is now a directory, or vice versa; and if the path starts or stops existing. Notably, this does not include changes to any files under the directory if the path is a directory. For that, use path.readdir()
instead.
Note that attempting to watch paths inside the repo currently being fetched, or inside the working directory of the current module extension, will result in an error. A module extension attempting to watch a path outside the current Bazel workspace will also result in an error.
Parameters
watch_tree
None
repository_ctx.watch_tree(path)
Note that attempting to watch paths inside the repo currently being fetched will result in an error.
Parameters
which
path repository_ctx.which(program)
path
of the corresponding program or None
if there is no such program in the path.
Parameters
Parameter | Description |
---|---|
program
|
string;
required Program to find in the path. |
None
.
workspace_root
path repository_ctx.workspace_root