Please commands

Please has a rich command line interface that can be used to build and test you code; interrogate the build graph; and much more!

Tab completion

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)

Common flags

These flags are common to all (or nearly all) operations.

Options controlling what to build & how to build it:

  • -c, --config

    The build config to use. The effect this has depends on the language; typically it allows swapping between a debug or an optimised build.
    The default is opt to build optimised code; dbg is accepted for C++ and Go to build code with debugging symbols.
    This has no effect on Python or Java rules.

  • -r, --repo_root

    Sets the location of the repo root to use. Normally plz assumes it is within the repo somewhere and locates the root itself, this forces it to a specific location.

  • -n, --num_threads

    Sets the number of parallel workers to use while building. The default is the number of logical CPUs of the current machine plus two.

  • -i, --include

    Labels of targets to include when selecting multiple targets with :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).
    Only targets with this label will be built.

  • -e, --exclude

    The inverse of --include; labels of targets to exclude when selecting multiple targets with :all or /....
    Takes priority over --include.
    You can also pass build expressions to --exclude to exclude targets as well as by label.

  • -a, --arch

    Architecture to compile for. By default Please will build for the host architecture, but has some support for targeting others. See the cross-compiling docs for more information.

  • -o, --override

    Allows overriding individual config settings on a temporary basis; for example -o python.testrunner:pytest. See the config reference for more information on what can be overridden.

  • --profile

    Defines a profile of config file to load from the repo. For example, --profile ci will load .plzconfig.ci. This can be useful to canonicalise certain settings for non-common or scripted configurations.

Options controlling output & logging:

  • -v, --verbosity

    Sets the amount of output logged from plz; a number between 0 and 4.
    Each number shows all messages at the given level and above:

    1. 0. Error
    2. 1. Warning
    3. 2. Notice
    4. 3. Info
    5. 4. Debug

    The default is 1, for warnings and errors only. If level 4 is requested then it will suppress interactive output.

  • --log_file

    Writes all logs out into the given file.

  • --log_file_level

    Level of logging to write to the file. Defaults to 2 (notice, warning and error).

  • --interactive_output

    Forces plz to show interactive output on stderr. By default it autodetects based on whether stderr appears to be an interactive terminal or not, but this flag can be used to force it on in cases where it might get it wrong.

  • -p, --plain_output

    Forces plz not to show interactive output on stderr. Can be useful in cases where it might obscure other messages or where the output isn't capable of interpreting the escape codes correctly.

  • --colour

    Forces coloured output from logging & shell output. Again, this is autodetected by default, but this can be used in cases where it would normally detect false but it will later be consumed by something that understands the codes (e.g. CI systems like Teamcity or Jenkins).

  • --nocolour

    Inverse of above, forces colourless output from logging & the shell.

  • --trace_file

    File to write Chrome tracing output into.
    This is a JSON format that contains the actions taken by plz during the build and their timings. You can load the file up in about:tracing and use that to see which parts of your build were slow.

  • --version

    Prints the version of the tool and exits immediately.

  • --show_all_output

    Prints all output of each building process as they run. Implies --plain_output.

  • --completion_script

    Prints the bash / zsh completion script to stdout. This can be used in a .bashrc or .zshrc, e.g. source <(plz --completion_script).

Options that enable / disable certain features:

  • --noupdate

    Disables Please attempting to auto-update itself.

  • --nohash_verification

    Turns hash verification errors into non-fatal warnings.
    Obviously this is only for local development & testing, not for 'production' use.

  • --nolock

    Don't attempt to lock the repo exclusively while building.
    Use with care - if two instances of plz start building the same targets simultaneously they will likely fail with very strange errors.

  • --keep_workdirs

    Don't clean directories in plz-out/tmp after successfully building targets.
    They're always left in cases where targets fail.

plz build

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.

