core

package
v9.5.0+incompatible Latest Latest
Warning

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

 Go to latest Published: Oct 30, 2017 License: Apache-2.0 Imports: 30 Imported by: 2

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 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.

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 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 CopyFile 

func CopyFile(from string, to string, mode os.FileMode) error

CopyFile copies a file from 'from' to 'to', with an attempt to perform a copy & rename to avoid chaos if anything goes wrong partway.

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 bool, argv []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(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 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 ExpandHomePath 

func ExpandHomePath(path string) string

ExpandHomePath expands all prefixes of ~ without a user specifier TO $HOME.

func FileExists 

func FileExists(filename string) bool

FileExists returns true if the given path exists and is a file.

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 Glob 

func Glob(rootPath string, includes, prefixedExcludes, excludes []string, includeHidden bool) []string

Glob implements matching using Go's built-in filepath.Glob, but extends it to support Ant-style patterns using **.

func IsGlob 

func IsGlob(pattern string) bool

IsGlob returns true if the given pattern requires globbing (i.e. contains characters that would be expanded by it)

func IsPackage 

func IsPackage(name string) bool

IsPackage returns true if the given directory name is a package (i.e. contains a build file)

func IsSameFile 

func IsSameFile(a, b string) bool

IsSameFile returns true if two filenames describe the same underlying file (i.e. inode)

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 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 returns true if the given path exists, as a file or a directory.

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 RecursiveCopyFile 

func RecursiveCopyFile(from string, to string, mode os.FileMode, link, fallback bool) error

RecursiveCopyFile copies either a single file or a directory. If 'link' is true then we'll hardlink files instead of copying them. If 'fallback' is true then we'll fall back to a copy if linking fails.

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.

func WriteFile 

func WriteFile(fromFile io.Reader, to string, mode os.FileMode) error

WriteFile writes data from a reader to the file named 'to', with an attempt to perform a copy & rename to avoid chaos if anything goes wrong partway.

Types

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, test bool) BuildEnv

BuildEnvironment creates the shell env vars to be passed into the exec.Command calls made by plz. Use test=true for plz test targets. 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, test bool, 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 (BuildEnv) Redacted 

func (env BuildEnv) Redacted() interface{}

Redacted implements the interface for our logging implementation.

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

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

Package retrieves a package from the graph by name

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(name string) *Package

PackageOrDie retrieves a package by name, 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) 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 TryParseNamedOutputLabel 

func TryParseNamedOutputLabel(target, currentPath string) (BuildInput, error)

TryParseNamedOutputLabel 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
}

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

func FindOwningPackage 

func FindOwningPackage(file string) BuildLabel

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

func FindOwningPackages 

func FindOwningPackages(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 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 string, 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) 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 TestResults
}

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
	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
	// 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
	}
	// 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. 0 == 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
	// 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. 

var State *BuildState

State is a singleton instance of the most recently constructed BuildState. We would prefer not to have this but it ended up being inevitable for some of the parsing code that doesn't have ready access to other Go variables.

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 (*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) 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.

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) 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 *TestResults, 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) 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()

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

type BuildTarget 

