README
¶
Alternative runfiles library for Go
This package contains an alternative runfiles library for
rules_go. This library follows the runfiles libraries
proposal more closely. In particular, it requires specifying a workspace
name for runfile paths, and handles the case where no runfiles-specific
environmental variables are set correctly. You can use both this library and
the official Bazel library in the same program or library; they don’t
interfere with each other.
See the Go package documentation for instructions how to use this package.
This is not an officially supported Google product.
Documentation
¶
Overview ¶
Package runfiles provides access to Bazel runfiles. It is an alternative to the official Bazel package https://pkg.go.dev/github.com/bazelbuild/rules_go/go/tools/bazel.
Installation ¶
To use this package, first set up rules_go as described in https://github.com/bazelbuild/rules_go#setup. Then add the following snippet to your Bazel WORKSPACE file:
load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
http_archive(
name = "com_github_phst_runfiles",
urls = ["https://github.com/phst/runfiles/archive/f8065aa0cb28b5cc0fffa7d0b5e9ea1a92add4bb.zip"],
sha256 = "8f0502d14cc35e8857d67ac02a3b8d46a496bb7e3ddf723ebb73ce71c4c0cd6d",
strip_prefix = "runfiles-f8065aa0cb28b5cc0fffa7d0b5e9ea1a92add4bb",
)
Usage ¶
This package has two main entry points, the global functions Path and Env, and the Runfiles type.
Global functions ¶
For simple use cases that don’t require hermetic behavior, use the Path and Env functions to access runfiles. Use Path 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 Path and Env, which correspond to the package-level functions. On Go 1.16, *Runfiles implements fs.FS, fs.StatFS, and fs.ReadFileFS.
Index ¶
Examples ¶
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 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 Path ¶
Path 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), Path returns an error that wraps ErrEmpty.
Example ¶
package main
import (
"fmt"
"os"
"github.com/phst/runfiles"
)
func main() {
path, err := runfiles.Path("com_github_phst_runfiles/test.txt")
if err != nil {
panic(err)
}
b, err := os.ReadFile(path)
if err != nil {
panic(err)
}
fmt.Println(string(b))
}
Output: hi!
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.
Example ¶
package main
import (
"os"
"os/exec"
"github.com/phst/runfiles"
)
func main() {
r, err := runfiles.New()
if err != nil {
panic(err)
}
// The binary “testprog” is itself built with Bazel, and needs
// runfiles.
prog, err := r.Path("com_github_phst_runfiles/testprog/testprog")
if err != nil {
panic(err)
}
cmd := exec.Command(prog)
// We add r.Env() after os.Environ() so that runfile environment
// variables override anything set in the process environment.
cmd.Env = append(os.Environ(), r.Env()...)
cmd.Stdout = os.Stdout
cmd.Stderr = os.Stderr
if err := cmd.Run(); err != nil {
panic(err)
}
}
Output: hi!
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.
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) Path ¶
Path 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 r is the zero Runfiles object, Path always returns an error. If the runfiles manifest maps s to an empty name (indicating an empty runfile not present in the filesystem), Path returns an error that wraps ErrEmpty.
Source Files
Directories