query

Documentation

Overview

Package query implements a simple query language for Please.

Currently supported operations:

'deps': 'plz query deps //src:please'
        shows the dependency graph of this target.
'somepath': 'plz query somepath //src:please //src/parse/rules:java_rules_pyc'
            finds a route between these two targets, if there is one.
            useful for saying 'why on earth do I depend on that thing?'
'alltargets': 'plz query alltargets //src/...'
              shows all targets currently in the graph. careful in large repos!
'print': 'plz query print //src:please'
         produces a python-like function call that would define the rule.
'completions': 'plz query completions //sr'
         produces a list of possible completions for the given stem.
'affectedtargets': 'plz query affectedtargets path/to/changed_file.py'
         produces a list of test targets which have a transitive dependency on
         the given file.
'input': 'plz query input //src:label' produces a list of all the files
         (including transitive deps) that are referenced by this rule.
'output': 'plz query output //src:label' produces a list of all the files
          that are output by this rule.
'graph': 'plz query graph' produces a JSON representation of the build graph
         that other programs can interpret for their own uses.

Index

• func AffectedTargets(state *core.BuildState, files, include, exclude []string, ...)
• func AllTargets(graph *core.BuildGraph, labels core.BuildLabels, showHidden bool)
• func ChangedLabels(state *core.BuildState, request ChangedRequest) []core.BuildLabel
• func CompletionLabels(config *core.Configuration, args []string, repoRoot string) ([]core.BuildLabel, []core.BuildLabel, bool)
• func Completions(graph *core.BuildGraph, labels []core.BuildLabel, binary, test, hidden bool)
• func Deps(state *core.BuildState, labels []core.BuildLabel, unique bool, targetLevel int)
• func DiffGraphs(before, after *core.BuildState, files []string) []core.BuildLabel
• func Filter(state *core.BuildState, labels core.BuildLabels)
• func GetAllPackages(config *core.Configuration, query, repoRoot string) []string
• func Graph(state *core.BuildState, targets []core.BuildLabel)
• func MustCheckout(revision, command string)
• func MustGetRevision(command string) string
• func Print(graph *core.BuildGraph, labels []core.BuildLabel, fields []string)
• func ReverseDeps(state *core.BuildState, labels []core.BuildLabel)
• func Roots(graph *core.BuildGraph, labels core.BuildLabels)
• func SomePath(graph *core.BuildGraph, label1 core.BuildLabel, label2 core.BuildLabel)
• func TargetInputs(graph *core.BuildGraph, labels []core.BuildLabel)
• func TargetOutputs(graph *core.BuildGraph, labels []core.BuildLabel)
• func WhatOutputs(graph *core.BuildGraph, files []string, printFiles bool)
• type ChangedRequest
• type JSONGraph
• type JSONPackage
• type JSONTarget

Functions

func AffectedTargets

func AffectedTargets(state *core.BuildState, files, include, exclude []string, tests, transitive bool)

AffectedTargets walks over the build graph and identifies all targets that have a transitive dependency on the given set of files. Targets are filtered by given include / exclude labels and if 'tests' is true only test targets will be returned.

func AllTargets

func AllTargets(graph *core.BuildGraph, labels core.BuildLabels, showHidden bool)

AllTargets simply prints all the targets according to some expression.

func ChangedLabels

func ChangedLabels(state *core.BuildState, request ChangedRequest) []core.BuildLabel

ChangedLabels returns all BuildLabels that have changed according to the given request.

func CompletionLabels

func CompletionLabels(config *core.Configuration, args []string, repoRoot string) ([]core.BuildLabel, []core.BuildLabel, bool)

