Please config file reference

The root of a Please repo is identified by a .plzconfig file. This also has a number of options to control various parts of its behaviour which might be useful to tailor it to your environment.

Please looks in several locations for these files and builds it up bit by bit. In order (from lowest priority to highest):

One would normally check in .plzconfig (and arch-specific equivalents if needed).
/etc/please/plzconfig is there to facilitate per-machine config in cases where the repo is often deleted - this is quite common in CI systems.
Finally you normally add .plzconfig.local to .gitignore to allow people to override settings locally if needed.

The file format is very similar to Git's config; it's broken into sections by headers in square brackets, and each section contains option = value pairs. Comments start with a semicolon.

We'll list out the various options by section. The option names are all case-insensitive, the values are of course case sensitive (except in the case of boolean variables which accept various forms of true, false, yes, no, etc).
Various parameters can be repeated (they're noted as such below); this means passing them multiple times in their entirety, e.g.

  
  
    buildfilename = BUILD
    buildfilename = BUILD.plz
  

Comma-separating on the same line won't generally work.

[Please]

[Parse]

[Display]

Contains options relating to display output. These have no impact on build output.

[Build]

[BuildEnv]

A set of extra environment variables to define for build rules. For example:

    
    
    [buildenv]
    secret-passphrase = 12345
    
  

This would become SECRET_PASSPHRASE for any rules. These can be useful for passing secrets into custom rules; any variables containing SECRET or PASSWORD won't be logged.

[Remote]

This whole section is still experimental; some settings may not work fully and as a whole it's subject to change. Proceed with caution!

[Cache]

[Test]

[Cover]

[Gc]

Options relating to use of plz gc.

[Go]

Properties that affect how the various Go build rules work.

[Python]

Properties that affect how the various Python build rules work.

[Java]

Properties that affect how the various Java build rules work.

[Cpp]

Properties that affect how the various C++ build rules work.

[Proto]

Properties that affect how the proto_library and grpc_library rules work.

As noted elsewhere, these rules are fairly complex and do a bunch of things internally, so they correspondingly have a lot of options here.

Obviously the various gRPC-related properties only apply to grpc_library rules, whereas proto_library rules are affected by all of them.

[Licences]

Please has a limited ability to detect licences from third-party code. We obviously can't be 100% sure of these due to the complex nature of dependency management formats and the many, many different forms each licence can be described as. Hopefully though this should offer some help in cases where licences can be detected.

[Buildconfig]

This section lets you define arbitrary key-value pairs that can be consumed by custom build rules. For example:

    
    
    [buildconfig]
    rust-toolchain = //third_party/rust:toolchain
    
  

The above can then be read in a .build_def or BUILD file as CONFIG.RUST_TOOLCHAIN, i.e. they are upper-cased and hyphens are converted to underscores.

[Alias]

This section can be used to add custom commands to the plz cli. The section can be repeated multiple times to add many aliases. For example, an alias to run //deployment:deployer with the form plz deploy prod --force //my:target would look like this in the config:

    
    
    [alias "deploy"]
    cmd = run //deployment:deployer --
    subcommand = dev
    subcommand = prod
    subcommand = real prod
    flag = --force
    flag = -f
    positionallabels = true
    
  

The subcommand, flags, and positionallabels values are optional. They aren't enforced in anyway but instead provide tab-completion through the standard Please completions. The positionallabels field adds tab-completion for build labels to the alias which can be useful for those that operate on build targets.

To enable Please completions, add this line to your .bashrc or .zshrc:

    
    
    source <(plz --completion_script)
    
  

Aliases for personal use can be added to your local (personal) please configuration i.e. .plzconfig.local.

[Bazel]

This section defines some settings to help with limited Bazel compatibility.
We don't aspire to be fully compatible and mimic all the semantics of their system, but we hope to ease migration and cross-testing by being able to parse simple repos.

Currently the only attribute here is compatibility, when that is enabled some aspects of the parser behave a little differently; some of the rule names and flags change, //visibility:public is interpreted specially and WORKSPACE files are parsed to find external dependencies. The glob builtin also changes to include hidden files by default.

There is a --bazel_compat flag to plz init which sets this on initialising a new repo.

We don't have a separate setting for it, but switching this on will also allow limited Buck compatibility. Specifically include_defs becomes available and the various C++ rules gain cxx_ aliases.