type BuildTarget struct {

	// Identifier of this build target
	Label BuildLabel `name:"name"`

	// 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"`
	// Per-configuration shell commands to run.
	Commands map[string]string `name:"cmd"`
	// 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 that the target was added in a post-build function.
	AddedPostBuild bool `print:"false"`
	// Containerisation settings that override the defaults.
	ContainerSettings *TargetContainerSettings `name:"container"`
	// Results of test, if it is one
	Results TestResults `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
	// Python functions to call before / after target is built. Allows deferred manipulation of the
	// build graph.
	PreBuildFunction  uintptr `name:"pre_build"`
	PostBuildFunction uintptr `name:"post_build"`
	// Hash of the function's bytecode. Used for incrementality.
	// TODO(pebers): unify with RuleHash maybe? seems wasteful to store these separately.
	PreBuildHash, PostBuildHash []byte `print:"false"`
	// 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. 0 is the default and
	// is interpreted the same way as 1 would be (ie. one run only).
	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) 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) 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) 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) 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(dep *BuildTarget) bool

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

func (*BuildTarget) CheckDependencyVisibility 

func (target *BuildTarget) CheckDependencyVisibility(graph *BuildGraph) 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) 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) GetCommand 

func (target *BuildTarget) GetCommand() 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() string

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

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

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) 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) 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 */
		NumThreads       int         `` /* 132-byte string literal not displayed */
		BuildFileName    []string    `help:"Deprecated, use parse.buildfilename instead"`
		BlacklistDirs    []string    `help:"Deprecated, use parse.blacklistdirs instead"`
		Lang             string      `help:"Deprecated, use build.lang instead"`
		ParserEngine     string      `help:"Deprecated, use parse.engine instead"`
		Nonce            string      `help:"Deprecated, use build.nonce instead"`
		ExperimentalDir  string      `help:"Deprecated, use parse.experimentaldir instead"`
		LintTool         string      `help:"Deprecated, use parse.linttool instead."`
	} `help:"The [please] section in the config contains non-language-specific settings defining how Please should operate."`
	Parse struct {
		LintTool         string   `help:"Location of the lint tool for BUILD files."`
		Engine           string   `` /* 290-byte string literal not displayed */
		ExperimentalDir  string   `` /* 309-byte string literal not displayed */
		BuildFileName    []string `` /* 343-byte string literal not displayed */
		BlacklistDirs    []string `` /* 308-byte string literal not displayed */
		PreloadBuildDefs []string `` /* 240-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 {
		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         `` /* 185-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 */
	}
	BuildConfig map[string]string `` /* 307-byte string literal not displayed */
	BuildEnv    map[string]string `` /* 379-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 */
		DirCacheCleaner       string       `` /* 309-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."`
		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."`
	} `` /* 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       `` /* 201-byte string literal not displayed */
		Sandbox          bool         `` /* 177-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."`
		RunArgs            []string     `help:"Arguments passed to docker run when running a test." example:"-e LANG=en_GB"`
	} `` /* 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"`
		GoVersion string `` /* 471-byte string literal not displayed */
		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"`
		CgoCCTool string `help:"Sets the location of CC while building cgo_library and cgo_test rules. Defaults to gcc" var:"CGO_CC_TOOL"`
	} `` /* 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 */
		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 */
	} `` /* 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"`
		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 */
		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 */
	} `` /* 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_JAVA_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"`
		PythonPackage    string   `` /* 200-byte string literal not displayed */
	} `` /* 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 */
	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) (*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 (*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) 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).

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
	// Filename of the build file that defined this package
	Filename string
	// Subincluded build defs files that this package imported
	Subincludes []BuildLabel
	// Targets contained within the package
	Targets map[string]*BuildTarget
	// 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) 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) 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) 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) 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.

type Parser 

type Parser interface {
	// 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 allows performing several parsing tasks directly. This is not used for normal BUILD file parsing, but rather pre/post build callbacks etc to decouple the build package from calling straight into parse (since parse is cgo we attempt to minimise any dependencies on it).

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 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
	}
}

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"`
	// Extra arguments to pass to 'docker run'
	DockerRunArgs string `name:"docker_run_args"`
}

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 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.

type TestFailure 

type TestFailure struct {
	Name      string // Name of failed test
	Type      string // Type of failure, eg. type of exception raised
	Traceback string // Traceback
	Stdout    string // Standard output during test
	Stderr    string // Standard error during test
}

TestFailure represents information about a test failure.

type TestResults 

type TestResults struct {
	NumTests         int // Total number of test cases in the test target.
	Passed           int // Number of tests that passed outright.
	Failed           int // Number of tests that failed.
	ExpectedFailures int // Number of tests that were expected to fail (counts as a pass, but displayed differently)
	Skipped          int // Number of tests skipped (also count as passes)
	Flakes           int // Number of failed attempts to run the test
	Failures         []TestFailure
	Passes           []string
	Output           string        // Stdout / stderr from the test.
	Cached           bool          // True if the test results were retrieved from cache
	TimedOut         bool          // True if the test failed because we timed it out.
	Duration         time.Duration // Length of time this test took
}

TestResults describes a set of test results for a test target.

func (*TestResults) Aggregate 

func (results *TestResults) Aggregate(r *TestResults)

Aggregate aggregates the given results into this one.

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.