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

Profile-specific config files can be defined and take precedence over the config file being evaluated. Except .plzconfig.local which always has highest precedence. This is achieved by having a sibling config file with the name ending with the profile name (i.e. .plzconfig.remote, .plzconfig_linux_amd64.remote, etc.) and running the command with the --profile flag set (ie. --profile=remote).

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]

[PluginDefinition]

This feature is still experimental; some aspects may not work fully or at all just yet. Proceed with caution!

Used in repos that implement a Please plugin. By adding this section to your .plzconfig, your project can be included as a plugin in other Please repos.

The following sets up a plugin with ID foo.

    
    
    [PluginDefinition]
    Name = foo

    [PluginConfig "foo_tool"]
    ConfigKey = FooTool
    ; It is resolved relative to the subrepo for this plugin
    DefaultValue = //tools:foo
    
  

Another Please repo can then override these values as such:

    
    
    [Plugin "foo"]
    FooTool = foo_tool
    
  

This config value is then available to the build definitions as CONFIG.FOO.FOO_TOOL.

[PluginConfig "config_key"]

This feature is still experimental; some aspects may not work fully or at all just yet. Proceed with caution!

Used in conjunction with [PluginDefinition] to define configuration values for a plugin.

[Plugin "plugin-id"]

This feature is still experimental; some aspects may not work fully or at all just yet. Proceed with caution!

This section can be used to define configuration specific to a plugin identified by its ID.

[Display]

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

[Colours]

{{ index .ConfigHelpText "colours" }}

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

[Sandbox]

N.B. On Ubuntu Noble (24.04) or later, sandboxing may fail with a "Permission denied" error (often referring to /proc/self/setgroups). This is due to a security change which prohibits unprivileged user namespaces, which the sandboxing relies upon.
To fix this, you need to create an AppArmor profile allowing it; we have an example for the default install location, which you should copy to /etc/apparmor.d/build.please, then run sudo systemctl reload apparmor to apply the new profile.

[Remote]

[Cache]

[Size]

{{ index .ConfigHelpText "size" }}

[Test]

[Cover]

[Gc]

Options relating to use of plz gc.

[Alias "name"]

This section can be used to add custom commands to the plz cli. The section can be repeated multiple times to add many aliases.

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.

[Python]

Properties that affect how the various Python build rules work.

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

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