core

package
v13.2.0-beta3+incompat... Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 13, 2018 License: Apache-2.0 Imports: 33 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	ContainerImplementationNone   = "none"
	ContainerImplementationDocker = "docker"
)

The available container implementations that we support.

View Source 
const (
	Kill            TaskType = 0x0000 | 0
	SubincludeBuild          = 0x1000 | 1
	SubincludeParse          = 0x2000 | 2
	Build                    = 0x4000 | 3
	Parse                    = 0x4000 | 4
	Test                     = 0x4000 | 5
	Stop                     = 0x8000 | 6
)

The values here are fiddled to make Compare work easily. Essentially we prioritise on the higher bits only and use the lower ones to make the values unique. Subinclude tasks order first, but we're happy for all build / parse / test tasks to be treated equivalently.

View Source 
const ArchConfigFileName string = ".plzconfig_" + OsArch

ArchConfigFileName is the architecture-specific config file which overrides the repo one. Also normally checked in if needed.

View Source 
const BinDir string = "plz-out/bin"

BinDir is the output directory for binary targets.

View Source 
const ConfigFileName string = ".plzconfig"

ConfigFileName is the file name for the typical repo config - this is normally checked in

View Source 
const DefaultBuildingDescription = "Building..."

DefaultBuildingDescription is the default description for targets when they're building.

View Source 
const DirPermissions = os.ModeDir | 0775

DirPermissions are the default permission bits we apply to directories.

View Source 
const GenDir string = "plz-out/gen"

GenDir is the output directory for non-binary targets.

View Source 
const GithubAPILocation = "https://api.github.com/repos/thought-machine/please"

GithubAPILocation is as above, but for the API endpoints.

View Source 
const GithubDownloadLocation = "https://github.com/thought-machine/please"

GithubDownloadLocation is plz's Github repo, which will become the default download location in future.

View Source 
const LocalConfigFileName string = ".plzconfig.local"

LocalConfigFileName is the file name for the local repo config - this is not normally checked in and used to override settings on the local machine.

View Source 
const MachineConfigFileName = "/etc/plzconfig"

MachineConfigFileName is the file name for the machine-level config - can use this to override things for a particular machine (eg. build machine with different caching behaviour).

View Source 
const OsArch = runtime.GOOS + "_" + runtime.GOARCH

OsArch is the os/arch pair, like linux_amd64 etc.

View Source 
const OutDir string = "plz-out"

OutDir is the root output directory for everything.

View Source 
const TmpDir string = "plz-out/tmp"

TmpDir is the root of the temporary directory for building targets & running tests.

View Source 
const UserConfigFileName = "~/.please/plzconfig"

UserConfigFileName is the file name for user-specific config (for all their repos).

Variables

View Source 
var BuildLabelStdin = BuildLabel{PackageName: "", Name: "_STDIN"}

BuildLabelStdin is used to indicate that we're going to consume build labels from stdin.

View Source 
var ExpandHomePath func(string) string = fs.ExpandHomePath

ExpandHomePath is an alias to the function in fs for compatibility.

View Source 
var OriginalTarget = BuildLabel{PackageName: "", Name: "_ORIGINAL"}

OriginalTarget is used to indicate one of the originally requested targets on the command line.

View Source 
var PleaseVersion = *semver.New("1.0.9999")

PleaseVersion is the current version of Please. Note that non-bootstrap builds replace this interim version with a real one.

View Source 
var RepoRoot string

RepoRoot is the root of the Please repository

View Source 
var WholeGraph = []BuildLabel{{PackageName: "", Name: "..."}}

