Please has a rich command line interface that can be used to build and test you code; interrogate the build graph; and much more!
To get the most our of the Please command line interface, it is highly
recommended that you enable tab-completion. Please has a sophisticated
mechanism that is aware of your build graph, all the commands and flags, and
any aliases you may have configured. To enable
Please completions, add this line to your .bashrc
or
.zshrc
:
source <(plz --completion_script)
These flags are common to all (or nearly all) operations.
-c, --config
opt
to build optimised code; dbg
is accepted
for C++ and Go to build code with debugging symbols.-r, --repo_root
-n, --num_threads
-i, --include
:all
or /...
. These apply to labels which can be set on individual targets;
a number of them are predefined, most notably for each language (go
,
python
, java
, cc
, etc).-e, --exclude
--include
; labels of targets to exclude when
selecting multiple targets with :all
or /...
.--include
.--exclude
to exclude targets
as well as by label.-a, --arch
-o, --override
-o python.testrunner:pytest
. See the config
reference for more information on what can be overridden.--profile
--profile ci
will load .plzconfig.ci
. This can be useful to
canonicalise certain settings for non-common or scripted configurations.
-v, --verbosity
--log_file
--log_file_level
--interactive_output
-p, --plain_output
--colour
--nocolour
--trace_file
--version
--show_all_output
--plain_output
.--completion_script
.bashrc
or .zshrc
, e.g. source <(plz --completion_script)
.--noupdate
--nocache
--nohash_verification
--nolock
--keep_workdirs
This is the most common and obvious command; it builds one or more targets
and all their dependencies. A plain plz build
attempts to build
everything, but more usually you can tell it to build a particular target
or targets by passing them on the command line afterwards. For example:
plz build //src/core:core
builds just the one target.
plz build //src/core:all
builds every target in
src/core/BUILD
.
plz build //src/...
builds every target in src
and all subdirectories.
This is also a very commonly used command, it builds one or more targets and
then runs their tests. Which tests to run are specified by positional arguments
as described for plz build
.
After successful completion a combined test output file will be written to
plz-out/log/test_results.xml
in something approximating xUnit
XML format.
It takes a few special flags:
--num_runs
--failing_tests_ok
--test_results_file
-d, --debug
-c dbg
unless that flag is explicitly passed.Very similar to plz test
, but also instruments tests for coverage
and collects results. Tests normally run significantly slower in this mode
(the exact amount depends on the language).
Coverage isn't available for C++ tests at present.
All the same flags from plz test
apply here as well. In addition
there are several more:
--no_coverage_report
--line_coverage_report
--include_all_files
--include_file
--coverage_results_file
--test_results_file
, determines where to write
the aggregated coverage results to.-d, --debug
-c dbg
unless that flag is explicitly passed.This is essentially shorthand for calling plz build
and then
running the result of whatever target was built. It's often handy for iterating
on a single target such that one command builds and reruns it.
Because of the way the target is run after, you have to provide exactly one
target to this command. The target must be marked as binary
in its
rule definition (this is implicit for the various builtin _binary
rules such as go_binary
etc).
If you want to pass flags to the target rather than plz itself, you must pass
them last on the command line, after a --
. This tells Please not
to attempt to parse them as its own flags.
There are two optional subcommands sequential
and parallel
which allow running multiple targets in one go. As the names suggest, they run targets
either one after the other or all in parallel.
In either case, the semantics are a little different to running a single target; arguments
must be passed one by one via the -a
flag, and while stdout / stderr are
connected to the current terminal, stdin is not connected (because it'd not be clear
which process would consume it).
Watches a set of targets for changes. Whenever any one of their source files (or that of any dependency) is changed, the targets will be rebuilt. If any of them are tests, then they will be run as well.
Optionally you can pass the --run
flag if you'd like the targets to be run
(using plz run
) instead of just built / tested.
This allows you to introspect various aspects of the build graph. There are a number of subcommands identifying what you want to query for:
alltargets
: Lists all targets in the graphchanges
: Queries changed targets versus a revision or from a set of filescompletions
: Prints possible completions for a string.deps
: Queries the dependencies of a target.graph
: Prints a JSON representation of the build graph.input
: Prints all transitive inputs of a target.output
: Prints all outputs of a target.print
: Prints a representation of a single targetreverseDeps
: Queries all the reverse dependencies of a target.somepath
: Queries for a path between two targetsrules
: Prints out a machine-parseable description of all currently known build rules.Note that this is not the same as the query language accepted by Bazel and Buck, if you're familiar with those; generally this is lighter weight but less flexible and powerful. We haven't ruled out adding that in the future but have no concrete plans to do so at present.
Cleans up output build artifacts and caches.
This is not normally necessary since generally incrementality detection will ensure that targets are rebuilt if needed. It's possible though for particularly determined rules to do something they shouldn't in which case this might be needed, or (inconceivable though it is) a bug might exist that led to incorrect artifacts being cached.
If given no arguments this cleans the entire plz-out directory and the directory
cache, if configured. It returns immediately with the actual removal proceeding in
the background; you can invoke other plz commands freely while that continues.
You can pass the --nobackground
flag if you'd prefer to wait though.
If it's given targets to clean, it will need to perform a parse to work out what to clean, and will not return until those targets have been cleaned.
The --nocache
flag works like all other commands here, but bears
mentioning since it will prevent artifacts from being removed from the cache
(by default they're cleaned from there too).
This command calculates the hash of outputs for one or more targets. These can
then be passed in the hash
or hashes
attributes of
those targets to verify their output is as expected - this is useful for
fetching third-party dependencies to ensure they are not changing between builds.
The relevant targets will be built in order to calculate the hash, but if they fail because it doesn't match the one recorded in the BUILD file plz will still exit successfully (although the output files will still not be created).
One can of course achieve the same effect via running plz build
and
reading the actual hash when it fails, but this way is generally considered nicer.
The --update
flag will cause Please to rewrite the BUILD file with
any changed hashes that it can find.
a.k.a. plz format
Auto-formats existing BUILD files. You can either provide a list of files to reformat or, if none are given, it will discover all BUILD files in the repository.
The -w
flag rewrites existing files in-place; if not passed the
formatted version will be printed to stdout.
The implementation is currently based on a lightly modified version of
buildifier which supports nearly
a superset of the same dialect, but lacks one or two features such as type annotations.
These are relatively rarely used in BUILD files though.
Creates an initial (and pretty empty) .plzconfig
file in the current
directory (or, if the --dir
flag is passed, somewhere else).
You'll be warned before overwriting an existing file.
It will also create a wrapper script, pleasew
which runs plz if found
on the local machine, and otherwise attempts to download a copy. This can be handy
for users who don't have it installed already.
There is a --bazel_compat
flag which initialises the config file for
Bazel compatibility mode. This changes behaviour in various ways to make it easier
to begin building an existing Bazel project - although more complex projects will
still likely find things that don't translate easily.
Updates plz to the appropriate version. This is quite tightly governed by the
.plzconfig
file:
selfupdate
is true, then it's not normally necessary to run this
since any invocation of plz will update before running. It will still behave as
normal though if invoked explicitly.version
property is set then it will attempt to download
exactly that version, and fail if it can't for some reason.downloadlocation
property determines where it tries to download
from; by default it's the central plz site, but you could set this to a server of
your own if you'd rather be more independent.Runs a basic "garbage collection" step, which attempts to identify targets that aren't in use. This is still fairly experimental since the definition of "not used" isn't always very clear (for example, ideally simply having a test on a library that isn't otherwise used would not be enough to keep both of those). Because of this it suggests a set of targets that it's pretty sure aren't used at all, and a secondary set that it's less sure on.
Right now the name is a bit misleading since it finds but doesn't collect the garbage;
ideally it'd be able to rewrite the BUILD files itself. Deleting sources is a little
trickier since you'd often want to couple that with a VC operation (i.e. git rm
)
and by design plz is unaware of the VCS in use.
There are a few flags controlling it:
-c
, --conservative
-t
, --targets_only
-t
, --srcs_only
Displays help about a particular facet of Please. It knows about built-in build rules, config
settings and a few other things. Mostly this is useful as an instant reference; you can run
plz help topics
to get a list of all the topics that it knows about.
Re-runs whatever the previous command was.