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):
/etc/please/plzconfig
~/.config/please/plzconfig
.plzconfig
.plzconfig_<arch>
(e.g.
.plzconfig_linux_amd64
)
.plzconfig.local
Profile-specific config files can be defined and take precedence over the config file being
evaluated. 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.
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.
Defines a hex-encoded sha256 checksum that the downloaded version must match. Can be specified multiple times to support different architectures.
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.
Sets whether plz will attempt to update itself when the version set in the config file is different.
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.
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.
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.
Location of the please repo to use by default, if not already in a please repo.
{{ index .ConfigHelpText "please.pluginrepo" }}
Automatically clean stale versions without prompting. Defaults to true.
The number of old versions to keep. Defaults to 10.
{{ index .ConfigHelpText "please.toolsurl" }}
{{ index .ConfigHelpText "please.motd" }}
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+.
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.
Directory containing experimental code. This is subject to some extra restrictions:
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.
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.
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
.
The number of threads to use while parsing the build graph. Default is the number of CPU threads + 2.
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.
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
.
A description of the plugin. If set, this can be read and output by
plz help <plugin>
.
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
.
A link to where the plugin's documentation is hosted.
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.
The key consumers of this plugin will use to set this value in their [Plugin] section.
The default value for this config value, if any.
If true, this config value may be empty.
If true, this config value may be repeated.
If true, this config value will always be inherited by the parent repo, when this repo is a subrepo.
The type of this config value. The options are str
, int
,
or bool
. Defaults to str
.
A help string describing what this config property does.
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.
{{ index .ConfigHelpText "plugin.target" }}
Contains options relating to display output. These have no impact on build output.
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.
Whether or not to show basic system resource usage in the interactive
display. Defaults to False
.
Shell colour scheme mode, dark or light. Adapts interactive display
colours to the colour scheme mode. Defaults to
dark
.
{{ index .ConfigHelpText "display.maxworkers" }}
{{ index .ConfigHelpText "colours" }}
Architecture to compile for. Defaults to the host architecture.
Timeout for build operations, in seconds. Defaults to 600 (ten minutes).
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.
The build config to use when one is not chosen on the command line.
Defaults to opt
.
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
.
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.
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.
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
.
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
.
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.
When set, Please will update the nearest .gitignore
with generated sources
automatically during builds. This must be used in conjunction with LinkGeneratedSources.
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.
{{ index .ConfigHelpText "build.xattrs" }}
{{ index .ConfigHelpText "build.nonce" }}
{{ index .ConfigHelpText "build.httpproxy" }}
{{ index .ConfigHelpText "build.hashcheckers" }}
{{ index .ConfigHelpText "build.hashfunction" }}
{{ index .ConfigHelpText "build.exitonerror" }}
{{ index .ConfigHelpText "build.paralleldownloads" }}
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.
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.
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
.
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
.
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.
{{ index .ConfigHelpText "sandbox.namespace" }}
{{ index .ConfigHelpText "sandbox.excludeabletargets" }}. Values can be wildcards, e.g.
//third_party/...
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.
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.
Defines the number of remote executors to use simultaneously.
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.
{{ index .ConfigHelpText "remote.casurl" }}
{{ index .ConfigHelpText "remote.asseturl" }}
{{ index .ConfigHelpText "remote.displayurl" }}
{{ index .ConfigHelpText "remote.tokenfile" }}
{{ index .ConfigHelpText "remote.timeout" }}
{{ index .ConfigHelpText "remote.secure" }}
{{ index .ConfigHelpText "remote.verifyoutputs" }}
{{ index .ConfigHelpText "remote.uploaddirs" }}
{{ index .ConfigHelpText "remote.shell" }}
{{ index .ConfigHelpText "remote.platform" }}
{{ index .ConfigHelpText "remote.cacheduration" }}
{{ index .ConfigHelpText "remote.buildid" }}
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.
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
.
When cleaning the directory cache, it's reduced to at most this size.
Defaults to 8GiB
.
Base URL of the HTTP cache.
Not set to anything by default which means the cache will be disabled.
If True this plz instance will write content back to the HTTP
cache.
By default it runs in read-only mode.
Timeout for operations contacting the HTTP cache, in seconds.
{{ index .ConfigHelpText "cache.workers" }}
{{ index .ConfigHelpText "cache.dirclean" }}
{{ index .ConfigHelpText "cache.dircompress" }}
{{ index .ConfigHelpText "cache.httpconcurrentrequestlimit" }}
{{ index .ConfigHelpText "cache.httpretry" }}
Use a custom command to retrieve cache entries.
Disabled by default.
Use a custom command to store cache entries.
Disabled by default. You can only enable it together with RetrieveCommand.
{{ index .ConfigHelpText "size" }}
{{ index .ConfigHelpText "size.timeout" }}
{{ index .ConfigHelpText "size.timeoutname" }}
Sets the default timeout length, in seconds, for any test that isn't explicitly given one. Defaults to 600 (10 minutes).
Disables coverage for tests that have any of these labels specified.
URL to upload test results to. The request is a POST containing the results in XML format.
{{ index .ConfigHelpText "test.uploadgzipped" }}
{{ index .ConfigHelpText "test.storetestoutputonsuccess" }}
Extensions of files to consider for coverage.\nDefaults to
.go
, .py
,
.java
, .tsx
,
.ts
, .js
,
.cc
, .h
, and
.c
.
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
.
Exclude glob pattern from coverage.
Typically this is for generated code and it is useful when there is no other discrimination possible.
Options relating to use of plz gc
.
Marks targets that gc should always keep. Can include meta-targets
such as //test/...
and
//docs:all
.
Defines a target label to be kept; for example, if you set this to
go
, no Go targets would ever be considered
for deletion.
This section can be used to add custom commands to the plz cli. The section can be repeated multiple times to add many aliases.
The actual command to run. Will be prefixed by `plz` and all arguments will be passed to this literally.
Any subcommands of this alias. Used for tab completion.
Any flags of this alias. Used for tab completion.
Whether this alias's positional arguments are build labels.
{{ index .ConfigHelpText "alias.desc" }}
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
.
Properties that affect how the various Python build rules work.
The tool that is invoked during
pip_library
rules. Defaults to
pip3
.
The tool that's invoked to build pexes. Defaults to
please_pex
in the install directory.
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
.
The test runner used to discover & run Python tests; one of
unittest
,
pytest
or behave
.
Defaults to unittest
.
{{ index .ConfigHelpText "python.testrunnerbootstrap" }}
{{ index .ConfigHelpText "python.debugger" }}
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.
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
.
Defines a location for a remote repo that python_wheel rules will download from. See python_wheel for more information.
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
.
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.
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.
{{ index .ConfigHelpText "python.pipflags" }}
{{ index .ConfigHelpText "python.interpreteroptions" }}
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.
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.
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.
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.
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.