WholeGraph represents parsing the entire graph (i.e. //...). We use this specially in one or two places.

Functions

func AcquireRepoLock 

func AcquireRepoLock()

AcquireRepoLock opens the lock file and acquires the lock. Dies if the lock cannot be successfully acquired.

func AsyncDeleteDir 

func AsyncDeleteDir(dir string) error

AsyncDeleteDir deletes a directory asynchronously. First it renames the directory to something temporary and then forks to delete it. The rename is done synchronously but the actual deletion is async (after fork) so you don't have to wait for large directories to be removed. Conversely there is obviously no guarantee about at what point it will actually cease to be on disk any more.

func CollapseHash 

func CollapseHash(key []byte) []byte

CollapseHash combines our usual four-part hash into one by XOR'ing them together. This helps keep things short in places where sometimes we get complaints about filenames being too long (this is most noticeable on e.g. Ubuntu with an encrypted home directory, but not an entire encrypted disk) and where we don't especially care about breaking out the individual parts of hashes, which is important for many parts of the system.

func ExecCommand 

func ExecCommand(command string, args ...string) *exec.Cmd

ExecCommand executes an external command. We set Pdeathsig to try to make sure commands don't outlive us if we die.

func ExecWithTimeout 

func ExecWithTimeout(target *BuildTarget, dir string, env []string, timeout time.Duration, defaultTimeout cli.Duration, showOutput, attachStdStreams bool, argv []string, msg string) ([]byte, []byte, error)

ExecWithTimeout runs an external command with a timeout. If the command times out the returned error will be a context.DeadlineExceeded error. If showOutput is true then output will be printed to stderr as well as returned. It returns the stdout only, combined stdout and stderr and any error that occurred.

func ExecWithTimeoutShell 

func ExecWithTimeoutShell(state *BuildState, target *BuildTarget, dir string, env []string, timeout time.Duration, defaultTimeout cli.Duration, showOutput bool, cmd string, sandbox bool) ([]byte, []byte, error)

ExecWithTimeoutShell runs an external command within a Bash shell. Other arguments are as ExecWithTimeout. Note that the command is deliberately a single string.

func ExecWithTimeoutShellStdStreams 

func ExecWithTimeoutShellStdStreams(state *BuildState, target *BuildTarget, dir string, env []string, timeout time.Duration, defaultTimeout cli.Duration, showOutput bool, cmd string, sandbox, attachStdStreams bool, msg string) ([]byte, []byte, error)

ExecWithTimeoutShellStdStreams is as ExecWithTimeoutShell but optionally attaches stdin to the subprocess.

func ExecWithTimeoutSimple 

func ExecWithTimeoutSimple(timeout cli.Duration, cmd ...string) ([]byte, error)

ExecWithTimeoutSimple runs an external command with a timeout. It's a simpler version of ExecWithTimeout that gives less control.

func FindRepoRoot 

func FindRepoRoot() bool

FindRepoRoot returns the root directory of the current repo and sets the initial working dir. It returns true if the repo root was found.

func IterInputPaths 

func IterInputPaths(graph *BuildGraph, target *BuildTarget) <-chan string

IterInputPaths yields all the transitive input files for a rule (sources & data files), similar to above (again).

func IterRuntimeFiles 

func IterRuntimeFiles(graph *BuildGraph, target *BuildTarget, absoluteOuts bool) <-chan SourcePair

IterRuntimeFiles yields all the runtime files for a rule (outputs & data files), similar to above.

func IterSources 

func IterSources(graph *BuildGraph, target *BuildTarget) <-chan SourcePair

IterSources returns all the sources for a function, allowing for sources that are other rules and rules that require transitive dependencies. Yielded values are pairs of the original source location and its temporary location for this rule.

func KillProcess 

func KillProcess(cmd *exec.Cmd)

KillProcess kills a process, attempting to send it a SIGTERM first followed by a SIGKILL shortly after if it hasn't exited.

func LogProgress 

func LogProgress(ctx context.Context, target *BuildTarget, msg string)

LogProgress logs a message once a minute until the given context has expired. Used to provide some notion of progress while waiting for external commands.

func LookPath 

func LookPath(filename string, paths []string) (string, error)

LookPath does roughly the same as exec.LookPath, i.e. looks for the named file on the path. The main difference is that it looks based on our config which isn't necessarily the same as the external environment variable.

func LooksLikeABuildLabel 

func LooksLikeABuildLabel(str string) bool

LooksLikeABuildLabel returns true if the string appears to be a build label, false if not. Useful for cases like rule sources where sources can be a filename or a label.

func MustFindRepoRoot 

func MustFindRepoRoot() string

MustFindRepoRoot returns the root directory of the current repo and sets the initial working dir. It dies on failure, although will fall back to looking for a Bazel WORKSPACE file first.

func PathExists 

func PathExists(filename string) bool

PathExists is an alias to fs.PathExists. TODO(peterebden): Remove and migrate everything over.

func PrepareSource 

func PrepareSource(sourcePath string, tmpPath string) error

PrepareSource symlinks a single source file for a build rule.

func PrepareSourcePair 

func PrepareSourcePair(pair SourcePair) error

PrepareSourcePair prepares a source file for a build.

func ReadLastOperationOrDie 

func ReadLastOperationOrDie() []string

ReadLastOperationOrDie reads the last operation performed from the lock file. Dies if unsuccessful.

func ReleaseRepoLock 

func ReleaseRepoLock()

ReleaseRepoLock releases the lock and closes the file handle. Does not die on errors, at this point it wouldn't really do any good.

func StartedAtRepoRoot 

func StartedAtRepoRoot() bool

StartedAtRepoRoot returns true if the build was initiated from the repo root. Used to provide slightly nicer output in some places.

func TestCoverageString 

func TestCoverageString(lines []LineCoverage) string

TestCoverageString produces a string representation of coverage for serialising to file so we don't expose the internal enum values (ordering is important so we may want to insert new ones later). This format happens to be the same as the one Phabricator uses, which is mildly useful to us since we want to integrate with it anyway. See https://secure.phabricator.com/book/phabricator/article/arcanist_coverage/ for more detail of how it works.

Types

type Alias 

type Alias struct {
	Cmd              string   `help:"Command to run for this alias."`
	Desc             string   `help:"Description of this alias"`
	Subcommand       []string `help:"Known subcommands of this command"`
	Flag             []string `help:"Known flags of this command"`
	PositionalLabels bool     `help:"Treats positional arguments after commands as build labels for the purpose of tab completion."`
}

An Alias represents aliases in the config.

type BuildEnv 

type BuildEnv []string

A BuildEnv is a representation of the build environment that also knows how to log itself.

func BuildEnvironment 

func BuildEnvironment(state *BuildState, target *BuildTarget) BuildEnv

BuildEnvironment creates the shell env vars to be passed into the exec.Command calls made by plz. Note that we lie about the location of HOME in order to keep some tools happy. We read this as being slightly more POSIX-compliant than not having it set at all...

func GeneralBuildEnvironment 

func GeneralBuildEnvironment(config *Configuration) BuildEnv

GeneralBuildEnvironment creates the shell env vars used for a command, not based on any specific target etc.

func StampedBuildEnvironment 

func StampedBuildEnvironment(state *BuildState, target *BuildTarget, stamp []byte) BuildEnv

StampedBuildEnvironment returns the shell env vars to be passed into exec.Command. Optionally includes a stamp if the target is marked as such.

func TestEnvironment 

func TestEnvironment(state *BuildState, target *BuildTarget, testDir string) BuildEnv

TestEnvironment creates the environment variables for a test.

func (BuildEnv) Redacted 

func (env BuildEnv) Redacted() interface{}

Redacted implements the interface for our logging implementation.

func (BuildEnv) Replace 

func (env BuildEnv) Replace(key, value string)

Replace replaces the value of the given variable in this BuildEnv.

func (BuildEnv) ReplaceEnvironment 

func (env BuildEnv) ReplaceEnvironment(s string) string

ReplaceEnvironment is a function suitable for passing to os.Expand to replace environment variables from this BuildEnv.

func (BuildEnv) String 

func (env BuildEnv) String() string

String implements the fmt.Stringer interface

type BuildGraph 

type BuildGraph struct {
	// contains filtered or unexported fields
}

A BuildGraph contains all the loaded targets and packages and maintains their relationships, especially reverse dependencies which are calculated here. It also arbitrates access to a lot of things via its builtin mutex which is probably our most overused lock :(

func NewGraph 

func NewGraph() *BuildGraph

NewGraph constructs and returns a new BuildGraph. Users should not attempt to construct one themselves.

func (*BuildGraph) AddDependency 

func (graph *BuildGraph) AddDependency(from BuildLabel, to BuildLabel)

AddDependency adds a dependency between two build targets. The 'to' target doesn't necessarily have to exist in the graph yet (but 'from' must).

func (*BuildGraph) AddPackage 

func (graph *BuildGraph) AddPackage(pkg *Package)

AddPackage adds a new package to the graph with given name.

func (*BuildGraph) AddSubrepo 

func (graph *BuildGraph) AddSubrepo(subrepo *Subrepo)

AddSubrepo adds a new subrepo to the graph. It dies if one is already registered by this name.

func (*BuildGraph) AddTarget 

func (graph *BuildGraph) AddTarget(target *BuildTarget) *BuildTarget

AddTarget adds a new target to the graph.

func (*BuildGraph) AllDependenciesResolved 

func (graph *BuildGraph) AllDependenciesResolved(target *BuildTarget) bool

AllDependenciesResolved returns true once all the dependencies of a target have been parsed and resolved to real targets.

func (*BuildGraph) AllDepsBuilt 

func (graph *BuildGraph) AllDepsBuilt(target *BuildTarget) bool

AllDepsBuilt returns true if all the dependencies of a target are built.

func (*BuildGraph) AllTargets 

func (graph *BuildGraph) AllTargets() BuildTargets

AllTargets returns a consistently ordered slice of all the targets in the graph.

func (*BuildGraph) DependentTargets 

func (graph *BuildGraph) DependentTargets(from, to BuildLabel) []BuildLabel

DependentTargets returns the labels that 'from' should actually depend on when it declared a dependency on 'to'. This is normally just 'to' but could be otherwise given require/provide shenanigans.

func (*BuildGraph) Len 

func (graph *BuildGraph) Len() int

Len returns the number of targets currently in the graph.

func (*BuildGraph) MaybeAddSubrepo 

func (graph *BuildGraph) MaybeAddSubrepo(subrepo *Subrepo) *Subrepo

MaybeAddSubrepo adds the given subrepo to the graph, or returns the existing one if one is already registered.

func (*BuildGraph) Package 

func (graph *BuildGraph) Package(name, subrepo string) *Package

Package retrieves a package from the graph by name & subrepo, or nil if it can't be found.

func (*BuildGraph) PackageByLabel 

func (graph *BuildGraph) PackageByLabel(label BuildLabel) *Package

PackageByLabel retrieves a package from the graph using the appropriate parts of the given label. The Name entry is ignored.

func (*BuildGraph) PackageMap 

func (graph *BuildGraph) PackageMap() map[string]*Package

PackageMap returns a copy of the graph's internal map of name to package.

func (*BuildGraph) PackageOrDie 

func (graph *BuildGraph) PackageOrDie(label BuildLabel) *Package

PackageOrDie retrieves a package by label, and dies if it can't be found.

func (*BuildGraph) ReverseDependencies 

func (graph *BuildGraph) ReverseDependencies(target *BuildTarget) []*BuildTarget

ReverseDependencies returns the set of revdeps on the given target.

func (*BuildGraph) Subrepo 

func (graph *BuildGraph) Subrepo(name string) *Subrepo

Subrepo returns the subrepo with this name. It returns nil if one isn't registered.

func (*BuildGraph) SubrepoOrDie 

func (graph *BuildGraph) SubrepoOrDie(name string) *Subrepo

SubrepoOrDie returns the subrepo with this name, dying if it doesn't exist.

func (*BuildGraph) Target 

func (graph *BuildGraph) Target(label BuildLabel) *BuildTarget

Target retrieves a target from the graph by label

func (*BuildGraph) TargetOrDie 

func (graph *BuildGraph) TargetOrDie(label BuildLabel) *BuildTarget

TargetOrDie retrieves a target from the graph by label. Dies if the target doesn't exist.

type BuildInput 

type BuildInput interface {
	// Paths returns a slice of paths to the files of this input.
	Paths(graph *BuildGraph) []string
	// FullPaths is like Paths but includes the leading plz-out/gen directory.
	FullPaths(graph *BuildGraph) []string
	// LocalPaths returns paths within the local package
	LocalPaths(graph *BuildGraph) []string
	// Label returns the build label associated with this input, or nil if it doesn't have one (eg. it's just a file).
	Label() *BuildLabel

	// String returns a string representation of this input
	String() string
	// contains filtered or unexported methods
}

A BuildInput represents some kind of input to a build rule. They can be implemented as either a file (in the local package or on the system) or another build rule.

func MustParseNamedOutputLabel 

func MustParseNamedOutputLabel(target string, pkg *Package) BuildInput

MustParseNamedOutputLabel attempts to parse a build output label. It's allowed to just be a normal build label as well. The syntax is an extension of normal build labels: //package:target|output

type BuildLabel 

type BuildLabel struct {
	PackageName string
	Name        string
	Subrepo     string
}

A BuildLabel is a representation of an identifier of a build target, e.g. //spam/eggs:ham corresponds to BuildLabel{PackageName: spam/eggs name: ham} BuildLabels are always absolute, so relative identifiers like :ham are always parsed into an absolute form. There is also implicit expansion of the final element of a target (ala Blaze) so //spam/eggs is equivalent to //spam/eggs:eggs

It can also be in a subrepo, in which case the syntax is @subrepo//spam/eggs:ham.

func FindOwningPackage 

func FindOwningPackage(state *BuildState, file string) BuildLabel

FindOwningPackage returns a build label identifying the package that owns a given file.

func FindOwningPackages 

func FindOwningPackages(state *BuildState, files []string) []BuildLabel

FindOwningPackages returns build labels corresponding to the packages that own each of the given files.

func InitialPackage 

func InitialPackage() []BuildLabel

InitialPackage returns a label corresponding to the initial package we started in.

func NewBuildLabel 

func NewBuildLabel(pkgName, name string) BuildLabel

NewBuildLabel constructs a new build label from the given components. Panics on failure.

func ParseBuildLabel 

func ParseBuildLabel(target, currentPath string) BuildLabel

ParseBuildLabel parses a single build label from a string. Panics on failure.

func ParseBuildLabelContext 

func ParseBuildLabelContext(target string, pkg *Package) BuildLabel

ParseBuildLabelContext parses a build label in the context of a package. It panics on error.

func ParseBuildLabels 

func ParseBuildLabels(targets []string) []BuildLabel

ParseBuildLabels parses a bunch of build labels from strings. It dies on failure. Relative labels are allowed since this is generally used at initialisation.

func TryNewBuildLabel 

func TryNewBuildLabel(pkgName, name string) (BuildLabel, error)

TryNewBuildLabel constructs a new build label from the given components.

func TryParseBuildLabel 

func TryParseBuildLabel(target, currentPath string) (BuildLabel, error)

TryParseBuildLabel attempts to parse a single build label from a string. Returns an error if unsuccessful.

func (BuildLabel) Complete 

func (label BuildLabel) Complete(match string) []flags.Completion

Complete implements the flags.Completer interface, which is used for shell completion. Unfortunately it's rather awkward to handle here; we need to do a proper parse in order to find out what the possible build labels are, and we're not ready for that yet. Returning to main is also awkward since the flags haven't parsed properly; all in all it seems an easier (albeit inelegant) solution to start things over by re-execing ourselves.

func (BuildLabel) FullPaths 

func (label BuildLabel) FullPaths(graph *BuildGraph) []string

FullPaths is an implementation of BuildInput interface.

func (BuildLabel) HasParent 

func (label BuildLabel) HasParent() bool

HasParent returns true if the build label has a parent that's not itself.

func (BuildLabel) Includes 

func (label BuildLabel) Includes(that BuildLabel) bool

Includes returns true if label includes the other label (//pkg:target1 is covered by //pkg:all etc).

func (BuildLabel) IsAllSubpackages 

func (label BuildLabel) IsAllSubpackages() bool

IsAllSubpackages returns true if the label ends in ..., ie. it includes all subpackages.

func (BuildLabel) IsAllTargets 

func (label BuildLabel) IsAllTargets() bool

IsAllTargets returns true if the label is the pseudo-label referring to all targets in this package.

func (BuildLabel) IsEmpty 

func (label BuildLabel) IsEmpty() bool

IsEmpty returns true if this is an empty build label, i.e. nothing's populated it yet.

func (BuildLabel) Label 

func (label BuildLabel) Label() *BuildLabel

Label is an implementation of BuildInput interface. It always returns this label.

func (BuildLabel) Less 

func (label BuildLabel) Less(other BuildLabel) bool

Less returns true if this build label would sort less than another one.

func (BuildLabel) LocalPaths 

func (label BuildLabel) LocalPaths(graph *BuildGraph) []string

LocalPaths is an implementation of BuildInput interface.

func (BuildLabel) PackageDir 

func (label BuildLabel) PackageDir() string

PackageDir returns a path to the directory this target is in. This is equivalent to PackageName in all cases except when at the repo root, when this will return . instead. This is often easier to use in build rules.

func (BuildLabel) Parent 

func (label BuildLabel) Parent() BuildLabel

Parent returns what would be the parent of a build label, or the label itself if it's parentless. Note that there is not a concrete guarantee that the returned label exists in the build graph, and that the label returned is the ultimate ancestor (ie. not necessarily immediate parent).

func (BuildLabel) Paths 

func (label BuildLabel) Paths(graph *BuildGraph) []string

Paths is an implementation of BuildInput interface; we use build labels directly as inputs.

func (BuildLabel) String 

func (label BuildLabel) String() string

String returns a string representation of this build label.

func (BuildLabel) SubrepoLabel 

func (label BuildLabel) SubrepoLabel() BuildLabel

SubrepoLabel returns a build label corresponding to the subrepo part of this build label.

func (*BuildLabel) UnmarshalFlag 

func (label *BuildLabel) UnmarshalFlag(value string) error

UnmarshalFlag unmarshals a build label from a command line flag. Implementation of flags.Unmarshaler interface.

func (*BuildLabel) UnmarshalText 

func (label *BuildLabel) UnmarshalText(text []byte) error

UnmarshalText implements the encoding.TextUnmarshaler interface. This is used by gcfg to unmarshal the config files.

type BuildLabels 

type BuildLabels []BuildLabel

BuildLabels makes slices of build labels sortable.

func (BuildLabels) Len 

func (slice BuildLabels) Len() int

func (BuildLabels) Less 

func (slice BuildLabels) Less(i, j int) bool

func (BuildLabels) Swap 

func (slice BuildLabels) Swap(i, j int)

type BuildResult 

type BuildResult struct {
	// Thread id (or goroutine id, really) that generated this result.
	ThreadID int
	// Timestamp of this event
	Time time.Time
	// Target which has just changed
	Label BuildLabel
	// Its current status
	Status BuildResultStatus
	// Error, only populated for failure statuses
	Err error
	// Description of what's going on right now.
	Description string
	// Test results
	Tests TestSuite
}

A BuildResult represents a single event in the build process, i.e. a target starting or finishing building, or reaching some milestone within those steps.

type BuildResultStatus 

type BuildResultStatus int

A BuildResultStatus represents the status of a target when we log a build result. 

const (
	PackageParsing BuildResultStatus = iota
	PackageParsed
	ParseFailed
	TargetBuilding
	TargetBuildStopped
	TargetBuilt
	TargetCached
	TargetBuildFailed
	TargetTesting
	TargetTestStopped
	TargetTested
	TargetTestFailed
)

The collection of expected build result statuses.

func (BuildResultStatus) Category 

func (s BuildResultStatus) Category() string

Category returns the broad area that this event represents in the tasks we perform for a target.

type BuildState 

type BuildState struct {
	Graph *BuildGraph

	// Stream of results from the build
	Results chan *BuildResult
	// Stream of results pushed to remote clients.
	// Will be nil until server is initialised.
	RemoteResults chan *BuildResult
	// Last results for each thread. These are used to catch up remote clients quickly.
	LastResults []*BuildResult
	// Timestamp that the build is considered to start at.
	StartTime time.Time
	// Various system statistics. Mostly used during remote communication.
	Stats *SystemStats
	// Configuration options
	Config *Configuration
	// Parser implementation. Other things can call this to perform various external parse tasks.
	Parser Parser
	// Worker pool for the parser
	ParsePool Pool
	// Hashes of variouts bits of the configuration, used for incrementality.
	Hashes struct {
		// Hash of the general config, not including specialised bits.
		Config []byte
		// Hash of the config relating to containerisation for tests.
		Containerisation []byte
	}
	// Tracks file hashes during the build.
	PathHasher *fs.PathHasher
	// Level of verbosity during the build
	Verbosity int
	// Cache to store / retrieve old build results.
	Cache Cache
	// Targets that we were originally requested to build
	OriginalTargets []BuildLabel
	// Arguments to tests.
	TestArgs []string
	// Labels of targets that we will include / exclude
	Include, Exclude []string
	// Actual targets to exclude from discovery
	ExcludeTargets []BuildLabel
	// True if we require rule hashes to be correctly verified (usually the case).
	VerifyHashes bool
	// Aggregated coverage for this run
	Coverage TestCoverage
	// True if tests should calculate coverage metrics
	NeedCoverage bool
	// True if we intend to build targets. False if we're just parsing
	// (although some may be built if they're needed for parse).
	NeedBuild bool
	// True if we're running tests. False if we're only building or parsing.
	NeedTests bool
	// True if we want to calculate target hashes (ie. 'plz hash').
	NeedHashesOnly bool
	// True if we only want to prepare build directories (ie. 'plz build --prepare')
	PrepareOnly bool
	// True if we're going to run a shell after builds are prepared.
	PrepareShell bool
	// Number of times to run each test target. 1 == once each, plus flakes if necessary.
	NumTestRuns int
	// True to clean working directories after successful builds.
	CleanWorkdirs bool
	// True if we're forcing a rebuild of the original targets.
	ForceRebuild bool
	// True to always show test output, even on success.
	ShowTestOutput bool
	// True to print all output of all tasks to stderr.
	ShowAllOutput bool
	// True to attach a debugger on test failure.
	DebugTests bool
	// contains filtered or unexported fields
}

A BuildState tracks the current state of the build & related data. As well as tracking the build graph and config, it also tracks the set of current tasks and maintains a queue of them, along with various related counters which are used to determine when we're finished. Tasks are internally tracked by priority, which is determined by their type.

func NewBuildState 

func NewBuildState(numThreads int, cache Cache, verbosity int, config *Configuration) *BuildState

NewBuildState constructs and returns a new BuildState. Everyone should use this rather than attempting to construct it themselves; callers can't initialise all the required private fields.

func NewDefaultBuildState 

func NewDefaultBuildState() *BuildState

NewDefaultBuildState creates a BuildState for the default configuration. This is useful for tests etc that don't need to customise anything about it.

func (*BuildState) AddActiveTarget 

func (state *BuildState) AddActiveTarget()

AddActiveTarget increments the counter for a newly active build target.

func (*BuildState) AddOriginalTarget 

func (state *BuildState) AddOriginalTarget(label BuildLabel, addToList bool)

AddOriginalTarget adds one of the original targets and enqueues it for parsing / building.

func (*BuildState) AddPendingBuild 

func (state *BuildState) AddPendingBuild(label BuildLabel, forSubinclude bool)

AddPendingBuild adds a task for a pending build of a target.

func (*BuildState) AddPendingParse 

func (state *BuildState) AddPendingParse(label, dependor BuildLabel, forSubinclude bool)

AddPendingParse adds a task for a pending parse of a build label.

func (*BuildState) AddPendingTest 

func (state *BuildState) AddPendingTest(label BuildLabel)

AddPendingTest adds a task for a pending test of a target.

func (*BuildState) DelayedKillAll 

func (state *BuildState) DelayedKillAll()

DelayedKillAll waits until no workers are running

func (*BuildState) ExpandOriginalLabels 

func (state *BuildState) ExpandOriginalLabels() BuildLabels

ExpandOriginalLabels expands any pseudo-labels (ie. :all, ... has already been resolved to a bunch :all targets) from the set of original labels.

func (*BuildState) ExpandOriginalTargets 

func (state *BuildState) ExpandOriginalTargets() BuildLabels

ExpandOriginalTargets expands any pseudo-targets (ie. :all, ... has already been resolved to a bunch :all targets) from the set of original targets. Deprecated: Callers should use ExpandOriginalLabels instead.

func (*BuildState) ExpandVisibleOriginalTargets 

func (state *BuildState) ExpandVisibleOriginalTargets() BuildLabels

ExpandVisibleOriginalTargets expands any pseudo-targets (ie. :all, ... has already been resolved to a bunch :all targets) from the set of original targets. Hidden targets are not included.

func (*BuildState) ForArch 

func (state *BuildState) ForArch(arch cli.Arch) *BuildState

ForArch creates a copy of this BuildState for a different architecture.

func (*BuildState) ForTarget 

func (state *BuildState) ForTarget(target *BuildTarget) *BuildState

ForTarget returns the state associated with a given target. This differs if the target is in a subrepo for a different architecture.

func (*BuildState) IsOriginalTarget 

func (state *BuildState) IsOriginalTarget(label BuildLabel) bool

IsOriginalTarget returns true if a target is an original target, ie. one specified on the command line.

func (*BuildState) Kill 

func (state *BuildState) Kill(n int)

Kill adds n kill tasks to the list of pending tasks, which stops n workers before they do anything else.

func (*BuildState) KillAll 

func (state *BuildState) KillAll()

KillAll kills all the workers.

func (*BuildState) LogBuildError 

func (state *BuildState) LogBuildError(tid int, label BuildLabel, status BuildResultStatus, err error, format string, args ...interface{})

LogBuildError logs a failure for a target to parse, build or test.

func (*BuildState) LogBuildResult 

func (state *BuildState) LogBuildResult(tid int, label BuildLabel, status BuildResultStatus, description string)

LogBuildResult logs the result of a target either building or parsing.

func (*BuildState) LogTestResult 

func (state *BuildState) LogTestResult(tid int, label BuildLabel, status BuildResultStatus, results *TestSuite, coverage *TestCoverage, err error, format string, args ...interface{})

LogTestResult logs the result of a target once its tests have completed.

func (*BuildState) NextTask 

func (state *BuildState) NextTask() (BuildLabel, BuildLabel, TaskType)

NextTask receives the next task that should be processed according to the priority queues.

func (*BuildState) NumActive 

func (state *BuildState) NumActive() int

NumActive returns the number of currently active tasks (i.e. those that are scheduled to be built at some point, or have been built already).

func (*BuildState) NumDone 

func (state *BuildState) NumDone() int

NumDone returns the number of tasks that have been completed so far.

func (*BuildState) SetIncludeAndExclude 

func (state *BuildState) SetIncludeAndExclude(include, exclude []string)

SetIncludeAndExclude sets the include / exclude labels. Handles build labels on Exclude so should be preferred over setting them directly.

func (*BuildState) SetTaskNumbers 

func (state *BuildState) SetTaskNumbers(active, done int64)

SetTaskNumbers allows a caller to set the number of active and done tasks. This may drastically confuse matters if used incorrectly.

func (*BuildState) ShouldInclude 

func (state *BuildState) ShouldInclude(target *BuildTarget) bool

ShouldInclude returns true if the given target is included by the include/exclude flags.

func (*BuildState) Stop 

func (state *BuildState) Stop(n int)

Stop adds n stop tasks to the list of pending tasks, which stops n workers after all their other tasks are done.

func (*BuildState) TaskDone 

func (state *BuildState) TaskDone(wasBuildOrTest bool)

TaskDone indicates that a single task is finished. Should be called after one is finished with a task returned from NextTask(), or from a call to ExtraTask().

func (*BuildState) WaitForBuiltTarget 

func (state *BuildState) WaitForBuiltTarget(l, dependor BuildLabel) *BuildTarget

WaitForBuiltTarget blocks until the given label is available as a build target and has been successfully built.

func (*BuildState) WaitForPackage 

func (state *BuildState) WaitForPackage(label BuildLabel) *Package

WaitForPackage either returns the given package which is already parsed and available, or returns nil if nothing's parsed it already, in which case everything else calling this will wait for the caller to parse it themselves.

type BuildTarget 

type BuildTarget struct {

	// Identifier of this build target
	Label BuildLabel `name:"name"`
	// If this target is in a subrepo, this will be the one it's in.
	Subrepo *Subrepo `print:"false"`

	// List of build target patterns that can use this build target.
	Visibility []BuildLabel
	// Source files of this rule. Can refer to build rules themselves.
	Sources []BuildInput `name:"srcs"`
	// Named source files of this rule; as above but identified by name.
	NamedSources map[string][]BuildInput `name:"srcs"`
	// Data files of this rule. Similar to sources but used at runtime, typically by tests.
	Data []BuildInput

	// Optional output files of this rule. Same as outs but aren't required to be produced always.
	// Can be glob patterns.
	OptionalOutputs []string `name:"optional_outs"`
	// Optional labels applied to this rule. Used for including/excluding rules.
	Labels []string
	// Shell command to run.
	Command string `name:"cmd" hide:"filegroup"`
	// Per-configuration shell commands to run.
	Commands map[string]string `name:"cmd" hide:"filegroup"`
	// Shell command to run for test targets.
	TestCommand string `name:"test_cmd"`
	// Per-configuration test commands to run.
	TestCommands map[string]string `name:"test_cmd"`

	// True if this target is a binary (ie. runnable, will appear in plz-out/bin)
	IsBinary bool `name:"binary"`
	// True if this target is a test
	IsTest bool `name:"test"`
	// Indicates that the target can only be depended on by tests or other rules with this set.
	// Used to restrict non-deployable code and also affects coverage detection.
	TestOnly bool `name:"test_only"`
	// True if we're going to containerise the test.
	Containerise bool `name:"container"`
	// True if the build action is sandboxed.
	Sandbox bool
	// True if the test action is sandboxed.
	TestSandbox bool `name:"test_sandbox"`
	// True if the target is a test and has no output file.
	// Default is false, meaning all tests must produce test.results as output.
	NoTestOutput bool `name:"no_test_output"`
	// True if this target needs access to its transitive dependencies to build.
	// This would be false for most 'normal' genrules but true for eg. compiler steps
	// that need to build in everything.
	NeedsTransitiveDependencies bool `name:"needs_transitive_deps"`
	// True if this target blocks recursive exploring for transitive dependencies.
	// This is typically false for _library rules which aren't complete, and true
	// for _binary rules which normally are, and genrules where you don't care about
	// the inputs, only whatever they were turned into.
	OutputIsComplete bool `name:"output_is_complete"`
	// If true, the rule is given an env var at build time that contains the hash of its
	// transitive dependencies, which can be used to identify the output in a predictable way.
	Stamp bool
	// Marks the target as a filegroup.
	IsFilegroup bool `print:"false"`
	// Marks the target as a hash_filegroup.
	IsHashFilegroup bool `print:"false"`
	// Marks the target as a remote_file.
	IsRemoteFile bool `print:"false"`
	// Marks that the target was added in a post-build function.
	AddedPostBuild bool `print:"false"`
	// If true, the interactive progress display will try to infer the target's progress
	// via some heuristics on its output.
	ShowProgress bool `name:"progress"`
	// If ShowProgress is true, this is used to store the current progress of the target.
	Progress float32 `print:"false"`
	// Containerisation settings that override the defaults.
	ContainerSettings *TargetContainerSettings `name:"container"`
	// The results of this test target, if it is one.
	Results TestSuite `print:"false"`
	// Description displayed while the command is building.
	// Default is just "Building" but it can be customised.
	BuildingDescription string `name:"building_description"`
	// Acceptable hashes of the outputs of this rule. If the output doesn't match any of these
	// it's an error at build time. Can be used to validate third-party deps.
	Hashes []string
	// Licences that this target is subject to.
	Licences []string
	// Any secrets that this rule requires.
	// Secrets are similar to sources but are always absolute system paths and affect the hash
	// differently; they are not used to determine the hash for retrieving a file from cache, but
	// if changed locally will still force a rebuild. They're not copied into the source directory
	// (or indeed anywhere by plz).
	Secrets []string
	// BUILD language functions to call before / after target is built. Allows deferred manipulation of the build graph.
	PreBuildFunction  PreBuildFunction  `name:"pre_build"`
	PostBuildFunction PostBuildFunction `name:"post_build"`
	// Languages this rule requires. These are an arbitrary set and the only meaning is that they
	// correspond to entries in Provides; if rules match up then it allows choosing a specific
	// dependency (consider eg. code generated from protobufs; this mechanism allows us to expose
	// one rule but only compile the appropriate code for each library that consumes it).
	Requires []string
	// Dependent rules this rule provides for each language. Matches up to Requires as described above.
	Provides map[string]BuildLabel
	// Stores the hash of this build rule before any post-build function is run.
	RuleHash []byte `name:"exported_deps"` // bit of a hack to call this exported_deps...
	// Tools that this rule will use, ie. other rules that it may use at build time which are not
	// copied into its source directory.
	Tools []BuildInput

	// Flakiness of test, ie. number of times we will rerun it before giving up. 1 is the default.
	Flakiness int `name:"flaky"`
	// Timeouts for build/test actions
	BuildTimeout time.Duration `name:"timeout"`
	TestTimeout  time.Duration `name:"test_timeout"`
	// Extra output files from the test.
	// These are in addition to the usual test.results output file.
	TestOutputs []string
	// contains filtered or unexported fields
}

A BuildTarget is a representation of a build target and all information about it; its name, dependencies, build commands, etc.

func NewBuildTarget 

func NewBuildTarget(label BuildLabel) *BuildTarget

NewBuildTarget constructs & returns a new BuildTarget.

func (*BuildTarget) AddCommand 

func (target *BuildTarget) AddCommand(config, command string)

AddCommand adds a new config-specific command to this build target. Adding a general command is still done by simply setting the Command member.

func (*BuildTarget) AddDatum 

func (target *BuildTarget) AddDatum(datum BuildInput)

AddDatum adds a new item of data to the target.

func (*BuildTarget) AddDependency 

func (target *BuildTarget) AddDependency(dep BuildLabel)

AddDependency adds a dependency to this target. It deduplicates against any existing deps.

func (*BuildTarget) AddHash 

func (target *BuildTarget) AddHash(hash string)

AddHash adds a new acceptable hash to the target.

func (*BuildTarget) AddLabel 

func (target *BuildTarget) AddLabel(label string)

AddLabel adds the given label to this target if it doesn't already have it.

func (*BuildTarget) AddLicence 

func (target *BuildTarget) AddLicence(licence string)

AddLicence adds a licence to the target if it's not already there.

func (*BuildTarget) AddMaybeExportedDependency 

func (target *BuildTarget) AddMaybeExportedDependency(dep BuildLabel, exported, source bool)

AddMaybeExportedDependency adds a dependency to this target which may be exported. It deduplicates against any existing deps.

func (*BuildTarget) AddNamedOutput 

func (target *BuildTarget) AddNamedOutput(name, output string)

AddNamedOutput adds a new output to the target under a named group. No attempt to deduplicate against unnamed outputs is currently made.

func (*BuildTarget) AddNamedSource 

func (target *BuildTarget) AddNamedSource(name string, source BuildInput)

AddNamedSource adds a source to the target which is tagged with a particular name. For example, C++ rules add sources tagged as "sources" and "headers" to distinguish two conceptually different kinds of input.

func (*BuildTarget) AddNamedTool 

func (target *BuildTarget) AddNamedTool(name string, tool BuildInput)

AddNamedTool adds a new tool to the target.

func (*BuildTarget) AddOptionalOutput 

func (target *BuildTarget) AddOptionalOutput(output string)

AddOptionalOutput adds a new optional output to the target if it's not already there.

func (*BuildTarget) AddOutput 

func (target *BuildTarget) AddOutput(output string)

AddOutput adds a new output to the target if it's not already there.

func (*BuildTarget) AddProvide 

func (target *BuildTarget) AddProvide(language string, label BuildLabel)

AddProvide adds a new provide entry to this target.

func (*BuildTarget) AddRequire 

func (target *BuildTarget) AddRequire(require string)

AddRequire adds a new requirement to the target.

func (*BuildTarget) AddSource 

func (target *BuildTarget) AddSource(source BuildInput)

AddSource adds a source to the build target, deduplicating against existing entries.

func (*BuildTarget) AddTestCommand 

func (target *BuildTarget) AddTestCommand(config, command string)

AddTestCommand adds a new config-specific test command to this build target. Adding a general command is still done by simply setting the TestCommand member.

func (*BuildTarget) AddTestOutput 

func (target *BuildTarget) AddTestOutput(output string)

AddTestOutput adds a new test output to the target if it's not already there.

func (*BuildTarget) AddTool 

func (target *BuildTarget) AddTool(tool BuildInput)

AddTool adds a new tool to the target.

func (*BuildTarget) AllData 

func (target *BuildTarget) AllData(graph *BuildGraph) []string

AllData returns all the data paths for this target.

func (*BuildTarget) AllFullSourcePaths 

func (target *BuildTarget) AllFullSourcePaths(graph *BuildGraph) []string

AllFullSourcePaths returns all the source paths for this target, with a leading plz-out/gen etc if appropriate.

func (*BuildTarget) AllLocalSourcePaths 

func (target *BuildTarget) AllLocalSourcePaths(graph *BuildGraph) []string

AllLocalSourcePaths returns the local part of all the source paths for this target, i.e. without this target's package in it.

func (*BuildTarget) AllLocalSources 

func (target *BuildTarget) AllLocalSources() []string

AllLocalSources returns all the "local" sources of this rule, i.e. all sources that are actually sources in the repo, not other rules or system srcs etc.

func (*BuildTarget) AllSourcePaths 

func (target *BuildTarget) AllSourcePaths(graph *BuildGraph) []string

AllSourcePaths returns all the source paths for this target

func (*BuildTarget) AllSources 

func (target *BuildTarget) AllSources() []BuildInput

AllSources returns all the sources of this rule.

func (*BuildTarget) AllTools 

func (target *BuildTarget) AllTools() []BuildInput

AllTools returns all the tools for this rule in some canonical order.

func (*BuildTarget) BuildDependencies 

func (target *BuildTarget) BuildDependencies() []*BuildTarget

BuildDependencies returns the build-time dependencies of this target (i.e. not data).

func (*BuildTarget) CanSee 

func (target *BuildTarget) CanSee(state *BuildState, dep *BuildTarget) bool

CanSee returns true if target can see the given dependency, or false if not.

func (*BuildTarget) CheckDependencyVisibility 

func (target *BuildTarget) CheckDependencyVisibility(state *BuildState) error

CheckDependencyVisibility checks that all declared dependencies of this target are visible to it. Returns an error if not, or nil if all's well.

func (*BuildTarget) CheckDuplicateOutputs 

func (target *BuildTarget) CheckDuplicateOutputs() error

CheckDuplicateOutputs checks if any of the outputs of this target duplicate one another. Returns an error if so, or nil if all's well.

func (*BuildTarget) CheckSecrets 

func (target *BuildTarget) CheckSecrets() error

CheckSecrets checks that this target's secrets are available. We run this check before building because we don't attempt to copy them, but any rule requiring them will presumably fail if they aren't available. Returns an error if any aren't.

func (*BuildTarget) CoverageFile 

func (target *BuildTarget) CoverageFile() string

CoverageFile returns the output coverage file for tests for this target.

func (*BuildTarget) DeclaredDependencies 

func (target *BuildTarget) DeclaredDependencies() []BuildLabel

DeclaredDependencies returns all the targets this target declared any kind of dependency on (including sources and tools).

func (*BuildTarget) DeclaredDependenciesStrict 

func (target *BuildTarget) DeclaredDependenciesStrict() []BuildLabel

DeclaredDependenciesStrict returns the original declaration of this target's dependencies.

func (*BuildTarget) DeclaredNamedOutputs 

func (target *BuildTarget) DeclaredNamedOutputs() map[string][]string

DeclaredNamedOutputs returns the named outputs from this target's original declaration.

func (*BuildTarget) DeclaredOutputNames 

func (target *BuildTarget) DeclaredOutputNames() []string

DeclaredOutputNames is a convenience function to return the names of the declared outputs in a consistent order.

func (*BuildTarget) DeclaredOutputs 

func (target *BuildTarget) DeclaredOutputs() []string

DeclaredOutputs returns the outputs from this target's original declaration. Hence it's similar to Outputs() but without the resolving of other rule names.

func (*BuildTarget) Dependencies 

func (target *BuildTarget) Dependencies() []*BuildTarget

Dependencies returns the resolved dependencies of this target.

func (*BuildTarget) DependenciesFor 

func (target *BuildTarget) DependenciesFor(label BuildLabel) []*BuildTarget

DependenciesFor returns the dependencies that relate to a given label.

func (*BuildTarget) ExportedDependencies 

func (target *BuildTarget) ExportedDependencies() []BuildLabel

ExportedDependencies returns any exported dependencies of this target.

func (*BuildTarget) FullOutputs 

func (target *BuildTarget) FullOutputs() []string

FullOutputs returns a slice of all the outputs of this rule with the target's output directory prepended.

func (*BuildTarget) GetCommand 

func (target *BuildTarget) GetCommand(state *BuildState) string

GetCommand returns the command we should use to build this target for the current config.

func (*BuildTarget) GetCommandConfig 

func (target *BuildTarget) GetCommandConfig(config string) string

GetCommandConfig returns the command we should use to build this target for the given config.

func (*BuildTarget) GetTestCommand 

func (target *BuildTarget) GetTestCommand(state *BuildState) string

GetTestCommand returns the command we should use to test this target for the current config.

func (*BuildTarget) GetTmpOutput 

func (target *BuildTarget) GetTmpOutput(parseOutput string) string

GetTmpOutput takes the original output filename as an argument, and returns a temporary output filename(plz-out/tmp/) if output has the same name as the package, this avoids the name conflict issue

func (*BuildTarget) GetTmpOutputAll 

func (target *BuildTarget) GetTmpOutputAll(parseOutputs []string) []string

GetTmpOutputAll returns a slice of all the temporary outputs this is used in setting up environment for outputs, e.g: OUTS, OUT

func (*BuildTarget) HasAbsoluteSource 

func (target *BuildTarget) HasAbsoluteSource(source string) bool

HasAbsoluteSource returns true if this target has the given file as a source (or data). The input source includes the target's package name.

func (*BuildTarget) HasAllLabels 

func (target *BuildTarget) HasAllLabels(labels []string) bool

HasAllLabels returns true if target has all of these labels.

func (*BuildTarget) HasAnyLabel 

func (target *BuildTarget) HasAnyLabel(labels []string) bool

HasAnyLabel returns true if target has any of these labels.

func (*BuildTarget) HasDependency 

func (target *BuildTarget) HasDependency(label BuildLabel) bool

HasDependency checks if a target already depends on this label.

func (*BuildTarget) HasLabel 

func (target *BuildTarget) HasLabel(label string) bool

HasLabel returns true if target has the given label.

func (*BuildTarget) HasParent 

func (target *BuildTarget) HasParent() bool

HasParent returns true if the target has a parent rule that's not itself.

func (*BuildTarget) HasSource 

func (target *BuildTarget) HasSource(source string) bool

HasSource returns true if this target has the given file as a source (named or not, or data).

func (*BuildTarget) IsSourceOnlyDep 

func (target *BuildTarget) IsSourceOnlyDep(label BuildLabel) bool

IsSourceOnlyDep returns true if the given dependency was only declared on the srcs of the target.

func (*BuildTarget) IsTool 

func (target *BuildTarget) IsTool(tool BuildLabel) bool

IsTool returns true if the given build label is a tool used by this target.

func (*BuildTarget) NamedOutputs 

func (target *BuildTarget) NamedOutputs(name string) []string

NamedOutputs returns a slice of all the outputs of this rule with a given name. If the name is not declared by this rule it panics.

func (*BuildTarget) NamedTools 

func (target *BuildTarget) NamedTools(name string) []BuildInput

NamedTools returns the tools with the given name.

func (*BuildTarget) OutDir 

func (target *BuildTarget) OutDir() string

OutDir returns the output directory for this target, eg. //mickey/donald:goofy -> plz-out/gen/mickey/donald (or plz-out/bin if it's a binary)

func (*BuildTarget) OutMode 

func (target *BuildTarget) OutMode() os.FileMode

OutMode returns the mode to set outputs of a target to.

func (*BuildTarget) Outputs 

func (target *BuildTarget) Outputs() []string

Outputs returns a slice of all the outputs of this rule.

func (*BuildTarget) Parent 

func (target *BuildTarget) Parent(graph *BuildGraph) *BuildTarget

Parent finds the parent of a build target, or nil if the target is parentless. Note that this is a fairly informal relationship; we identify it by labels with the convention of a leading _ and trailing hashtag on child rules, rather than storing pointers between them in the graph. The parent returned, if any, will be the ultimate ancestor of the target.

func (*BuildTarget) PostBuildOutputFileName 

func (target *BuildTarget) PostBuildOutputFileName() string

PostBuildOutputFileName returns the post-build output file for this target.

func (*BuildTarget) PrefixedLabels 

func (target *BuildTarget) PrefixedLabels(prefix string) []string

PrefixedLabels returns all labels of this target with the given prefix.

func (*BuildTarget) ProvideFor 

func (target *BuildTarget) ProvideFor(other *BuildTarget) []BuildLabel

ProvideFor returns the build label that we'd provide for the given target.

func (*BuildTarget) SetContainerSetting 

func (target *BuildTarget) SetContainerSetting(name, value string) error

SetContainerSetting sets one of the fields on the container settings by name.

func (*BuildTarget) SetState 

func (target *BuildTarget) SetState(state BuildTargetState)

SetState sets a target's current state.

func (*BuildTarget) ShouldInclude 

func (target *BuildTarget) ShouldInclude(includes, excludes []string) bool

ShouldInclude handles the typical include/exclude logic for a target's labels; returns true if target has any include label and not an exclude one. Each include/exclude can have multiple comma-separated labels; in this case, all of the labels in a given group must match.

func (*BuildTarget) SourcePaths 

func (target *BuildTarget) SourcePaths(graph *BuildGraph, sources []BuildInput) []string

SourcePaths returns the source paths for a given set of sources.

func (*BuildTarget) State 

func (target *BuildTarget) State() BuildTargetState

State returns the target's current state.

func (*BuildTarget) SyncUpdateState 

func (target *BuildTarget) SyncUpdateState(before, after BuildTargetState) bool

SyncUpdateState oves the target's state from before to after via a lock. Returns true if successful, false if not (which implies something else changed the state first). The nature of our build graph ensures that most transitions are only attempted by one thread simultaneously, but this one can be attempted by several at once (eg. if a depends on b and c, which finish building simultaneously, they race to queue a).

func (*BuildTarget) TestDir 

func (target *BuildTarget) TestDir() string

TestDir returns the test directory for this target, eg. //mickey/donald:goofy -> plz-out/tmp/mickey/donald/goofy._test This is different to TmpDir so we run tests in a clean environment and to facilitate containerising tests.

func (*BuildTarget) TestResultsFile 

func (target *BuildTarget) TestResultsFile() string

TestResultsFile returns the output results file for tests for this target.

func (*BuildTarget) TmpDir 

func (target *BuildTarget) TmpDir() string

TmpDir returns the temporary working directory for this target, eg. //mickey/donald:goofy -> plz-out/tmp/mickey/donald/goofy._build Note the extra subdirectory to keep rules separate from one another, and the .build suffix to attempt to keep rules from duplicating the names of sub-packages; obviously that is not 100% reliable but we don't have a better solution right now.

func (*BuildTarget) ToolNames 

func (target *BuildTarget) ToolNames() []string

ToolNames returns an ordered list of tool names.

type BuildTargetState 

type BuildTargetState int32

A BuildTargetState tracks the current state of this target in regard to whether it's built or not. Targets only move forwards through this (i.e. the state of a target only ever increases). 

const (
	Inactive   BuildTargetState = iota // Target isn't used in current build
	Semiactive                         // Target would be active if we needed a build
	Active                             // Target is going to be used in current build
	Pending                            // Target is ready to be built but not yet started.
	Building                           // Target is currently being built
	Stopped                            // We stopped building the target because we'd gone as far as needed.
	Built                              // Target has been successfully built
	Cached                             // Target has been retrieved from the cache
	Unchanged                          // Target has been built but hasn't changed since last build
	Reused                             // Outputs of previous build have been reused.
	Failed                             // Target failed for some reason
)

The available states for a target.

func (BuildTargetState) String 

func (s BuildTargetState) String() string

String implements the fmt.Stringer interface.

type BuildTargets 

type BuildTargets []*BuildTarget

BuildTargets makes a slice of build targets sortable by their labels.

func (BuildTargets) Len 

func (slice BuildTargets) Len() int

func (BuildTargets) Less 

func (slice BuildTargets) Less(i, j int) bool

func (BuildTargets) Swap 

func (slice BuildTargets) Swap(i, j int)

type Cache 

type Cache interface {
	// Stores the results of a single build target.
	// Optionally can store extra files against it at the same time.
	Store(target *BuildTarget, key []byte, files ...string)
	// Stores an extra file against a build target.
	// The file name is relative to the target's out directory.
	StoreExtra(target *BuildTarget, key []byte, file string)
	// Retrieves the results of a single build target.
	// If successful, the outputs will be placed into the output file tree.
	Retrieve(target *BuildTarget, key []byte) bool
	// Retrieves an extra file previously stored by StoreExtra.
	// If successful, the file will be placed into the output file tree.
	RetrieveExtra(target *BuildTarget, key []byte, file string) bool
	// Cleans any artifacts associated with this target from the cache, for any possible key.
	Clean(target *BuildTarget)
	// Cleans the entire cache.
	CleanAll()
	// Shuts down the cache, blocking until any potentially pending requests are done.
	Shutdown()
}

Cache is our general interface to caches for built targets. The implementations are in //src/cache, but the interface is in this package because it's passed around on the BuildState object.

type Configuration 

type Configuration struct {
	Please struct {
		Version          cli.Version `` /* 445-byte string literal not displayed */
		Location         string      `` /* 218-byte string literal not displayed */
		SelfUpdate       bool        `help:"Sets whether plz will attempt to update itself when the version set in the config file is different."`
		DownloadLocation cli.URL     `` /* 234-byte string literal not displayed */
		NumOldVersions   int         `help:"Number of old versions to keep from autoupdates."`
		Autoclean        bool        `help:"Automatically clean stale versions without prompting"`
		NumThreads       int         `` /* 132-byte string literal not displayed */
		Motd             []string    `help:"Message of the day; is displayed once at the top during builds. If multiple are given, one is randomly chosen."`
		DefaultRepo      string      `` /* 147-byte string literal not displayed */
	} `help:"The [please] section in the config contains non-language-specific settings defining how Please should operate."`
	Parse struct {
		ExperimentalDir  []string `` /* 309-byte string literal not displayed */
		BuildFileName    []string `` /* 366-byte string literal not displayed */
		BlacklistDirs    []string `` /* 308-byte string literal not displayed */
		PreloadBuildDefs []string `` /* 240-byte string literal not displayed */
		BuiltinPleasings bool     `` /* 301-byte string literal not displayed */
	} `help:"The [parse] section in the config contains settings specific to parsing files."`
	Display struct {
		UpdateTitle bool `` /* 225-byte string literal not displayed */
		SystemStats bool `help:"Whether or not to show basic system resource usage in the interactive display. Has no effect without that configured."`
	} `` /* 307-byte string literal not displayed */
	Events struct {
		Port int `help:"Port to start the streaming build event server on."`
	} `` /* 132-byte string literal not displayed */
	Build struct {
		Arch              cli.Arch     `help:"Architecture to compile for. Defaults to the host architecture."`
		Timeout           cli.Duration `help:"Default timeout for Dockerised tests, in seconds. Default is twenty minutes."`
		Path              []string     `` /* 229-byte string literal not displayed */
		Config            string       `help:"The build config to use when one is not chosen on the command line. Defaults to opt." example:"opt | dbg"`
		FallbackConfig    string       `` /* 149-byte string literal not displayed */
		Lang              string       `` /* 166-byte string literal not displayed */
		Sandbox           bool         `` /* 182-byte string literal not displayed */
		PleaseSandboxTool string       `help:"The location of the please_sandbox tool to use."`
		Nonce             string       `` /* 293-byte string literal not displayed */
		PassEnv           []string     `` /* 210-byte string literal not displayed */
	}
	BuildConfig map[string]string `` /* 307-byte string literal not displayed */
	BuildEnv    map[string]string `` /* 381-byte string literal not displayed */
	Cache       struct {
		Workers               int          `help:"Number of workers for uploading artifacts to remote caches, which is done asynchronously."`
		Dir                   string       `` /* 138-byte string literal not displayed */
		DirCacheHighWaterMark cli.ByteSize `` /* 149-byte string literal not displayed */
		DirCacheLowWaterMark  cli.ByteSize `help:"When cleaning the directory cache, it's reduced to at most this size."`
		DirClean              bool         `help:"Controls whether entries in the dir cache are cleaned or not. If disabled the cache will only grow."`
		DirCompress           bool         `help:"Compresses stored artifacts in the dir cache. They are slower to store & retrieve but more compact."`
		HTTPURL               cli.URL      `help:"Base URL of the HTTP cache.\nNot set to anything by default which means the cache will be disabled."`
		HTTPWriteable         bool         `help:"If True this plz instance will write content back to the HTTP cache.\nBy default it runs in read-only mode."`
		HTTPTimeout           cli.Duration `help:"Timeout for operations contacting the HTTP cache, in seconds."`
		RPCURL                cli.URL      `help:"Base URL of the RPC cache.\nNot set to anything by default which means the cache will be disabled."`
		RPCWriteable          bool         `help:"If True this plz instance will write content back to the RPC cache.\nBy default it runs in read-only mode."`
		RPCTimeout            cli.Duration `help:"Timeout for operations contacting the RPC cache, in seconds."`
		RPCPublicKey          string       `help:"File containing a PEM-encoded private key which is used to authenticate to the RPC cache." example:"my_key.pem"`
		RPCPrivateKey         string       `help:"File containing a PEM-encoded certificate which is used to authenticate to the RPC cache." example:"my_cert.pem"`
		RPCCACert             string       `help:"File containing a PEM-encoded certificate which is used to validate the RPC cache's certificate." example:"ca.pem"`
		RPCSecure             bool         `` /* 194-byte string literal not displayed */
		RPCMaxMsgSize         cli.ByteSize `` /* 241-byte string literal not displayed */
	} `` /* 827-byte string literal not displayed */
	Metrics struct {
		PushGatewayURL cli.URL      `help:"The URL of the pushgateway to send metrics to."`
		PushFrequency  cli.Duration `help:"The frequency, in milliseconds, to push statistics at." example:"400ms"`
		PushTimeout    cli.Duration `help:"Timeout on pushes to the metrics repository." example:"500ms"`
		PerTest        bool         `help:"Emit per-test duration metrics. Off by default because they generate increased load on Prometheus."`
		PerUser        bool         `help:"Emit per-user metrics. On by default for compatibility, but will generate more load on Prometheus."`
	} `` /* 179-byte string literal not displayed */
	CustomMetricLabels map[string]string `` /* 455-byte string literal not displayed */
	Test               struct {
		Timeout          cli.Duration `help:"Default timeout applied to all tests. Can be overridden on a per-rule basis."`
		DefaultContainer string       `` /* 223-byte string literal not displayed */
		Sandbox          bool         `` /* 196-byte string literal not displayed */
	}
	Cover struct {
		FileExtension    []string `` /* 144-byte string literal not displayed */
		ExcludeExtension []string `` /* 164-byte string literal not displayed */
	}
	Docker struct {
		DefaultImage       string       `help:"The default image used for any test that doesn't specify another."`
		AllowLocalFallback bool         `help:"If True, will attempt to run the test locally if containerised running fails."`
		Timeout            cli.Duration `help:"Default timeout for containerised tests. Can be overridden on a per-rule basis."`
		ResultsTimeout     cli.Duration `help:"Timeout to wait when trying to retrieve results from inside the container. Default is 20 seconds."`
		RemoveTimeout      cli.Duration `help:"Timeout to wait when trying to remove a container after running a test. Defaults to 20 seconds."`
	} `` /* 270-byte string literal not displayed */
	Gc struct {
		Keep      []BuildLabel `help:"Marks targets that gc should always keep. Can include meta-targets such as //test/... and //docs:all."`
		KeepLabel []string     `` /* 143-byte string literal not displayed */
	} `` /* 439-byte string literal not displayed */
	Go struct {
		GoTool        string `help:"The binary to use to invoke Go & its subtools with." var:"GO_TOOL"`
		BuildIDTool   string `help:"The binary to use to override Go's BuildIds'." var:"BUILDID_TOOL"`
		GoRoot        string `help:"If set, will set the GOROOT environment variable appropriately during build actions."`
		TestTool      string `` /* 128-byte string literal not displayed */
		GoPath        string `help:"If set, will set the GOPATH environment variable appropriately during build actions." var:"GOPATH"`
		ImportPath    string `` /* 230-byte string literal not displayed */
		CgoCCTool     string `help:"Sets the location of CC while building cgo_library and cgo_test rules. Defaults to gcc" var:"CGO_CC_TOOL"`
		FilterTool    string `` /* 137-byte string literal not displayed */
		DefaultStatic bool   `` /* 197-byte string literal not displayed */
	} `` /* 432-byte string literal not displayed */
	Python struct {
		PipTool            string  `help:"The tool that is invoked during pip_library rules." var:"PIP_TOOL"`
		PipFlags           string  `help:"Additional flags to pass to pip invocations in pip_library rules." var:"PIP_FLAGS"`
		PexTool            string  `help:"The tool that's invoked to build pexes. Defaults to please_pex in the install directory." var:"PEX_TOOL"`
		DefaultInterpreter string  `` /* 208-byte string literal not displayed */
		TestRunner         string  `` /* 152-byte string literal not displayed */
		ModuleDir          string  `` /* 422-byte string literal not displayed */
		DefaultPipRepo     cli.URL `` /* 298-byte string literal not displayed */
		WheelRepo          cli.URL `` /* 150-byte string literal not displayed */
		UsePyPI            bool    `` /* 243-byte string literal not displayed */
		WheelNameScheme    string  `` /* 339-byte string literal not displayed */
	} `` /* 693-byte string literal not displayed */
	Java struct {
		JavacTool          string    `help:"Defines the tool used for the Java compiler. Defaults to javac." var:"JAVAC_TOOL"`
		JlinkTool          string    `help:"Defines the tool used for the Java linker. Defaults to jlink." var:"JLINK_TOOL"`
		JavaHome           string    `help:"Defines the path of the Java Home folder." var:"JAVA_HOME"`
		JavacWorker        string    `` /* 310-byte string literal not displayed */
		JarCatTool         string    `` /* 208-byte string literal not displayed */
		PleaseMavenTool    string    `` /* 164-byte string literal not displayed */
		JUnitRunner        string    `` /* 228-byte string literal not displayed */
		DefaultTestPackage string    `` /* 181-byte string literal not displayed */
		ReleaseLevel       string    `` /* 201-byte string literal not displayed */
		SourceLevel        string    `help:"The default Java source level when compiling. Defaults to 8." var:"JAVA_SOURCE_LEVEL"`
		TargetLevel        string    `help:"The default Java bytecode level to target. Defaults to 8." var:"JAVA_TARGET_LEVEL"`
		JavacFlags         string    `help:"Additional flags to pass to javac when compiling libraries." example:"-Xmx1200M" var:"JAVAC_FLAGS"`
		JavacTestFlags     string    `help:"Additional flags to pass to javac when compiling tests." example:"-Xmx1200M" var:"JAVAC_TEST_FLAGS"`
		DefaultMavenRepo   []cli.URL `` /* 130-byte string literal not displayed */
	} `` /* 366-byte string literal not displayed */
	Cpp struct {
		CCTool             string     `help:"The tool invoked to compile C code. Defaults to gcc but you might want to set it to clang, for example." var:"CC_TOOL"`
		CppTool            string     `` /* 129-byte string literal not displayed */
		LdTool             string     `help:"The tool invoked to link object files. Defaults to ld but you could also set it to gold, for example." var:"LD_TOOL"`
		ArTool             string     `help:"The tool invoked to archive static libraries. Defaults to ar." var:"AR_TOOL"`
		AsmTool            string     `` /* 133-byte string literal not displayed */
		LinkWithLdTool     bool       `` /* 395-byte string literal not displayed */
		DefaultOptCflags   string     `` /* 253-byte string literal not displayed */
		DefaultDbgCflags   string     `` /* 145-byte string literal not displayed */
		DefaultOptCppflags string     `` /* 259-byte string literal not displayed */
		DefaultDbgCppflags string     `` /* 151-byte string literal not displayed */
		DefaultLdflags     string     `help:"Linker flags passed to all C++ rules.\nBy default this is empty." var:"DEFAULT_LDFLAGS"`
		DefaultNamespace   string     `` /* 245-byte string literal not displayed */
		PkgConfigPath      string     `help:"Custom PKG_CONFIG_PATH for pkg-config.\nBy default this is empty." var:"PKG_CONFIG_PATH"`
		Coverage           bool       `` /* 492-byte string literal not displayed */
		TestMain           BuildLabel `` /* 129-byte string literal not displayed */
	} `` /* 512-byte string literal not displayed */
	Proto struct {
		ProtocTool       string   `help:"The binary invoked to compile .proto files. Defaults to protoc." var:"PROTOC_TOOL"`
		ProtocGoPlugin   string   `` /* 264-byte string literal not displayed */
		GrpcPythonPlugin string   `` /* 128-byte string literal not displayed */
		GrpcJavaPlugin   string   `help:"The plugin invoked to compile Java code for grpc_library.\nDefaults to protoc-gen-grpc-java." var:"GRPC_JAVA_PLUGIN"`
		GrpcCCPlugin     string   `help:"The plugin invoked to compile C++ code for grpc_library.\nDefaults to grpc_cpp_plugin." var:"GRPC_CC_PLUGIN"`
		Language         []string `` /* 164-byte string literal not displayed */
		PythonDep        string   `help:"An in-repo dependency that's applied to any Python proto libraries." var:"PROTO_PYTHON_DEP"`
		JavaDep          string   `help:"An in-repo dependency that's applied to any Java proto libraries." var:"PROTO_JAVA_DEP"`
		GoDep            string   `help:"An in-repo dependency that's applied to any Go proto libraries." var:"PROTO_GO_DEP"`
		JsDep            string   `help:"An in-repo dependency that's applied to any Javascript proto libraries." var:"PROTO_JS_DEP"`
		PythonGrpcDep    string   `help:"An in-repo dependency that's applied to any Python gRPC libraries." var:"GRPC_PYTHON_DEP"`
		JavaGrpcDep      string   `help:"An in-repo dependency that's applied to any Java gRPC libraries." var:"GRPC_JAVA_DEP"`
		GoGrpcDep        string   `help:"An in-repo dependency that's applied to any Go gRPC libraries." var:"GRPC_GO_DEP"`
	} `` /* 545-byte string literal not displayed */
	Licences struct {
		Accept []string `` /* 531-byte string literal not displayed */
		Reject []string `` /* 274-byte string literal not displayed */
	} `` /* 262-byte string literal not displayed */
	Aliases  map[string]string `` /* 240-byte string literal not displayed */
	Alias    map[string]*Alias `` /* 169-byte string literal not displayed */
	Provider map[string]*struct {
		Target BuildLabel `help:"The in-repo target to build this provider."`
	} `` /* 245-byte string literal not displayed */
	Bazel struct {
		Compatibility bool `` /* 472-byte string literal not displayed */
	} `` /* 255-byte string literal not displayed */
	// contains filtered or unexported fields
}

A Configuration contains all the settings that can be configured about Please. This is parsed from .plzconfig etc; we also auto-generate help messages from its tags.

func DefaultConfiguration 

func DefaultConfiguration() *Configuration

DefaultConfiguration returns the default configuration object with no overrides.

func ReadConfigFiles 

func ReadConfigFiles(filenames []string, profile string) (*Configuration, error)

ReadConfigFiles reads all the config locations, in order, and merges them into a config object. Values are filled in by defaults initially and then overridden by each file in turn.

func ReadDefaultConfigFiles 

func ReadDefaultConfigFiles(profile string) (*Configuration, error)

ReadDefaultConfigFiles reads all the config files from the default locations and merges them into a config object. The repo root must have already have been set before calling this.

func (*Configuration) AllAliases 

func (config *Configuration) AllAliases() map[string]*Alias

AllAliases returns all the aliases defined in this config

func (*Configuration) ApplyOverrides 

func (config *Configuration) ApplyOverrides(overrides map[string]string) error

ApplyOverrides applies a set of overrides to the config. The keys of the given map are dot notation for the config setting.

func (*Configuration) AttachAliasFlags 

func (config *Configuration) AttachAliasFlags(parser *flags.Parser) bool

AttachAliasFlags attaches the alias flags to the given flag parser. It returns true if any modifications were made.

func (*Configuration) Completions 

func (config *Configuration) Completions(prefix string) []flags.Completion

Completions returns a list of possible completions for the given option prefix.

func (*Configuration) ContainerisationHash 

func (config *Configuration) ContainerisationHash() []byte

ContainerisationHash returns the hash of the containerisation part of the config.

func (*Configuration) GetBuildEnv 

func (config *Configuration) GetBuildEnv() []string

GetBuildEnv returns the build environment configured for this config object.

func (*Configuration) Hash 

func (config *Configuration) Hash() []byte

Hash returns a hash of the parts of this configuration that affect building targets in general. Most parts are considered not to (e.g. cache settings) or affect specific targets (e.g. changing tool paths which get accounted for on the targets that use them).

func (*Configuration) PrintAliases 

func (config *Configuration) PrintAliases(w io.Writer)

PrintAliases prints the set of aliases defined in the config.

func (*Configuration) UpdateArgsWithAliases 

func (config *Configuration) UpdateArgsWithAliases(args []string) []string

UpdateArgsWithAliases applies the aliases in this config to the given set of arguments.

type FileLabel 

type FileLabel struct {
	// Name of the file
	File string
	// Name of the package
	Package string
}

FileLabel represents a file in the current package which is directly used by a target.

func (FileLabel) FullPaths 

func (label FileLabel) FullPaths(graph *BuildGraph) []string

FullPaths is like Paths but includes the leading plz-out/gen directory.

func (FileLabel) Label 

func (label FileLabel) Label() *BuildLabel

Label returns the build rule associated with this input. For a FileLabel it's always nil.

func (FileLabel) LocalPaths 

func (label FileLabel) LocalPaths(graph *BuildGraph) []string

LocalPaths returns paths within the local package

func (FileLabel) Paths 

func (label FileLabel) Paths(graph *BuildGraph) []string

Paths returns a slice of paths to the files of this input.

func (FileLabel) String 

func (label FileLabel) String() string

String returns a string representation of this input.

type LineCoverage 

type LineCoverage uint8

A LineCoverage represents a single line of coverage, which can be in one of several states. Note that Please doesn't support sub-line coverage at present. 

const (
	NotExecutable LineCoverage = iota // Line isn't executable (eg. comment, blank)
	Unreachable   LineCoverage = iota // Line is executable but we've determined it can't be reached. So far not used.
	Uncovered     LineCoverage = iota // Line is executable but isn't covered.
	Covered       LineCoverage = iota // Line is executable and covered.
)

Constants representing the states that a single line can be in for coverage.

func MergeCoverageLines 

func MergeCoverageLines(existing, coverage []LineCoverage) []LineCoverage

MergeCoverageLines merges two sets of coverage results together, taking the superset of the two results.

type NamedOutputLabel 

type NamedOutputLabel struct {
	BuildLabel
	Output string
}

NamedOutputLabel represents a reference to a subset of named outputs from a rule. The rule must have declared those as a named group.

func (NamedOutputLabel) FullPaths 

func (label NamedOutputLabel) FullPaths(graph *BuildGraph) []string

FullPaths is like Paths but includes the leading plz-out/gen directory.

func (NamedOutputLabel) Label 

func (label NamedOutputLabel) Label() *BuildLabel

Label returns the build rule associated with this input. For a NamedOutputLabel it's always non-nil.

func (NamedOutputLabel) LocalPaths 

func (label NamedOutputLabel) LocalPaths(graph *BuildGraph) []string

LocalPaths returns paths within the local package

func (NamedOutputLabel) Paths 

func (label NamedOutputLabel) Paths(graph *BuildGraph) []string

Paths returns a slice of paths to the files of this input.

func (NamedOutputLabel) String 

func (label NamedOutputLabel) String() string

String returns a string representation of this input.

type Package 

type Package struct {
	// Name of the package, ie. //spam/eggs
	Name string
	// If this package is in a subrepo, this is the name of the subrepo.
	// Equivalent to Subrepo.Name but avoids NPEs.
	SubrepoName string
	// Filename of the build file that defined this package
	Filename string
	// Subincluded build defs files that this package imported
	Subincludes []BuildLabel
	// If the package is in a subrepo, this is the subrepo it belongs to. It's nil if not.
	Subrepo *Subrepo

	// Set of output files from rules.
	Outputs map[string]*BuildTarget
	// contains filtered or unexported fields
}

Package is a representation of a package, ie. the part of the system (one or more directories) covered by a single build file.

func NewPackage 

func NewPackage(name string) *Package

NewPackage constructs a new package with the given name.

func (*Package) AddTarget 

func (pkg *Package) AddTarget(target *BuildTarget)

AddTarget adds a new target to this package with the given name. It doesn't check for duplicates.

func (*Package) AllChildren 

func (pkg *Package) AllChildren(target *BuildTarget) []*BuildTarget

AllChildren returns all child targets of the given one. The given target is included as well.

func (*Package) AllTargets 

func (pkg *Package) AllTargets() []*BuildTarget

AllTargets returns the current set of targets in this package. This is threadsafe, unlike iterating .Targets directly which is not.

func (*Package) EnterBuildCallback 

func (pkg *Package) EnterBuildCallback(f func() error) (map[*BuildTarget]struct{}, error)

EnterBuildCallback is used to arbitrate access to build callbacks & track changes to targets. The supplied function will be called & a set of modified targets, along with any errors, is returned.

func (*Package) HasOutput 

func (pkg *Package) HasOutput(output string) bool

HasOutput returns true if the package has the given file as an output.

func (*Package) HasSubinclude 

func (pkg *Package) HasSubinclude(label BuildLabel) bool

HasSubinclude returns true if the package has subincluded the given label.

func (*Package) IsIncludedIn 

func (pkg *Package) IsIncludedIn(label BuildLabel) bool

IsIncludedIn returns true if the given build label would include this package. e.g. //src/... includes the packages src and src/core but not src2.

func (*Package) Label 

func (pkg *Package) Label() BuildLabel

Label returns a build label uniquely identifying this package.

func (*Package) MarkTargetModified 

func (pkg *Package) MarkTargetModified(target *BuildTarget)

MarkTargetModified marks a single target as being modified during a pre- or post- build function. Correct usage of EnterBuildCallback must have been observed.

func (*Package) MustRegisterOutput 

func (pkg *Package) MustRegisterOutput(fileName string, target *BuildTarget)

MustRegisterOutput registers a new output file and panics if it's already been registered.

func (*Package) NumTargets 

func (pkg *Package) NumTargets() int

NumTargets returns the number of targets currently registered in this package.

func (*Package) RegisterOutput 

func (pkg *Package) RegisterOutput(fileName string, target *BuildTarget) error

RegisterOutput registers a new output file in the map. Returns an error if the file has already been registered.

func (*Package) RegisterSubinclude 

func (pkg *Package) RegisterSubinclude(label BuildLabel)

RegisterSubinclude adds a new subinclude to this package, guaranteeing uniqueness.

func (*Package) SourceRoot 

func (pkg *Package) SourceRoot() string

SourceRoot returns the root directory of source files for this package. This is equivalent to .Name for in-repo packages but differs for those in subrepos.

func (*Package) Target 

func (pkg *Package) Target(name string) *BuildTarget

Target returns the target with the given name, or nil if this package doesn't have one.

func (*Package) TargetOrDie 

func (pkg *Package) TargetOrDie(name string) *BuildTarget

TargetOrDie returns the target with the given name, and dies if this package doesn't have one.

func (*Package) VerifyOutputs 

func (pkg *Package) VerifyOutputs()

VerifyOutputs checks all files output from this package and verifies that they're all OK; notably it checks that if targets that output into a subdirectory, that subdirectory isn't created by another target. That kind of thing can lead to subtle and annoying bugs. It logs detected warnings to stdout.

type Parser 

type Parser interface {
	// ParseFile parses a single BUILD file into the given package.
	ParseFile(state *BuildState, pkg *Package, filename string) error
	// ParseReader parses a single BUILD file into the given package.
	ParseReader(state *BuildState, pkg *Package, reader io.ReadSeeker) error
	// RunPreBuildFunction runs a pre-build function for a target.
	RunPreBuildFunction(threadID int, state *BuildState, target *BuildTarget) error
	// RunPostBuildFunction runs a post-build function for a target.
	RunPostBuildFunction(threadID int, state *BuildState, target *BuildTarget, output string) error
	// UndeferAnyParses undefers any pending parses that are waiting for this target to build.
	UndeferAnyParses(state *BuildState, target *BuildTarget)
}

A Parser is the interface to reading and interacting with BUILD files.

type Pool 

type Pool chan func()

A Pool implements an adjustable worker pool. We use it to handle parse tasks where we need to be able to deal with tasks blocking. Push onto the channel to submit new tasks.

func NewPool 

func NewPool(size int) Pool

NewPool constructs a new pool of the given size & starts its workers.

func (Pool) AddWorker 

func (p Pool) AddWorker()

AddWorker adds a new worker to the pool.

func (Pool) Run 

func (p Pool) Run()

Run is a worker function that consumes off the queue.

func (Pool) StopWorker 

func (p Pool) StopWorker()

StopWorker indicates to a worker that it should stop.

type PostBuildFunction 

type PostBuildFunction interface {
	fmt.Stringer
	// Call calls this pre-build function with this target and its output.
	Call(target *BuildTarget, output string) error
}

A PostBuildFunction is a type that allows hooking a post-build callback.

type PreBuildFunction 

type PreBuildFunction interface {
	fmt.Stringer
	// Call calls this pre-build function
	Call(target *BuildTarget) error
}

A PreBuildFunction is a type that allows hooking a pre-build callback.

type SourcePair 

type SourcePair struct{ Src, Tmp string }

A SourcePair represents a source file with its source and temporary locations. This isn't typically used much by callers; it's just useful to have a single type for channels.

type Subrepo 

type Subrepo struct {
	// The name of the subrepo.
	Name string
	// The root directory to load it from.
	Root string
	// If this repo is output by a target, this is the target that creates it. Can be nil.
	Target *BuildTarget
	// The build state instance that tracks this subrepo (it's different from the host one if
	// this subrepo is for a different architecture)
	State *BuildState
	// True if this subrepo was created for a different architecture
	IsCrossCompile bool
}

A Subrepo stores information about a registered subrepository, typically one that we have downloaded somehow to bring in third-party deps.

func SubrepoForArch 

func SubrepoForArch(state *BuildState, arch cli.Arch) *Subrepo

SubrepoForArch creates a new subrepo for the given architecture.

func (*Subrepo) Dir 

func (s *Subrepo) Dir(dir string) string

Dir returns the directory for a package of this name.

type SubrepoFileLabel 

type SubrepoFileLabel struct {
	// Name of the file
	File string
	// Name of the package
	Package string
	// The full path, including the subrepo root.
	FullPackage string
}

A SubrepoFileLabel represents a file in the current package within a subrepo.

func (SubrepoFileLabel) FullPaths 

func (label SubrepoFileLabel) FullPaths(graph *BuildGraph) []string

FullPaths is like Paths but includes the leading plz-out/gen directory.

func (SubrepoFileLabel) Label 

func (label SubrepoFileLabel) Label() *BuildLabel

Label returns the build rule associated with this input. For a SubrepoFileLabel it's always nil.

func (SubrepoFileLabel) LocalPaths 

func (label SubrepoFileLabel) LocalPaths(graph *BuildGraph) []string

LocalPaths returns paths within the local package

func (SubrepoFileLabel) Paths 

func (label SubrepoFileLabel) Paths(graph *BuildGraph) []string

Paths returns a slice of paths to the files of this input.

func (SubrepoFileLabel) String 

func (label SubrepoFileLabel) String() string

String returns a string representation of this input.

type SystemFileLabel 

type SystemFileLabel struct {
	Path string
}

SystemFileLabel represents an absolute system dependency, which is not managed by the build system.

func (SystemFileLabel) FullPaths 

func (label SystemFileLabel) FullPaths(graph *BuildGraph) []string

FullPaths is like Paths but includes the leading plz-out/gen directory.

func (SystemFileLabel) Label 

func (label SystemFileLabel) Label() *BuildLabel

Label returns the build rule associated with this input. For a SystemFileLabel it's always nil.

func (SystemFileLabel) LocalPaths 

func (label SystemFileLabel) LocalPaths(graph *BuildGraph) []string

LocalPaths returns paths within the local package

func (SystemFileLabel) Paths 

func (label SystemFileLabel) Paths(graph *BuildGraph) []string

Paths returns a slice of paths to the files of this input.

func (SystemFileLabel) String 

func (label SystemFileLabel) String() string

String returns a string representation of this input.

type SystemPathLabel 

type SystemPathLabel struct {
	Name string
	Path []string
}

SystemPathLabel represents system dependency somewhere on PATH, which is not managed by the build system.

func (SystemPathLabel) FullPaths 

func (label SystemPathLabel) FullPaths(graph *BuildGraph) []string

FullPaths is like Paths but includes the leading plz-out/gen directory.

func (SystemPathLabel) Label 

func (label SystemPathLabel) Label() *BuildLabel

Label returns the build rule associated with this input. For a SystemPathLabel it's always nil.

func (SystemPathLabel) LocalPaths 

func (label SystemPathLabel) LocalPaths(graph *BuildGraph) []string

LocalPaths returns paths within the local package

func (SystemPathLabel) Paths 

func (label SystemPathLabel) Paths(graph *BuildGraph) []string

Paths returns a slice of paths to the files of this input.

func (SystemPathLabel) String 

func (label SystemPathLabel) String() string

String returns a string representation of this input.

type SystemStats 

type SystemStats struct {
	Memory struct {
		Total, Used uint64
		UsedPercent float64
	}
	// This is somewhat abbreviated to the "interesting" values and is aggregated
	// across all CPUs for convenience of display.
	// We're a bit casual about the exact definition of Used (it's the sum of some
	// fields that seem relevant) and IOWait is not fully reliable.
	CPU struct {
		Used, IOWait float64
		Count        int
	}
	// Number of currently running worker processes.
	// N.B. These are background workers as started by $(worker) commands, not the internal worker
	//      threads tracked in the state object.
	NumWorkerProcesses int
}

SystemStats stores information about the system.

type TargetContainerSettings 

type TargetContainerSettings struct {
	// Image to use for this test
	DockerImage string `name:"docker_image"`
	// Username / Uid to run as
	DockerUser string `name:"docker_user"`
	// Location to mount a tmpfs at
	Tmpfs string `name:"tmpfs"`
}

TargetContainerSettings are known settings controlling containerisation for a particular target.

func (*TargetContainerSettings) ToMap 

func (settings *TargetContainerSettings) ToMap() map[string]string

ToMap returns this struct as a map.

type TaskType 

type TaskType int

A TaskType identifies the kind of task returned from NextTask()

type TestCase 

type TestCase struct {
	ClassName  string          // ClassName of test (optional, for languages that don't have classes)
	Name       string          // Name of test
	Executions []TestExecution // The results of executing the test, possibly multiple times
}

TestCase describes a set of test results for a test method.

func (*TestCase) Duration 

func (testCase *TestCase) Duration() *time.Duration

Duration calculates how long the test case took to run to success or failure (or nil if skipped or abnormal exit).

func (*TestCase) Errors 

func (testCase *TestCase) Errors() []TestExecution

Errors returns all abnormal executions of a test case.

func (*TestCase) Failures 

func (testCase *TestCase) Failures() []TestExecution

Failures returns all failing executions of a test case.

func (*TestCase) Skip 

func (testCase *TestCase) Skip() *TestExecution

Skip returns the either the skipped execution of a test case, or nil if it was never skipped.

func (*TestCase) Success 

func (testCase *TestCase) Success() *TestExecution

Success returns either the successful execution of a test case, or nil if it was never successfully executed.

type TestCases 

type TestCases []TestCase

TestCases is named so we can add a method to it.

func (TestCases) AllSucceeded 

func (testCases TestCases) AllSucceeded() bool

AllSucceeded checks that every test case either passed or was skipped.

type TestCoverage 

type TestCoverage struct {
	Tests map[BuildLabel]map[string][]LineCoverage
	Files map[string][]LineCoverage
}

TestCoverage implements a pretty simple coverage format; we record one int for each line stating what its coverage is.

func NewTestCoverage 

func NewTestCoverage() TestCoverage

NewTestCoverage constructs and returns a new TestCoverage instance.

func (*TestCoverage) Aggregate 

func (coverage *TestCoverage) Aggregate(cov *TestCoverage)

Aggregate aggregates results from that coverage object into this one.

func (*TestCoverage) OrderedFiles 

func (coverage *TestCoverage) OrderedFiles() []string

OrderedFiles returns an ordered slice of all the files we have coverage information for. Note that files are ordered non-trivially such that each directory remains together.

type TestExecution 

type TestExecution struct {
	Failure  *TestResultFailure // The failure, if any, running the test (usually an assertion that failed)
	Error    *TestResultFailure // The error, if any, running the test (usually some other abnormal exit)
	Skip     *TestResultSkip    // The reason for skipping the test, if it was skipped
	Stdout   string             // Standard output during test
	Stderr   string             // Standard error during test
	Duration *time.Duration     // How long the test took (if it did not fail abnormally)
}

TestExecution represents one execution of a test method. The absence of a Failure, Error or Skip implies the test executed successfully.

type TestResultFailure 

type TestResultFailure struct {
	Type      string // The type of error (e.g. "AssertionError")
	Message   string // The reason for error (e.g. "1 != 2")
	Traceback string // The trace of the error (if known)
}

TestResultFailure stores the information related to the failure - stack trace, exception type etc.

type TestResultSkip 

type TestResultSkip struct {
	Message string // The reason for skipping the test
}

TestResultSkip stores the reason for skipping a test.

type TestSuite 

type TestSuite struct {
	Package    string            // The package name of the test suite (usually the first part of the target label).
	Name       string            // The name of the test suite (usually the last part of the target label).
	Cached     bool              // True if the test results were retrieved from cache.
	Duration   time.Duration     // The length of time it took to run this target (may be different from the sum of times of test cases).
	TimedOut   bool              // True if the test failed because we timed it out.
	TestCases  TestCases         // The test cases that ran during execution of this target.
	Properties map[string]string // The system properties at the time of the test.
	Timestamp  string            // ISO8601 formatted datetime when the test ran.
}

TestSuite describes all the test results for a target.

func (*TestSuite) Add 

func (testSuite *TestSuite) Add(cases ...TestCase)

Add puts test cases together if they have the same name and classname, allowing callers to treat multiple test cases as if they were merely multiple executions of the same test.

func (*TestSuite) Collapse 

func (testSuite *TestSuite) Collapse(incoming TestSuite)

Collapse adds the results of one test suite to the current one.

func (*TestSuite) Errors 

func (testSuite *TestSuite) Errors() int

Errors returns the number of TestCases which did not succeed and returned some abnormal error.

func (*TestSuite) Failures 

func (testSuite *TestSuite) Failures() int

Failures returns the number of TestCases which did not succeed and returned some failure.

func (TestSuite) FlakyPasses 

func (testSuite TestSuite) FlakyPasses() int

FlakyPasses returns the number of TestCases which succeeded after some number of executions.

func (TestSuite) JavaStyleName 

func (testSuite TestSuite) JavaStyleName() string

JavaStyleName pretends we are using a language that has package names and classnames etc.

func (TestSuite) Passes 

func (testSuite TestSuite) Passes() int

Passes returns the number of TestCases which succeeded (not skipped).

func (*TestSuite) Skips 

func (testSuite *TestSuite) Skips() int

Skips returns the number of TestCases that were skipped.

func (*TestSuite) Tests 

func (testSuite *TestSuite) Tests() int

Tests returns the number of TestCases.

type TestSuites 

type TestSuites struct {
	TestSuites []TestSuite // The test results for each separate target
}

TestSuites describes a collection of test results for a set of targets.

type URLLabel 

type URLLabel string

A URLLabel represents a remote input that's defined by a URL.

func (URLLabel) FullPaths 

func (label URLLabel) FullPaths(graph *BuildGraph) []string

FullPaths returns an empty slice always (since there are no real source paths)

func (URLLabel) Label 

func (label URLLabel) Label() *BuildLabel

Label returns the build rule associated with this input. For a URLLabel it's always nil.

func (URLLabel) LocalPaths 

func (label URLLabel) LocalPaths(graph *BuildGraph) []string

LocalPaths returns an empty slice always (since there are no real source paths)

func (URLLabel) Paths 

func (label URLLabel) Paths(graph *BuildGraph) []string

Paths returns an empty slice always (since there are no real source paths)

func (URLLabel) String 

func (label URLLabel) String() string

String returns a string representation of this input.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.