core

package
v13.4.0+incompatible Latest Latest
Warning

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

 Go to latest Published: Jan 25, 2019 License: Apache-2.0 Imports: 33 Imported by: 261

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 SandboxDir = "/tmp/plz_sandbox"

SandboxDir is the directory that sandboxed actions are run in.

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 = "~/.config/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 LookBuildPath 

func LookBuildPath(filename string, config *Configuration) (string, error)

LookBuildPath is like LookPath but takes the config's build path into account.

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 MustSandboxCommand 

func MustSandboxCommand(state *BuildState, cmd []string) []string

MustSandboxCommand is like SandboxCommand but dies on errors.

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 SandboxCommand 

func SandboxCommand(state *BuildState, cmd []string) ([]string, error)

SandboxCommand applies a sandbox to the given command.

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 TargetTimeoutOrDefault 

func TargetTimeoutOrDefault(target *BuildTarget, state *BuildState) time.Duration

TargetTimeoutOrDefault is like TimeoutOrDefault but uses the given target, which can be nil.

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.

func TimeoutOrDefault 

func TimeoutOrDefault(timeout time.Duration, defaultTimeout cli.Duration) time.Duration

TimeoutOrDefault uses the given timeout, or the default if it is not set.

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.

func (BuildResultStatus) IsActive 

func (s BuildResultStatus) IsActive() bool

IsActive returns true if this status represents a target that is not yet finished.

func (BuildResultStatus) IsFailure 

func (s BuildResultStatus) IsFailure() bool

IsFailure returns true if this status represents a failure.

type BuildState 

type BuildState struct {
	Graph *BuildGraph

	// 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 the build has been successful so far (i.e. nothing has failed yet).
	Success bool
	// 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 will run targets at the end of the build.
	NeedRun 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
	// True if we only need to parse the initial package (i.e. don't search downwards
	// through deps) - for example when doing `plz query print`.
	ParsePackageOnly bool
	// True if this build is triggered by watching for changes
	Watch 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) ForConfig 

func (state *BuildState) ForConfig(config ...string) *BuildState

ForConfig creates a copy of this BuildState based on the given config files.

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) 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) LogResult 

func (state *BuildState) LogResult(result *BuildResult)

LogResult logs a build result directly to the state's queue.

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) RemoteResults 

func (state *BuildState) RemoteResults() (<-chan *BuildResult, []*BuildResult)

RemoteResults returns a channel for distributing remote results too, as well as the last set of results per thread.

func (*BuildState) Results 

func (state *BuildState) Results() <-chan *BuildResult

Results returns a channel on which the caller can listen for results.

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)