runfiles

README

Alternative runfiles library for Go

This package is deprecated. Users should switch to the official runfiles library.

This is not an officially supported Google product.

Documentation

Overview

Package runfiles provides access to Bazel runfiles.

Deprecated: use https://pkg.go.dev/github.com/bazelbuild/rules_go/go/runfiles instead.

Index

• Variables
• func Env() ([]string, error)
• func Path(s string) (string, error)
• type Directory
• type Error
• type ManifestFile
• type Option
• type ProgramName
• type Runfiles
  • func New(opts ...Option) (*Runfiles, error)
  • func (r *Runfiles) Path(s string) (string, error)

Examples

• Path
• Runfiles

Variables

var ErrEmpty = runfiles.ErrEmpty

ErrEmpty indicates that a runfile isn’t present in the filesystem, but should be created as an empty file if necessary.

Deprecated: use https://pkg.go.dev/github.com/bazelbuild/rules_go/go/runfiles#ErrEmpty instead.

Functions

func Env

func Env() ([]string, error)

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.

Deprecated: use https://pkg.go.dev/github.com/bazelbuild/rules_go/go/runfiles#Env instead.

func Path

func Path(s string) (string, error)

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.

Deprecated: use https://pkg.go.dev/github.com/bazelbuild/rules_go/go/runfiles#Rlocation instead.

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 = runfiles.Directory

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.

Deprecated: use https://pkg.go.dev/github.com/bazelbuild/rules_go/go/runfiles#Directory instead.

type Error

type Error = runfiles.Error

Error represents a failure to look up a runfile.

Deprecated: use https://pkg.go.dev/github.com/bazelbuild/rules_go/go/runfiles#Error instead.

type ManifestFile

type ManifestFile = runfiles.ManifestFile

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.

Deprecated: use https://pkg.go.dev/github.com/bazelbuild/rules_go/go/runfiles#ManifestFile instead.

type Option

type Option = runfiles.Option

Option is an option for the New function to override runfiles discovery.

Deprecated: use https://pkg.go.dev/github.com/bazelbuild/rules_go/go/runfiles#Option instead.

type ProgramName

type ProgramName = runfiles.ProgramName

ProgramName is an Option that sets the program name. If not set, New uses os.Args[0].

Deprecated: use https://pkg.go.dev/github.com/bazelbuild/rules_go/go/runfiles#ProgramName instead.

type Runfiles

type Runfiles struct{ runfiles.Runfiles }

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.

Deprecated: use https://pkg.go.dev/github.com/bazelbuild/rules_go/go/runfiles#Runfiles instead.

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

func New(opts ...Option) (*Runfiles, error)

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.

Deprecated: use https://pkg.go.dev/github.com/bazelbuild/rules_go/go/runfiles#New instead.

func (*Runfiles) Path

func (r *Runfiles) Path(s string) (string, error)

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.

Deprecated: use https://pkg.go.dev/github.com/bazelbuild/rules_go/go/runfiles#Runfiles.Rlocation instead.