plz test

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

    Determines how many times to run each test. The default is 1, but can be more for tests marked as flaky.

  • --failing_tests_ok

    The return value is 0 regardless of whether any tests fail or not. It will only be nonzero if they fail to build completely.
    This is not commonly used, it's mostly useful for CI automation which will parse the results file to determine ultimate success / failure.

  • --test_results_file

    Specifies the location to write the combined test results to.

  • -d, --debug

    Turns on interactive debug mode for this test. You can only specify one test with this flag, because it attaches an interactive debugger to catch failures.
    It only works for some test types, currently python (with pytest as the test runner), C and C++.
    It implies -c dbg unless that flag is explicitly passed.

plz cover

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

    Suppresses the coverage report output to the shell.

  • --line_coverage_report

    Produces a line-by-line coverage display for all source files.

  • --include_all_files

    Includes any transitively dependent source files in the coverage report (the default is just files from relevant packages).

  • --include_file

    Files to include in the coverage report (the flag can be passed more than once for multiple).

  • --coverage_results_file

    Similar to --test_results_file, determines where to write the aggregated coverage results to.

  • -d, --debug

    Turns on interactive debug mode for this test. You can only specify one test with this flag, because it attaches an interactive debugger to catch failures.
    It only works for some test types, currently python (with pytest as the test runner), C and C++.
    It implies -c dbg unless that flag is explicitly passed.

plz run

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

plz exec

This command executes the target in a hermetic build environment, as opposed to the plz run command. This allows for uses cases, such as: debugging/profiling programs that may require a predictable environment, or running E2E tests reliant on external state which doesn't fit with Please's caching approach.

The --share_network and --share_mount flags are available (Linux only) for greater control over the sandboxed environment where the target is run. The --share_network flag is useful in situations where the host system might want to connect to a server that the command started.

The --output_path and --out flags allow for artifacts, produced by the command executed in the sandboxed environment, to be copied onto the host system where plz exec is being run from.

Non-binary targets are also supported, but a custom command (see above) is required since there isn't a binary produced that can be executed by default. These targets' results can be accessed via the $OUTS environment variable.

Only a single command is supported per execution with plz exec. Multiple can be run with plz exec sequential or plz exec parallel, which are analogous to their plz run equivalents.

plz watch

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.

plz query

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 graph.
  • filter: Filter targets based on --include and --exclude. This is commonly used with other commands. For example, to run e2e tests separately from other tests: plz query changes --since master > plz-out/changes, then cat plz-out/changes | plz query filter --include e2e - | plz test -.
  • changes: Queries changed targets versus a revision or from a set of files.
  • completions: 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 target.
  • reverseDeps: Queries all the reverse dependencies of a target.
  • somepath: Queries for a path between two targets.
  • rules: Prints out a machine-parseable description of all currently known build rules.
  • whatinputs: Prints out target(s) with provided file(s) as inputs
  • whatoutputs: Prints out target(s) responsible for outputting provided file(s)

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.

plz clean

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.

plz hash

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.

plz fmt

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.

plz init

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.

plz generate

This command can be used to build generated sources and link them back into the source tree. This can be useful for tooling that expects generated sources to be there like linters and IDEs.

To build all generated sources, simply run plz generate.

Please can also update a gitignore file, ignoring all the gnerated files automatically: plz generate --update_gitignore .gitignore

To automatically link generated sources and update .gitignore files during normal builds, see the LinkGeneratedSources, and UpdateGitignore config values.

plz update

Updates plz to the appropriate version. This is quite tightly governed by the .plzconfig file:

  • If 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.
  • If the version property is set then it will attempt to download exactly that version, and fail if it can't for some reason.
  • Otherwise it will try to find the latest available version and update to that.
  • The 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.

plz gc

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

    Uses a more conservative algorithm (specifically any tests will keep their targets).

  • -t, --targets_only

    Only prints the targets to be removed (not sources). Useful to pipe them into another program.

  • -t, --srcs_only

    Only prints the sources to be removed (not targets). Useful to pipe them into another program.

plz help

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.

plz op

Re-runs whatever the previous command was.