CompletionLabels produces a set of labels that complete a given input. The second return value is a set of labels to parse for (since the original set generally won't turn out to exist). The last return value is true if one or more of the inputs are a "hidden" target (i.e. name begins with an underscore).

func Completions

func Completions(graph *core.BuildGraph, labels []core.BuildLabel, binary, test, hidden bool)

Completions queries a set of possible completions for some build labels. If 'binary' is true it will complete only targets that are runnable binaries (but not tests). If 'test' is true it will similarly complete only targets that are tests. If 'hidden' is true then hidden targets (i.e. those with names beginning with an underscore) will be included as well.

func Deps

func Deps(state *core.BuildState, labels []core.BuildLabel, unique bool, targetLevel int)

Deps prints all transitive dependencies of a set of targets.

func DiffGraphs

func DiffGraphs(before, after *core.BuildState, files []string) []core.BuildLabel

DiffGraphs calculates the difference between two build graphs. Note that this is not symmetric; targets that have been removed from 'before' do not appear (because this is designed to be fed into 'plz test' and we can't test targets that no longer exist).

func Filter

func Filter(state *core.BuildState, labels core.BuildLabels)

Filter takes the list of BuildLabels and checks which ones match the label selectors passed in.

func GetAllPackages

func GetAllPackages(config *core.Configuration, query, repoRoot string) []string

GetAllPackages returns a string slice of all the package labels, such as "//src/core/query"

func Graph

func Graph(state *core.BuildState, targets []core.BuildLabel)

Graph prints a representation of the build graph as JSON.

func MustCheckout

func MustCheckout(revision, command string)

MustCheckout checks out the given revision.

func MustGetRevision

func MustGetRevision(command string) string

MustGetRevision runs a command to determine the current revision.

func Print

func Print(graph *core.BuildGraph, labels []core.BuildLabel, fields []string)

Print produces a Python call which would (hopefully) regenerate the same build rule if run. This is of course not ideal since they were almost certainly created as a java_library or some similar wrapper rule, but we've lost that information by now.

func ReverseDeps

func ReverseDeps(state *core.BuildState, labels []core.BuildLabel)

ReverseDeps For each input label, finds all targets which depend upon it.

func Roots

func Roots(graph *core.BuildGraph, labels core.BuildLabels)

Roots returns build labels with no dependents from the given list. i.e. if `labels` contains `A` and `B` such that `A` depends-on `B` (possibly through some indirect path) only `B` will be output. This does not perform an ordering of the labels, but theoretically you could call this method repeatedly with a shrinking set of labels.

func SomePath

func SomePath(graph *core.BuildGraph, label1 core.BuildLabel, label2 core.BuildLabel)

SomePath finds and returns a path between two targets. Useful for a "why on earth do I depend on this thing" type query.

func TargetInputs

func TargetInputs(graph *core.BuildGraph, labels []core.BuildLabel)

TargetInputs prints all inputs for a single target.

func TargetOutputs

func TargetOutputs(graph *core.BuildGraph, labels []core.BuildLabel)

TargetOutputs prints all output files for a set of targets.

func WhatOutputs

func WhatOutputs(graph *core.BuildGraph, files []string, printFiles bool)

WhatOutputs prints the target responsible for producing each of the provided files The targets are printed in the same order as the provided files, separated by a newline Use printFiles to additionally echo the files themselves (i.e. print <file> <target>)

Types

type ChangedRequest

type ChangedRequest struct {
	Since            string
	DiffSpec         string
	IncludeDependees string
}

ChangedRequest is a simple parameter object

type JSONGraph

type JSONGraph struct {
	Packages map[string]JSONPackage `json:"packages"`
}

JSONGraph is an alternate representation of our build graph; will contain different information to the structures in core (also those ones can't be printed as JSON directly).

type JSONPackage

type JSONPackage struct {
	Targets map[string]JSONTarget `json:"targets"`
	// contains filtered or unexported fields
}

JSONPackage is an alternate representation of a build package

type JSONTarget

type JSONTarget struct {
	Inputs   []string `json:"inputs,omitempty" note:"declared inputs of target"`
	Outputs  []string `json:"outs,omitempty" note:"corresponds to outs in rule declaration"`
	Sources  []string `json:"srcs,omitempty" note:"corresponds to srcs in rule declaration"`
	Deps     []string `json:"deps,omitempty" note:"corresponds to deps in rule declaration"`
	Data     []string `json:"data,omitempty" note:"corresponds to data in rule declaration"`
	Labels   []string `json:"labels,omitempty" note:"corresponds to labels in rule declaration"`
	Requires []string `json:"requires,omitempty" note:"corresponds to requires in rule declaration"`
	Hash     string   `json:"hash" note:"partial hash of target, does not include source hash"`
	Test     bool     `json:"test,omitempty" note:"true if target is a test"`
	Binary   bool     `json:"binary,omitempty" note:"true if target is a binary"`
	TestOnly bool     `json:"test_only,omitempty" note:"true if target should be restricted to test code"`
}

JSONTarget is an alternate representation of a build target