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(graph *core.BuildGraph, files, include, exclude []string, ...)
• func AllTargets(graph *core.BuildGraph, labels core.BuildLabels, showHidden bool)
• 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)
• func Graph(graph *core.BuildGraph, targets []core.BuildLabel)
• func Print(graph *core.BuildGraph, labels []core.BuildLabel, fields []string)
• func ReverseDeps(graph *core.BuildGraph, labels []core.BuildLabel)
• 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 JSONGraph
• type JSONPackage
• type JSONTarget

Functions

func AffectedTargets

func AffectedTargets(graph *core.BuildGraph, 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 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)

Deps prints all transitive dependencies of a set of targets.

func Graph

func Graph(graph *core.BuildGraph, targets []core.BuildLabel)

Graph prints a representation of the build graph as JSON.

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(graph *core.BuildGraph, labels []core.BuildLabel)

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

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