Extensions > API reference > repository_ctx

repository_ctx

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

struct repository_ctx.attr

A struct to access the values of the attributes. The values are provided by the user (if not, a default value is used).

delete

bool repository_ctx.delete(path)

Deletes a file or a directory. Returns a bool, indicating whether the file or directory was actually deleted by this call.

Parameters

Parameter Description
path

string; or path

Path of the file to delete, relative to the repository directory, or absolute. Can be a path or a string.

download

struct repository_ctx.download(url, output='', sha256='', executable=False, allow_fail=False, canonical_id='', auth={}, *, integrity='')

Downloads a file to the output path for the provided url and returns a struct containing a hash of the file with the fields sha256 and integrity.

Parameters

Parameter Description
url

string; or Iterable of strings

List of mirror URLs referencing the same file.
output

string; or Label; or path

path to the output file, relative to the repository directory.
sha256

string

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

bool

set the executable flag on the created file, false by default.
allow_fail

bool

If set, indicate the error in the return value instead of raising an error for failed downloads
canonical_id

string

If set, restrict cache hits to those cases where the file was added to the cache with the same canonical id
auth

dict

An optional dict specifying authentication information for some of the URLs.
integrity

string

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.

download_and_extract

struct repository_ctx.download_and_extract(url, output='', sha256='', type='', stripPrefix='', allow_fail=False, canonical_id='', auth={}, *, integrity='')

Downloads a file to the output path for the provided url, extracts it, and returns a struct containing a hash of the downloaded file with the fields sha256 and integrity.

Parameters

Parameter Description
url

string; or Iterable of strings

List of mirror URLs referencing the same file.
output

string; or Label; or path

path to the directory where the archive will be unpacked, relative to the repository directory.
sha256

string

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

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", "tar.gz", "tgz", "tar.bz2", or "tar.xz" here.
stripPrefix

string

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

bool

If set, indicate the error in the return value instead of raising an error for failed downloads
canonical_id

string

If set, restrict cache hits to those cases where the file was added to the cache with the same canonical id
auth

dict

An optional dict specifying authentication information for some of the URLs.
integrity

string

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.

execute

exec_result repository_ctx.execute(arguments, timeout=600, environment={}, quiet=True, working_directory="")

Executes the command given by the list of arguments. The execution time of the command is limited by 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

List of arguments, the first element should be the path to the program to execute.
timeout

int

maximum duration of the command in seconds (default is 600 seconds).
environment

dict

force some environment variables to be set to be passed to the process.
quiet

bool

If stdout and stderr should be printed to the terminal.
working_directory

string

Working directory for command execution. Can be relative to the repository root or absolute.

extract

None repository_ctx.extract(archive, output='', stripPrefix='')

Extract an archive to the repository directory.

Parameters

Parameter Description
archive

string; or Label; or path

path to the archive that will be unpacked, relative to the repository directory.
output

string; or Label; or path

path to the directory where the archive will be unpacked, relative to the repository directory.
stripPrefix

string

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.

file

None repository_ctx.file(path, content='', executable=True, legacy_utf8=True)

Generates a file in the repository directory with the provided content.

Parameters

Parameter Description
path

string; or Label; or path

path of the file to create, relative to the repository directory.
content

string

the content of the file to create, empty by default.
executable

bool

set the executable flag on the created file, true by default.
legacy_utf8

bool

encode file content to UTF-8, true by default. Future versions will change the default and remove this parameter.

name

string repository_ctx.name

The name of the external repository created by this rule.

os

repository_os repository_ctx.os

A struct to access information from the system.

patch

None repository_ctx.patch(patch_file, strip=0)

Apply a patch file to the root directory of external repository. The patch file should be a standard unified diff format file. The Bazel-native patch implementation doesn't support fuzz match and binary patch like the patch command line tool.

Parameters

Parameter Description
patch_file

string; or Label; or path

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

strip the specified number of leading components from file names.

path

path repository_ctx.path(path)

Returns a path from a string, label or path. If the path is relative, it will resolve relative to the repository directory. If the path is a label, it will resolve to the path of the corresponding file. Note that remote repositories are executed during the analysis phase and thus cannot depends on a target result (the label should point to a non-generated file). If path is a path, it will return that path as is.

Parameters

Parameter Description
path

string; or Label; or path

string, label or path from which to create a path from

read

string repository_ctx.read(path)

Reads the content of a file on the filesystem.

Parameters

Parameter Description
path

string; or Label; or path

path of the file to read from.

report_progress

None repository_ctx.report_progress(status)

Updates the progress status for the fetching of this repository

Parameters

Parameter Description
status

string

string describing the current status of the fetch progress

 

None repository_ctx.symlink(from, to)

Creates a symlink on the filesystem.

Parameters

Parameter Description
from

string; or Label; or path

path to which the created symlink should point to.
to

string; or Label; or path

path of the symlink to create, relative to the repository directory.

template

None repository_ctx.template(path, template, substitutions={}, executable=True)

Generates a new file using a template. Every occurrence in template of a key of substitutions will be replaced by the corresponding value. The result is written in path. An optionalexecutable argument (default to true) can be set to turn on or offthe executable bit.

Parameters

Parameter Description
path

string; or Label; or path

path of the file to create, relative to the repository directory.
template

string; or Label; or path

path to the template file.
substitutions

dict

substitutions to make when expanding the template.
executable

bool

set the executable flag on the created file, true by default.

which

path repository_ctx.which(program)

Returns the path of the corresponding program or None if there is no such program in the path.

Parameters

Parameter Description
program

string

Program to find in the path.
May return None.