Documentation
¶
Overview ¶
Package runfiles provides access to Bazel runfiles.
Usage ¶
This package has two main entry points, the global functions Rlocation and Env, and the Runfiles type.
Global functions ¶
For simple use cases that don’t require hermetic behavior, use the Rlocation and Env functions to access runfiles. Use Rlocation to find the filesystem location of a runfile, and use Env to obtain environmental variables to pass on to subprocesses.
Runfiles type ¶
If you need hermetic behavior or want to change the runfiles discovery process, use New to create a Runfiles object. New accepts a few options to change the discovery process. Runfiles objects have methods Rlocation and Env, which correspond to the package-level functions. On Go 1.16, *Runfiles implements fs.FS, fs.StatFS, and fs.ReadFileFS.
Index ¶
- Variables
- func CallerRepository() string
- func CurrentRepository() string
- func Env() ([]string, error)
- func Rlocation(path string) (string, error)
- func RlocationFrom(path string, sourceRepo string) (string, error)
- type Directory
- type Error
- type ManifestFile
- type Option
- type ProgramName
- type Runfiles
- type SourceRepo
Constants ¶
This section is empty.
Variables ¶
var ErrEmpty = errors.New("empty runfile")
ErrEmpty indicates that a runfile isn’t present in the filesystem, but should be created as an empty file if necessary.
Functions ¶
func CallerRepository ¶ added in v0.37.0
func CallerRepository() string
CallerRepository returns the canonical name of the Bazel repository that contains the source file of the caller of the function that itself calls CallerRepository.
func CurrentRepository ¶ added in v0.37.0
func CurrentRepository() string
CurrentRepository returns the canonical name of the Bazel repository that contains the source file of the caller of CurrentRepository.
func Env ¶
Env returns additional environmental variables to pass to subprocesses. Each element is of the form “key=value”. Pass these variables to Bazel-built binaries so they can find their runfiles as well. See the Runfiles example for an illustration of this.
The return value is a newly-allocated slice; you can modify it at will.
func Rlocation ¶
Rlocation returns the absolute path name of a runfile. The runfile name must be a relative path, using the slash (not backslash) as directory separator. If the runfiles manifest maps s to an empty name (indicating an empty runfile not present in the filesystem), Rlocation returns an error that wraps ErrEmpty.
Types ¶
type Directory ¶
type Directory string
Directory specifies the location of the runfiles directory. You can pass this as an option to New. If unset or empty, use the value of the environmental variable RUNFILES_DIR.
type Error ¶
type Error struct {
// Runfile name that caused the failure.
Name string
// Underlying error.
Err error
}
Error represents a failure to look up a runfile.
type ManifestFile ¶
type ManifestFile string
ManifestFile specifies the location of the runfile manifest file. You can pass this as an option to New. If unset or empty, use the value of the environmental variable RUNFILES_MANIFEST_FILE.
type Option ¶
type Option interface {
// contains filtered or unexported methods
}
Option is an option for the New function to override runfiles discovery.
type ProgramName ¶
type ProgramName string
ProgramName is an Option that sets the program name. If not set, New uses os.Args[0].
type Runfiles ¶
type Runfiles struct {
// contains filtered or unexported fields
}
Runfiles allows access to Bazel runfiles. Use New to create Runfiles objects; the zero Runfiles object always returns errors. See https://docs.bazel.build/skylark/rules.html#runfiles for some information on Bazel runfiles.
func New ¶
New creates a given Runfiles object. By default, it uses os.Args and the RUNFILES_MANIFEST_FILE and RUNFILES_DIR environmental variables to find the runfiles location. This can be overwritten by passing some options.
See section “Runfiles discovery” in https://docs.google.com/document/d/e/2PACX-1vSDIrFnFvEYhKsCMdGdD40wZRBX3m3aZ5HhVj4CtHPmiXKDCxioTUbYsDydjKtFDAzER5eg7OjJWs3V/pub.
The returned object implements fs.FS regardless of the type of runfiles that backs it. This is the preferred way to interact with runfiles in a platform-agnostic way. For example, to find all runfiles beneath a directory, use fs.Glob or fs.WalkDir.
func (*Runfiles) Env ¶
Env returns additional environmental variables to pass to subprocesses. Each element is of the form “key=value”. Pass these variables to Bazel-built binaries so they can find their runfiles as well. See the Runfiles example for an illustration of this.
The return value is a newly-allocated slice; you can modify it at will. If r is the zero Runfiles object, the return value is nil.
func (*Runfiles) Open ¶
Open implements fs.FS for a Runfiles instance.
Rlocation-style paths are supported with both apparent and canonical repo names. The root directory of the filesystem (".") additionally lists the apparent repo names that are visible to the current source repo (with --enable_bzlmod).
func (*Runfiles) Rlocation ¶
Rlocation returns the (relative or absolute) path name of a runfile. The runfile name must be a runfile-root relative path, using the slash (not backslash) as directory separator. It is typically of the form "repo/path/to/pkg/file".
If r is the zero Runfiles object, Rlocation always returns an error. If the runfiles manifest maps s to an empty name (indicating an empty runfile not present in the filesystem), Rlocation returns an error that wraps ErrEmpty.
See section “Library interface” in https://docs.google.com/document/d/e/2PACX-1vSDIrFnFvEYhKsCMdGdD40wZRBX3m3aZ5HhVj4CtHPmiXKDCxioTUbYsDydjKtFDAzER5eg7OjJWs3V/pub.
func (*Runfiles) WithSourceRepo ¶ added in v0.37.0
WithSourceRepo returns a Runfiles instance identical to the current one, except that it uses the given repository's repository mapping when resolving runfiles paths.
type SourceRepo ¶ added in v0.37.0
type SourceRepo string
SourceRepo is an Option that sets the canonical name of the repository whose repository mapping should be used to resolve runfiles paths. If not set, New uses the repository containing the source file from which New is called. Use CurrentRepository to get the name of the current repository.
Source Files