Please config file reference

[Please]

• Version

  Defines the version of plz that this repo is supposed to use currently. If it's not present or the version matches the currently running version no special action is taken; otherwise if SelfUpdate is set Please will attempt to download an appropriate version, otherwise it will issue a warning and continue.

  Note that if this is not set, you can run plz update to update to the latest version available on the server.

• VersionChecksum

  Defines a hex-encoded sha256 checksum that the downloaded version must match. Can be specified multiple times to support different architectures.

• Location

  Defines the directory Please is installed into.
  Defaults to ~/.please but you might want it to be somewhere else if you're installing via another method.

• SelfUpdate (bool)

  Sets whether plz will attempt to update itself when the version set in the config file is different.

• DownloadLocation (bool)

  Defines the location to download Please from when self-updating. Defaults to the Please web server (https://get.please.build), but you can point it to some location of your own if you prefer to keep traffic within your network or use home-grown versions.

• Nonce

  This is an arbitrary string that is added to the hash of every build target. It provides a way to force a rebuild of everything when it's changed.
  We will bump the default of this whenever we think it's required - although it's been a pretty long time now and we hope that'll continue.

• NumThreads (int)

  Number of parallel build operations to run.
  Is overridden by the equivalent command-line flag, if that's passed. Defaults to the number of CPUs plus two.

• DefaultRepo

  Location of the please repo to use by default, if not already in a please repo.

• PluginRepo (repeated string)

  A list of template URLS used to download plugins from. The download should be an archive e.g. .tar.gz, or .zip. Templatized variables should be surrounded in curly braces, and the available options are: owner, revision and plugin. Defaults to github and gitlab.

• Autoclean (b ool)

  Automatically clean stale versions without prompting. Defaults to true.

• NumOldVersions (int)

  The number of old versions to keep. Defaults to 10.

• ToolsUrl

  The URL download the Please tools from. Defaults to download the tools from the current Please versions github releases page.

• MOTD

  Message of the day; is displayed once at the top during builds. If multiple are given, one is randomly chosen.

[Parse]

• BuildFileName (repeated string)

  Sets the names that Please uses for its build files. Defaults to BUILD.
  For clarity the documentation refers to them simply as BUILD files but you could reconfigure them here to be something else.
  One case this can be particularly useful is in cases where you have a subdirectory named build on a case-insensitive file system like HFS+.

• BlacklistDirs (repeated string)

  Directories to blacklist when recursively searching for BUILD files (e.g. when using plz build ... or similar).
  This is generally useful when you have large directories within your repo that don't need to be searched, especially things like node_modules that have come from external package managers.

• ExperimentalDir (repeated string)

  Directory containing experimental code. This is subject to some extra restrictions:

  • Code in the experimental dir can override normal visibility constraints
  • Code outside the experimental dir can never depend on code inside it
  • Tests are excluded from general detection

• PreloadBuildDefs (repeated string)

  Files to preload by the parser before loading any BUILD files.
  Since this is done before the first package is parsed they must be files in the repository, they cannot be subinclude() paths.

• PreloadSubincludes (repeated string)

  Subinclude targets to preload by the parser before loading any BUILD files.
  Subincludes can be slow so it's recommended to use PreloadBuildDefs where possible.

• BuildDefsDir (repeated string)

  Tells Please about any directories that contain custom build definitions. These are used by `plz help` to provide help text for build rules that are not built in. Defaults to build_defs.

• NumThreads (int)

  The number of threads to use while parsing the build graph. Default is the number of CPU threads + 2.

• GitFunctions

  Activates built-in functions git_branch, git_commit, git_show and git_state. If disabled they will not be usable at parse time. Defaults to true.

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

• Description (string)

  A description of the plugin. If set, this can be read and output by plz help <plugin>.

• BuildDefsDir (repeatable string)

  Tells Please about any directories in the plugin that contain custom build definitions. These are used by plz help <plugin> to provide help text for build rules that are not built in. Defaults to build_defs.

• DocumentationSite (string)

  A link to where the plugin's documentation is hosted.

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

• ConfigKey

  The key consumers of this plugin will use to set this value in their [Plugin] section.

• DefaultValue

  The default value for this config value, if any.

• Optional (bool)

  If true, this config value may be empty.

• Repeatable (bool)

  If true, this config value may be repeated.

• Inherit (bool)

  If true, this config value will always be inherited by the parent repo, when this repo is a subrepo.

• Type

  The type of this config value. The options are str, int, or bool. Defaults to str.

• Help

  A help string describing what this config property does.

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

• Target (build label)

  The build label for the target that provides the plugin repo.

[Display]

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

• UpdateTitle (bool)

  Whether to update the window title as things are built. This is off by default because while many Linux shells will reset it afterwards, others won't and it's not ideal for us to leave it messed up.

• SystemStats (bool)

  Whether or not to show basic system resource usage in the interactive display. Defaults to False.

• ColourScheme

  Shell colour scheme mode, dark or light. Adapts interactive display colours to the colour scheme mode. Defaults to dark.

• MaxWorkers (int)

  Maximum number of worker rows to display at any one time.

[Colours]

Colour code overrides for the targets in interactive output. These colours are map labels on targets to colours e.g. go -> ${YELLOW}.

[Build]

• Arch

  Architecture to compile for. Defaults to the host architecture.

• Timeout (int)

  Timeout for build operations, in seconds. Defaults to 600 (ten minutes).

• Path (repeated string)

  The PATH variable that will be passed to the build processes.
  Defaults to /usr/local/bin:/usr/bin:/bin but of course can be modified if you need to get binaries from other locations.

• Config

  The build config to use when one is not chosen on the command line. Defaults to opt.

• FallbackConfig

  The build config to use when one is chosen and a required target does not have one by the same name. Also defaults to opt.

• PassEnv (repeated string)

  A list of environment variables to pass from the current environment to build rules. For example PassEnv = HTTP_PROXY would copy your HTTP_PROXY environment variable to the build env for any rules.

• PassUnsafeEnv (repeated string)

  Similar to PassEnv. A list of environment variables to pass from the current environment to build rules. For example PassUnsafeEnv = HTTP_PROXY would copy your HTTP_PROXY environment variable to the build env for any rules. Unlike PassEnv, environment variable values are not used to calculate build target hashes.

• Lang

  Sets the language passed to build rules when building. This can be important for some tools (although hopefully not many) - we've mostly observed it with Sass. Defaults to en_GB.UTF-8.

• DownloadLinkable

  When set, targets with links defined that are built remotely are downloaded. Link definition is usually used to make artifacts available in certain locations for proper tool integration.

  Linkable targets are identified by rules with the following labels: link:destination, hlink:destination, dlink:destination, dhlink:destination and codegen.

• LinkGeneratedSources

  When set, Please will link generated sources back into the source tree. A .gitignore can be generated with plz generate --update_gitignore .gitignore. This can help with getting Please to work with IDEs and tooling. This can be set to hard to generate hard links.

  Generated sources are identified by rules with the codegen label.

• UpdateGitignore

  When set, Please will update the nearest .gitignore with generated sources automatically during builds. This must be used in conjunction with LinkGeneratedSources.

• ArcatTool

  Defines the tool used to concatenate files which we use to build the output of various build rules. Defaults to arcat (formerly jarcat).
  For more information, feel free to purr-use the arcat page here.

• XAttrs

  True (the default) to attempt to use xattrs to record file metadata. If false Please will fall back to using additional files where needed, which is more compatible but has slightly worse performance.

• Nonce

  This is an arbitrary string that is added to the hash of every build target. It provides a way to force a rebuild of everything when it's changed. We will bump the default of this whenever we think it's required - although it's been a pretty long time now and we hope that'll continue.

• HttpProxy

  A URL to use as a proxy server for downloads. Only applies to internal ones - e.g. self-updates or remote_file rules.

• HashCheckers

  Set of hash algos supported by the 'hashes' argument on build rules. Defaults to: sha1,sha256,blake3.

• HashFunction

  The hash function to use internally for build actions.

• ExitOnError (bool)

  True to have build actions automatically fail on error (essentially passing -e to the shell they run in).

• ParallelDownloads (int)

  Max number of remote_file downloads to run in parallel.

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

• Tool

  The binary to use for sandboxing build/test actions. Typically this is please_sandbox, which currently only does anything on Linux.
  It receives the program to execute and all its arguments in its argv, it is expected to do whatever it needs to then exec the real action.

• Build (bool)

  Activates sandboxing for build actions, which isolates them from network access, IPC and the repo-local filesystem. Currently only works on Linux. Defaults to False.

• Test (bool)

  Activates sandboxing for test actions, which isolates them from network access, IPC and the repo-local filesystem. Currently only works on Linux. Defaults to False.

• Dir (repeated string)

  Directories that the sandbox tool should mask (it's unspecified how, although mounting an empty filesystem over the top is the current implementation).
  These are passed to the tool itself in the SANDBOX_DIRS env var as a comma-separated list.

• Namespace (bool)

  Set to 'always', to namespace all actions. Set to 'sandbox' to namespace only when sandboxing the build action. Defaults to 'never', under the assumption the sandbox tool will handle its own namespacing. If set, user namespacing will be enabled for all rules. Mount and network will only be enabled if the rule is to be sandboxed.

• ExcludeableTargets (repeated build label)

  If set, only targets that match these wildcards will be allowed to opt out of the sandbox. Values can be wildcards, e.g. //third_party/...

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]

• URL

  Sets the URL to communicate with the remote server on.
  Typically this would look something like 127.0.0.1:8989, i.e. it is given without a protocol.

• Instance

  Defines the name of the remote instance to request. Depending on the server implementation or configuration this may be required; if so it must be set here to agree with it.

• NumExecutors (int)

  Defines the number of remote executors to use simultaneously.

• Name

  A name for this worker instance. This is informational only and attached to artifacts uploaded to remote storage to identify the original machine that created them.

• CasUrl

  URL for the CAS service, if it is different to the main one.

• AssetUrl

  URL for the remote asset server, if it is different to the main one.

• DisplayUrl

  A URL to browse the remote server with (e.g. using buildbarn-browser). Only used when printing hashes.

• TokenFile

  A file containing a token that is attached to outgoing RPCs to authenticate them. This is somewhat bespoke; we are still investigating further options for authentication.

• Timeout (int)

  Timeout for connections made to the remote server.

• Secure (bool)

  Whether to use TLS for communication or not.

• VerifyOutputs (bool)

  Whether to verify all outputs are present after a cached remote execution action. Depending on your server implementation, you may require this to ensure files are really present.

• UploadDirs (bool)

  Uploads individual directory blobs after build actions. This might not be necessary with some servers, but if you aren't sure, you should leave it on.

• OptionalOutputsRequired (bool)

  Requires that any optional outputs of build actions (optional test outputs, coverage when not opted out of) are produced. By default this is a non-fatal failure, but the actions may not cache remotely.

• Shell

  Path to the shell to use to execute actions in. Default is 'bash' which will be looked up by the server.

• Platform (repeated string)

  Platform properties to request from remote workers, in the format key=value.

• CacheDuraction (int)

  Length of time before we re-check locally cached build actions. Default is unlimited.

• BuildId

  ID of the build action that's being run, to attach to remote requests. If not set then one is automatically generated.

[Cache]

• Dir

  Sets the directory to use for the dir cache.
  The default is .plz-cache, if set to the empty string the dir cache will be disabled.

• DirCacheHighWaterMark (size)

  Starts cleaning the directory cache when it is over this number of bytes.
  Can also be given with human-readable suffixes like 10G, 200MB etc. Defaults to 10GiB.

• DirCacheLowWaterMark (size)

  When cleaning the directory cache, it's reduced to at most this size. Defaults to 8GiB.

• HttpUrl

  Base URL of the HTTP cache.
  Not set to anything by default which means the cache will be disabled.

• HttpWriteable (bool)

  If True this plz instance will write content back to the HTTP cache.
  By default it runs in read-only mode.

• HttpTimeout (int)

  Timeout for operations contacting the HTTP cache, in seconds.

• Workers

  Number of workers for uploading artifacts to remote caches, which is done asynchronously.

• DirClean (bool)

  Controls whether entries in the dir cache are cleaned or not. If disabled the cache will only grow.

• DirCompress (bool)

  Compresses stored artifacts in the dir cache. They are slower to store & retrieve but more compact.

• HttpConcurrentRequestLimit (int)

  The maximum amount of concurrent requests that can be open. Default 20.

• HttpRetry (int)

  The maximum number of retries before a request will give up, if a request is retryable

• RetrieveCommand

  Use a custom command to retrieve cache entries.
  Disabled by default.

• StoreCommand

  Use a custom command to store cache entries.
  Disabled by default. You can only enable it together with RetrieveCommand.

[Size]

Named sizes of targets; these are the definitions of what can be passed to the 'size' argument.

• Timeout (int)

  Timeout for targets of this size

• TimeoutName

  Name of the timeout, to be passed to the 'timeout' argument

[Test]

• Timeout (int)

  Sets the default timeout length, in seconds, for any test that isn't explicitly given one. Defaults to 600 (10 minutes).

• DisableCoverage (repeated string)

  Disables coverage for tests that have any of these labels specified.

• Upload (string)

  URL to upload test results to. The request is a POST containing the results in XML format.

• UploadGzipped (bool)

  True to upload the test results gzipped.

• StoreTestOutputOnSuccess (bool)

  True to store stdout and stderr in the test results for successful tests.

[Cover]

• FileExtension (repeated string)

  Extensions of files to consider for coverage.\nDefaults to .go, .py, .java, .tsx, .ts, .js, .cc, .h, and .c.

• ExcludeExtension (repeated string)

  Extensions of files to exclude from coverage.
  Typically this is for generated code; the default is to exclude protobuf extensions like .pb.go, _pb2.py. Defaults to .pb.go, .spec.tsx, .spec.ts, .spec.js, _pb2.py, .pb.cc, .pb.h, _test.py, _test.go, _pb.go, _bindata.go, and _test_main.cc.

• ExcludeGlob(repeated string)

  Exclude glob pattern from coverage.
  Typically this is for generated code and it is useful when there is no other discrimination possible.

[Gc]

Options relating to use of plz gc.

• Keep (build label)

  Marks targets that gc should always keep. Can include meta-targets such as //test/... and //docs:all.

• KeepLabel

  Defines a target label to be kept; for example, if you set this to go, no Go targets would ever be considered for deletion.

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

• Cmd

  The actual command to run. Will be prefixed by `plz` and all arguments will be passed to this literally.

• Subcommand (repeated string)

  Any subcommands of this alias. Used for tab completion.

• Flag (repeated string)

  Any flags of this alias. Used for tab completion.

• PositionalLabels (repeated string)

  Whether this alias's positional arguments are build labels.

• Desc

  Description of this alias

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.

• PipTool

  The tool that is invoked during pip_library rules. Defaults to pip3.

• PexTool

  The tool that's invoked to build pexes. Defaults to please_pex in the install directory.

• DefaultInterpreter

  The interpreter used for python_binary and python_test rules when none is specified on the rule itself. This can also be the name of a build target, in which case the generated binary should accept the same command line options as the Python interpreter. Defaults to python3.

• TestRunner

  The test runner used to discover & run Python tests; one of unittest, pytest or behave. Defaults to unittest.

• TestRunnerBootstrap

  Target providing test-runner library and its transitive dependencies. Injects plz-provided bootstraps if not given.

• Debugger

  Sets what debugger to use to debug Python binaries. The available options are: 'pdb' (default) and 'debugpy'.

• ModuleDir

  Defines a directory containing modules from which they can be imported at the top level.
  By default this is empty but by convention we define our pip_library rules in third_party/python and set this appropriately. Hence any of those third-party libraries that try something like import six will have it work as they expect, even though it's actually in a different location within the .pex.

• DefaultPipRepo

  Defines a location for a pip repo to download wheels from.
  By default pip_library uses PyPI (although see below on that) but you may well want to use this define another location to upload your own wheels to.
  Is overridden by the repo argument to pip_library.

• WheelRepo

  Defines a location for a remote repo that python_wheel rules will download from. See python_wheel for more information.

• UsePyPI (bool)

  Whether or not to use PyPI for pip_library rules or not. Defaults to True, if you disable this you will presumably want to set DefaultPipRepo to use one of your own.
  Is overridden by the use_pypi argument to pip_library.

• WheelNameScheme

  Defines a custom templatized wheel naming scheme.
  Templatized variables should be surrounded in curly braces within the scheme, and the available options are: url_base, package_name, and version. The default search pattern is {url_base}/{package_name}-{version}-${{OS}}-${{ARCH}}.whl along with a few common variants.

• DisableVendorFlags (bool)

  Disables injection of vendor specific flags for pip while using pip_library. The option can be useful if you are using something like Pyenv, and the passing of additional flags or configuration that are vendor specific, e.g. --system, breaks your build.

• PipFlags

  Additional flags to pass to pip invocations in pip_library rules.

• InterpreterOptions

  Options to pass to the python interpeter, when writing shebangs for pex executables.

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

• Accept (repeated string)

  Licences that are accepted in this repository.
  When this is empty licences are ignored. As soon as it's set any licence detected or assigned must be accepted explicitly here.
  There's no fuzzy matching, so some package managers (especially PyPI and Maven, but shockingly not npm which rather nicely uses SPDX) will generate a lot of slightly different spellings of the same thing, which will all have to be accepted here. We'd rather that than trying to "cleverly" match them which might result in matching the wrong thing.

• Reject

  Licences that are explicitly rejected in this repository.
  An astute observer will notice that this is not very different to just not adding it to the accept section, but it does have the advantage of explicitly documenting things that the team aren't allowed to use.

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