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

  • .plzconfig
  • .plzconfig_<arch> (e.g. .plzconfig_linux_amd64)
  • /etc/plzconfig
  • .plzconfig.local
One would normally check in .plzconfig (and arch-specific equivalents if needed).
/etc/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 = BUCK
      
Comma-separating on the same line won't 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.
  • 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 (e.g. the debs and install script still use /opt/please).
  • 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, 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.
  • BuildFileName (repeated string)
    Sets the names that Please uses instead of BUILD for its build files.
    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.
  • 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.
  • 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.

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

[Build]

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

[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.
  • DirCacheCleaner
    The binary to use for cleaning the directory cache.
    Defaults to cache_cleaner in the plz install directory.
    Can also be set to the empty string to disable attempting to run it - note that this will of course lead to the dir cache growing without limit which may ruin your day if it fills your disk :)
  • 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.
  • DirCacheLowWaterMark (size)
    When cleaning the directory cache, it's reduced to at most this size.
  • 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).
  • DefaultContainer
    Sets the default type of containerisation to use for tests that are given container = True.
    Currently the only option is "docker" but we intend to add rkt support at some point.

[Cover]

  • FileExtension (repeated string)
    Extensions of files to consider for coverage.
    Defaults to a reasonably obvious set for the builtin rules including .go, .py, .java, etc.
  • 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, etc.

[Metrics]

Options related to metric collection. Currently the only metrics implementation pushes to a Prometheus pushgateway for collection.

  • PushGatewayURL
    The URL of the pushgateway to send metrics to.
  • PushFrequency (integer)
    The frequency, in milliseconds, to push statistics at. Defaults to 100.

[CustomMetricLabels]

Describes optional labels to attach to metrics.
For technical reasons this is a separate section to the main metrics options.

These are defined as key-value pairs, where the key is the label attached to the metric and the value is a command to run on the system that defines the value to attach.
Hence these labels are run once at startup and constant across all build targets.

For example:

branch = git rev-parse --abbrev-ref HEAD
to attach the current git branch to all metrics reported.

In general it's a good idea not to let the cardinality of your labels become too large, so you might want to filter it to only print whether the user is on master or not.

[Docker]

Options relating to tests that are run inside Docker containers.

  • DefaultImage
    The default image used for any test that doesn't specify another.
  • AllowLocalFallback (bool)
    If True, will attempt to run the test locally if containerised running fails.
  • Timeout (int)
    Default timeout for Dockerised tests, in seconds. Default is 1200 (twenty minutes).
  • ResultsTimeout (int)
    Timeout to wait when trying to retrieve results from inside the container. Default is 20 seconds.
  • RemoveTimeout (int)
    Timeout to wait when trying to remove a container after running a test. Defaults to 20 seconds.
  • RunArgs (repeated string)
    Arguments passed to docker run when running a test.

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

  • GoVersion
    String identifying the version of the Go compiler.
    This is only now really important for anyone targeting versions of Go earlier than 1.5 since some of the tool names have changed (6g and 6l became compile and link in Go 1.5).
    We're pretty sure that targeting Go 1.4 works; we're not sure about 1.3 (never tried) but 1.2 certainly doesn't since some of the flags to go tool pack are different. We assume nobody is terribly bothered about this...
  • GoRoot
    If set, will set the GOROOT environment variable appropriately during build actions.
  • GoPath
    If set, will set the GOPATH 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

[Python]

Properties that affect how the various Python build rules work.

  • PipTool
    The tool that is invoked during pip_library rules. Defaults to, well, pip.
  • 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 python but you could of course set it to pypy.
  • 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.
  • 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.
  • 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.
  • PleaseMavenTool
    Defines the tool used to fetch information from Maven in maven_jars rules.
    Defaults to please_maven in the Please install directory.
  • 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.

[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.
  • AsmTool
    The tool invoked as an assembler. Currently only used on OSX for cc_embed_binary rules and so defaults to nasm.
  • 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.
  • DefaultNamespace
    Namespace passed to all cc_embed_binary rules when not overridden by the namespace argument to that rule.
    Not set by default, if you want to use those rules you'll need to set it or pass it explicitly to each one.
  • 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 protoc-gen-grpc-python.
  • 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 all of them!
  • ProtocVersion
    Identifies the version of the protoc compiler. This is mostly there to force a rebuild when it's changed.
    Note that since various incompatibilities can appear with different versions, it's a good idea for this to match the version of the actual compiler at all times.
  • PythonDep
    An in-repo dependency that's applied to any Python targets built.
  • JavaDep
    An in-repo dependency that's applied to any Java targets built.
  • GoDep
    An in-repo dependency that's applied to any Go targets built.
  • GrpcVersion
    Identifies the version of the gRPC compiler. This is mostly there to force a rebuild when it's changed.
    Note that since various incompatibilities can appear with different versions, it's a good idea for this to match the version of the actual compiler at all times.
  • PythonGrpcDep
    An in-repo dependency that's applied to any Python gRPC targets built.
  • JavaGrpcDep
    An in-repo dependency that's applied to any Java gRPC targets built.
  • GoGrpcDep
    An in-repo dependency that's applied to any Go gRPC targets built.

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

[Aliases]

This section lets you define new commands to run at the command line. These are currently implemented as a simple text-based replacement of the original command which limits some applications, but they can still be very useful.

They're written with a simple alias = replacement syntax:


	[aliases]
	deploy = run //deployment:deployer --
    

This would transform plz deploy //src:please into plz run //deployment:deployer -- //src:please.

You can also do subcommands of aliases, with a slightly different syntax:


	[aliases "deploy"]
	dev = run //deployment:deployer -- --env=dev
	prod = run //deployment:deployer -- --env=prod
    

These are then invoked as plz deploy dev and plz deploy prod respectively.
Due to the limitations of parsing our config format, you can only have one level of subcommand of aliases.

[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 dependencies in //external.

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.