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):
/etc/please/plzconfig
~/.config/please/plzconfig
.plzconfig
.plzconfig_<arch>
(e.g. .plzconfig_linux_amd64)
.plzconfig.<profile>
(if the --profile
flag is passed)
.plzconfig.local
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]
- 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
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.
[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.
[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 (string)
Shell colour scheme mode, dark or light. Adapts interactive display colours to the colour scheme mode.
Defaults to dark
.
[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.
- Sandbox (bool)
Activates sandboxing for individual build actions, which isolates them from network
access, IPC and some aspects of the filesystem. Currently only works on Linux.
Defaults to False
.
- 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
.
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.
This whole section is still experimental; some settings may not
work fully and as a whole it's subject to change. Proceed with caution!
- 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.
- 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.
- RpcUrl
Base URL of the RPC cache.
Not set to anything by default which means the cache will be disabled.
- RpcWriteable (bool)
If True this plz instance will write content back to the RPC cache.
By default it runs in read-only mode.
- RpcTimeout (int)
Timeout for operations contacting the RPC cache, in seconds.
- RpcMaxMsgSize (bytes)
Maximum size of a single message that we'll send to the RPC server.
This should agree with the server's limit, if it's higher the artifacts will be rejected.
The value is given as a byte size so can be suffixed with M, GB, KiB, etc.
[Test]
- Timeout (int)
Sets the default timeout length, in seconds, for any test that isn't explicitly given one.
Defaults to 600 (10 minutes).
- Sandbox (bool)
Activates sandboxing for individual tests, which isolates them from network
access, IPC and some aspects of the filesystem. Currently only works on Linux.
Defaults to False
.
- 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.
[Cover]
- FileExtension (repeated string)
Extensions of files to consider for coverage.
Defaults to .go
, .py
, .java
,
.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
, _pb2.py
, .pb.cc
,
.pb.h
, _test.py
, _test.go
,
_pb.go
, _bindata.go
, and _test_main.cc
.
[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.
[Go]
Properties that affect how the various Go build rules work.
- ImportPath
String name of the canonical path of this repository.
This path is used as the prefix of the package name relative to this please
build directory.
importpath
is commonly used to prepend github.com/myorg/myrepo
to a project's
path.
- GoPath
If set, will set the GOPATH environment variable appropriately during build actions.
- GoTool
If set, the binary name to use to invoke Go & its subtools with.
Defaults to go
.
- GoRoot
If set, will set the GOROOT environment variable appropriately during build actions.
- TestTool
Sets the location of the please_go_test
tool that is used to template the test
main for go_test
rules.
- CgoCCTool
Sets the location of CC
while building cgo_library
and cgo_test
rules. Defaults to gcc
- FilterTool
Sets the location of the please_go_filter
tool that is used to filter source
files against build constraints.
- DefaultStatic (bool)
Sets Go binaries to default to static linking. Note that enabling this may have negative
consequences for some code, including Go's DNS lookup code in the net module.
[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. Defaults to python3
but you could of course set it to
pypy
.
- TestRunner
The test runner used to discover & run Python tests; one of unittest
,
pytest
or behave
. Defaults to unittest
.
- 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 (string)
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.
[Java]
Properties that affect how the various Java build rules work.
- JavacTool
Defines the tool used for the Java compiler. Defaults to javac
.
- JlinkTool
Defines the tool used for the Java linker. Defaults to jlink
.
- JavaHome
Defines the Java home folder.
- JarTool
Defines the tool used to build a .jar. Defaults to jar
.
- JarcatTool
Defines the tool used to concatenate .jar files which we use to build the output
of java_binary
and java_test
.Defaults to jarcat
in the Please install directory.
Any resemblance to
this
or this
is purr-ly coincidental.
- DefaultMavenRepo
Default location to load artifacts from in maven_jar rules.
- JUnitRunner
Defines the .jar containing the JUnit runner. This is built into all java_test
rules
since it's necessary to make JUnit do anything useful.
Defaults to junit_runner.jar
in the Please install directory.
- DefaultTestPackage
The Java classpath to search for functions annotated with @Test
.
- SourceLevel (int)
The default Java source level when compiling. Defaults to 8.
- TargetLevel (int)
The default Java bytecode level to target. Defaults to 8.
- ReleaseLevel (int)
The default Java release level when compiling.
SourceLevel and TargetLevel are ignored if this is set.
Bear in mind that this flag is only supported in Java version 9+.
[Cpp]
Properties that affect how the various C++ build rules work.
- CCTool
The tool invoked to compile C code. Defaults to gcc
but you might
want to set it to clang
, for example.
- CppTool
The tool invoked to compile C++ code. Defaults to g++
but you might
want to set it to clang++
, for example.
- LdTool
The tool invoked to link object files. Defaults to ld
but you could
also set it to gold
, for example.
- ArTool
The tool invoked to archive static libraries. Defaults to ar
.
- LinkWithLdTool
If true, instructs Please to use the tool set earlier in ldtool
to link binaries instead of cctool
.
This is an esoteric setting that most people don't want; a vanilla ld
will not perform all steps necessary here (you'll get lots of missing symbol messages
from having no libc etc). Generally best to leave this disabled.
- DefaultOptCflags
Compiler flags passed to all C rules during opt
builds;
these are typically pretty basic things like
what language standard you want to target, warning flags, etc.
Defaults to --std=c99 -O3 -DNDEBUG -Wall -Werror
- DefaultDbgCflags
Compiler rules passed to all C rules during dbg
builds.
Defaults to --std=c99 -g3 -DDEBUG -Wall -Werror
.
- DefaultOptCppflags
Compiler flags passed to all C++ rules during opt
builds;
these are typically pretty basic things like
what language standard you want to target, warning flags, etc.
Defaults to --std=c++11 -O3 -DNDEBUG -Wall -Werror
- DefaultDbgCppflags
Compiler rules passed to all C++ rules during dbg
builds.
Defaults to --std=c++11 -g3 -DDEBUG -Wall -Werror
.
- DefaultLdFlags
Linker flags passed to all C++ rules.
By default this is empty.
- Coverage
If true (the default), coverage will be available for C and C++ build rules.
This is still a little experimental but should work for GCC. Right now it does
not work for Clang (it likely will in Clang 4.0 which will likely support
--fprofile-dir
) and so this can be useful to disable it.
It's also useful in some cases for CI systems etc if you'd prefer to avoid the overhead,
since the tests have to be compiled with extra instrumentation and without optimisation.
[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.
- ProtocTool
The binary invoked to compile .proto files. Defaults to protoc
.
- ProtocGoPlugin
The binary passed to protoc as a plugin to generate Go code. Defaults to
protoc-gen-go
.
We've found this easier to manage with a go_get
rule instead
though, so you can also pass a build label here. See the Please repo for an example.
- GrpcPythonPlugin
The plugin invoked to compile Python code for grpc_library
.
Defaults to grpc_python_plugin
.
- GrpcJavaPlugin
The plugin invoked to compile Java code for grpc_library
.
Defaults to protoc-gen-grpc-java
.
- Language (repeated string)
Sets the default set of languages that proto rules are built for.
Chosen from the set of {cc
, java
, go
,
py
}.
Defaults to multiple Language
lines, one line for each of
the following values: cc
, py
, java
,
go
, and js
.
- PythonDep
An in-repo dependency that's applied to any Python targets built.
Defaults to //third_party/python:protobuf
.
- JavaDep
An in-repo dependency that's applied to any Java targets built.
Defaults to //third_party/java:protobuf
.
- GoDep
An in-repo dependency that's applied to any Go targets built.
Defaults to //third_party/go:protobuf
.
- PythonGrpcDep
An in-repo dependency that's applied to any Python gRPC targets built.
Defaults to //third_party/python:grpc
.
- JavaGrpcDep
An in-repo dependency that's applied to any Java gRPC targets built.
Defaults to /third_party/java:grpc-all
.
- GoGrpcDep
An in-repo dependency that's applied to any Go gRPC targets built.
Defaults to //third_party/go:grpc
.
[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.
[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.