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 Print(graph *core.BuildGraph, labels []core.BuildLabel, fields []string)
• func QueryAffectedTargets(graph *core.BuildGraph, files, include, exclude []string, ...)
• func QueryAllTargets(graph *core.BuildGraph, labels core.BuildLabels, showHidden bool)
• func QueryCompletionLabels(config *core.Configuration, args []string, repoRoot string) ([]core.BuildLabel, []core.BuildLabel, bool)
• func QueryCompletions(graph *core.BuildGraph, labels []core.BuildLabel, binary, test, hidden bool)
• func QueryDeps(state *core.BuildState, labels []core.BuildLabel, unique bool)
• func QueryGraph(graph *core.BuildGraph, targets []core.BuildLabel)
• func QuerySomePath(graph *core.BuildGraph, label1 core.BuildLabel, label2 core.BuildLabel)
• func QueryTargetInputs(graph *core.BuildGraph, labels []core.BuildLabel)
• func QueryTargetOutputs(graph *core.BuildGraph, labels []core.BuildLabel)
• func ReverseDeps(graph *core.BuildGraph, labels []core.BuildLabel)
• func WhatOutputs(graph *core.BuildGraph, files []string, printFiles bool)
• type JSONGraph
• type JSONPackage
• type JSONTarget

Functions

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 QueryAffectedTargets

func QueryAffectedTargets(graph *core.BuildGraph, files, include, exclude []string, tests, transitive bool)

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

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

QueryAllTargets simply prints all the targets according to some expression.

func QueryCompletionLabels

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

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

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

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 QueryDeps

func QueryDeps(state *core.BuildState, labels []core.BuildLabel, unique bool)

QueryDeps prints all transitive dependencies of a set of targets.

func QueryGraph

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

QueryGraph prints a representation of the build graph as JSON.

func QuerySomePath

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

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

func QueryTargetInputs

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

QueryTargetInputs prints all inputs for a single target.

func QueryTargetOutputs

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

QueryTargetOutputs prints all output files for a set of targets.

func ReverseDeps

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

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

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