github.com/sercand/please@v13.4.0+incompatible/docs/config.html

    <h1>Please config file reference</h1>

    <p>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.</p>

    <p>Please looks in several locations for these files and builds it up bit by bit. In order
      (from lowest priority to highest):
      <ul>
        <li><code>/etc/plzconfig</code></li>
        <li><code>~/.please/plzconfig</code></li>
        <li><code>.plzconfig</code></li>
        <li><code>.plzconfig_&lt;arch&gt;</code> (e.g. .plzconfig_linux_amd64)</li>
        <li><code>.plzconfig.&lt;profile&gt;</code> (if the <code>--profile</code> flag is passed)</li>
        <li><code>.plzconfig.local</code></li>
      </ul>
      One would normally check in <code>.plzconfig</code> (and arch-specific equivalents if needed).<br/>
      <code>/etc/plzconfig</code> is there to facilitate per-machine config in cases where the repo is often
      deleted - this is quite common in CI systems.<br/>
      Finally you normally add <code>.plzconfig.local</code> to .gitignore to allow people to override
      settings locally if needed.</p>

    <p>The file format is very similar to
      <a href="https://git-scm.com/docs/git-config#_syntax">Git's config</a>; it's broken into
      sections by headers in square brackets, and each section contains <code>option = value</code>
      pairs. Comments start with a semicolon.</p>

    <p>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 <code>true</code>, <code>false</code>, <code>yes</code>, <code>no</code> etc).<br/>
      Various parameters can be repeated (they're noted as such below); this means passing them
      multiple times in their entirety, e.g.
      <pre><code>
          buildfilename = BUILD
          buildfilename = BUCK
      </code></pre>
      Comma-separating on the same line won't work.</p>

    <h3>[Please]</h3>

    <ul>
      <li><b>Version</b><br/>
        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 <code>SelfUpdate</code> is set Please will attempt to download an appropriate
        version, otherwise it will issue a warning and continue.<br/><br/>

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

      <li><b>Location</b><br/>
        Defines the directory Please is installed into.<br/>
        Defaults to <code>~/.please</code> 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 <code>/opt/please</code>).</li>

      <li><b>SelfUpdate</b> (bool)<br/>
        Sets whether plz will attempt to update itself when the version set in the config file is
        different.</li>

      <li><b>DownloadLocation</b><br/>
        Defines the location to download Please from when self-updating. Defaults to the Please
        web server (<code>https://get.please.build</code>), 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.</li>

      <li><b>Lang</b><br/>
        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 <code>en_GB.UTF-8</code>.</li>

      <li><b>Nonce</b><br/>
        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.<br/>
        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.</li>

      <li><b>NumThreads</b> (int)<br/>
        Number of parallel build operations to run.<br/>
        Is overridden by the equivalent command-line flag, if that's passed.
        Defaults to the number of CPUs plus two.</li>
    </ul>

    <h3>[Parse]</h3>

    <ul>
      <li><b>BuildFileName</b> (repeated string)<br/>
        Sets the names that Please uses for its build files.  Defaults to <code>BUILD</code>.<br/>
        For clarity the documentation refers to them simply as BUILD files but you could
        reconfigure them here to be something else.<br/>
        One case this can be particularly useful is in cases where you have a subdirectory named
        <code>build</code> on a case-insensitive file system like HFS+.</li>

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

      <li><b>ExperimentalDir</b> (repeated string)<br/>
        Directory containing experimental code. This is subject to some extra restrictions:
        <ul>
          <li>Code in the experimental dir can override normal visibility constraints</li>
          <li>Code outside the experimental dir can never depend on code inside it</li>
          <li>Tests are excluded from general detection</li>
        </ul>
      </li>

      <li><b>PreloadBuildDefs</b> (repeated string)<br/>
        Files to preload by the parser before loading any BUILD files.<br/>
        Since this is done before the first package is parsed they must be files in the
        repository, they cannot be <code>subinclude()</code> paths.</li>
    </ul>

    <h3>[Display]</h3>

    <p>Contains options relating to display output. These have no impact on build output.</p>

    <ul>
      <li><b>UpdateTitle</b> (bool)<br/>
	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.</li>

      <li><b>SystemStats</b> (bool)<br/>
	Whether or not to show basic system resource usage in the interactive display.
        Defaults to <code>False</code>.</li>
    </ul>

    <h3>[Build]</h3>

    <ul>

      <li><b>Arch</b><br/>
        Architecture to compile for. Defaults to the host architecture.</li>

      <li><b>Timeout</b> (int)<br/>
        Timeout for build operations, in seconds. Defaults to 600 (ten minutes).</li>

      <li><b>Path</b> (repeated string)<br/>
        The PATH variable that will be passed to the build processes.<br/>
        Defaults to <code>/usr/local/bin:/usr/bin:/bin</code> but of course can be modified if
        you need to get binaries from other locations.</li>

      <li><b>Config</b><br/>
        The build config to use when one is not chosen on the command line. Defaults to <code>opt</code>.</li>

      <li><b>FallbackConfig</b><br/>
        The build config to use when one is chosen and a required target does not have
        one by the same name. Also defaults to <code>opt</code>.</li>

      <li><b>PassEnv</b> (repeated string)<br/>
        A list of environment variables to pass from the current environment to build rules. For example
        <code>PassEnv = HTTP_PROXY</code>
        would copy your HTTP_PROXY environment variable to the build env for any rules.</li>

      <li><b>Sandbox</b> (bool)<br/>
        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 <code>False</code>.</li>

    </ul>

    <h3>[Cache]</h3>

    <ul>

      <li><b>Dir</b><br/>
        Sets the directory to use for the dir cache.<br/>
        The default is <code>.plz-cache</code>, if set to the empty string the dir cache will
        be disabled.</li>

      <li><b>DirCacheHighWaterMark</b> (size)<br/>
        Starts cleaning the directory cache when it is over this number of bytes.<br/>
        Can also be given with human-readable suffixes like 10G, 200MB etc.
        Defaults to <code>10GiB</code>.</li>

      <li><b>DirCacheLowWaterMark</b> (size)<br/>
        When cleaning the directory cache, it's reduced to at most this size.
        Defaults to <code>8GiB</code>.</li>

      <li><b>HttpUrl</b><br/>
        Base URL of the HTTP cache.<br/>
        Not set to anything by default which means the cache will be disabled.</li>

      <li><b>HttpWriteable</b> (bool)<br/>
        If True this plz instance will write content back to the HTTP cache.<br/>
        By default it runs in read-only mode.</li>

      <li><b>HttpTimeout</b> (int)<br/>
        Timeout for operations contacting the HTTP cache, in seconds.</li>

      <li><b>RpcUrl</b><br/>
        Base URL of the RPC cache.<br/>
        Not set to anything by default which means the cache will be disabled.</li>

      <li><b>RpcWriteable</b> (bool)<br/>
        If True this plz instance will write content back to the RPC cache.<br/>
        By default it runs in read-only mode.</li>

      <li><b>RpcTimeout</b> (int)<br/>
        Timeout for operations contacting the RPC cache, in seconds.</li>

      <li><b>RpcMaxMsgSize</b> (bytes)<br/>
        Maximum size of a single message that we'll send to the RPC server.<br/>
        This should agree with the server's limit, if it's higher the artifacts will be rejected.<br/>
        The value is given as a byte size so can be suffixed with M, GB, KiB, etc.</li>

    </ul>

    <h3>[Test]</h3>

    <ul>
      <li><b>Timeout</b> (int)<br/>
        Sets the default timeout length, in seconds, for any test that isn't explicitly given one.
        Defaults to 600 (10 minutes).</li>

      <li><b>DefaultContainer</b><br/>
        Sets the default type of containerisation to use for tests that are given
        <code>container = True</code>.<br/>
        Currently the only option is "docker" but we intend to add rkt support at some point.</li>

      <li><b>Sandbox</b> (bool)<br/>
        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 <code>False</code>.</li>
    </ul>

    <h3>[Cover]</h3>

    <ul>
      <li><b>FileExtension</b> (repeated string)<br/>
        Extensions of files to consider for coverage.<br/>
        Defaults to <code>.go</code>, <code>.py</code>, <code>.java</code>,
        <code>.js</code>, <code>.cc</code>, <code>.h</code>, and <code>.c</code>.</li>

      <li><b>ExcludeExtension</b> (repeated string)<br/>
        Extensions of files to exclude from coverage.<br/>
        Typically this is for generated code; the default is to exclude protobuf extensions like
        <code>.pb.go</code>, <code>_pb2.py</code>.
        Defaults to <code>.pb.go</code>, <code>_pb2.py</code>, <code>.pb.cc</code>,
        <code>.pb.h</code>, <code>_test.py</code>, <code>_test.go</code>,
        <code>_pb.go</code>, <code>_bindata.go</code>, and <code>_test_main.cc</code>.</li>
    </ul>

    <h3>[Metrics]</h3>

    <p>Options related to metric collection. Currently the only metrics implementation pushes
      to a <a href="https://prometheus.io/">Prometheus</a>
      <a href="https://github.com/prometheus/pushgateway">pushgateway</a> for collection.</p>

    <ul>
      <li><b>PushGatewayURL</b><br/>
	    The URL of the pushgateway to send metrics to.</li>

      <li><b>PushFrequency</b> (duration)<br/>
	    The frequency to push statistics at. Defaults to 400ms.</li>

      <li><b>PushTimeout</b> (duration)<br/>
	    The timeout for metric pushes. Defaults to 500ms.</li>

      <li><b>PerTest</b> (bool)<br/>
	    Emit per-test duration metrics. Off by default, they can be very useful but generate
        larger cardinalities of labels in Prometheus.</li>

      <li><b>PerUser</b> (bool)<br/>
	    Emit per-user metric labels. On by default, but turning it off can reduce the amount of
        data to be stored.</li>
    </ul>

    <h3>[CustomMetricLabels]</h3>

    <p>Describes optional labels to attach to metrics.<br/>
      For technical reasons this is a separate section to the main metrics options.</p>

    <p>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.<br/>
      Hence these labels are run once at startup and constant across all build targets.</p>

    <p>For example:<br/>
      <pre><code>branch = git rev-parse --abbrev-ref HEAD</code></pre>
      to attach the current git branch to all metrics reported.</p>

    <p>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.</p>

    <h3>[Docker]</h3>

    <p>Options relating to tests that are run inside Docker containers.</p>

    <ul>
      <li><b>DefaultImage</b><br/>
        The default image used for any test that doesn't specify another.
        Defaults to <code>ubuntu:trusty</code>.</li>

      <li><b>AllowLocalFallback</b> (bool)<br/>
        If True, will attempt to run the test locally if containerised running fails.
        Defaults to <code>False</code>.</li>

      <li><b>Timeout</b> (int)<br/>
        Default timeout for Dockerised tests, in seconds. Default is 1200 (twenty minutes).</li>

      <li><b>ResultsTimeout</b> (int)<br/>
        Timeout to wait when trying to retrieve results from inside the container. Default is 20 seconds.</li>

      <li><b>RemoveTimeout</b> (int)<br/>
        Timeout to wait when trying to remove a container after running a test. Defaults to 20 seconds.</li>
    </ul>

    <h3>[Gc]</h3>

    <p>Options relating to use of <code>plz gc</code>.</p>

    <ul>
      <li><b>Keep</b> (build label)<br/>
        Marks targets that gc should always keep. Can include meta-targets such as
        <code>//test/...</code> and <code>//docs:all</code>.</li>
      <li><b>KeepLabel</b><br/>
        Defines a target label to be kept; for example, if you set this to <code>go</code>,
        no Go targets would ever be considered for deletion.</li>
    </ul>

    <h3>[Go]</h3>

    <p>Properties that affect how the various Go build rules work.</p>

    <ul>
      <li><b>ImportPath</b><br/>
        String name of the canonical path of this repository.<br/>
	This path is used as the prefix of the package name relative to this <code>please</code> build directory.
	<code>importpath</code> is commonly used to prepend <code>github.com/myorg/myrepo</code> to a project's
        path.</li>

      <li><b>GoPath</b><br/>
        If set, will set the GOPATH environment variable appropriately during build actions.</li>

      <li><b>GoTool</b><br/>
        If set, the binary name to use to invoke Go & its subtools with.
        Defaults to <code>go</code>.</li>

      <li><b>GoRoot</b><br/>
        If set, will set the GOROOT environment variable appropriately during build actions.</li>

      <li><b>BuildIDTool</b><br/>
        Sets the name of the binary to use to replace Go <code>go tool buildid</code>.
        Defaults to <code>go_buildid_replacer</code>.</li>

      <li><b>TestTool</b><br/>
        Sets the location of the <code>please_go_test</code> tool that is used to template the test
        main for <code>go_test</code> rules.</li>

      <li><b>CgoCCTool</b><br/>
        Sets the location of <code>CC</code> while building <code>cgo_library</code> and <code>cgo_test</code>
	rules. Defaults to <code>gcc</code></li>

      <li><b>FilterTool</b><br/>
        Sets the location of the <code>please_go_filter</code> tool that is used to filter source
        files against build constraints.</li>

      <li><b>DefaultStatic</b> (bool)<br/>
        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.</li>
    </ul>

    <h3>[Python]</h3>

    <p>Properties that affect how the various Python build rules work.</p>

    <ul>
      <li><b>PipTool</b><br/>
        The tool that is invoked during <code>pip_library</code> rules. Defaults to <code>pip3</code>.</li>

      <li><b>PexTool</b><br/>
        The tool that's invoked to build pexes. Defaults to <code>please_pex</code> in the install directory.</li>

      <li><b>DefaultInterpreter</b><br/>
        The interpreter used for <code>python_binary</code> and <code>python_test</code> rules when none is
        specified on the rule itself. Defaults to <code>python3</code> but you could of course set it to
        <code>pypy</code>.</li>

      <li><b>TestRunner</b><br/>
        The test runner used to discover &amp; run Python tests; one of <code>unittest</code>,
        <code>pytest</code> or <code>behave</code>.  Defaults to <code>unittest</code>.</li>

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

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

      <li><b>UsePyPI</b> (bool)<br/>
        Whether or not to use PyPI for <code>pip_library</code> rules or not. Defaults to <code>True</code>, if you
        disable this you will presumably want to set DefaultPipRepo to use one of your own.<br/>
        Is overridden by the <code>use_pypi</code> argument to <code>pip_library</code>.</li>

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

    <h3>[Java]</h3>

    <p>Properties that affect how the various Java build rules work.</p>

    <ul>
      <li><b>JavacTool</b><br/>
        Defines the tool used for the Java compiler. Defaults to <code>javac</code>.</li>

      <li><b>JlinkTool</b><br/>
        Defines the tool used for the Java linker. Defaults to <code>jlink</code>.</li>

      <li><b>JavaHome</b><br/>
		    Defines the Java home folder.</li>

      <li><b>JarTool</b><br/>
        Defines the tool used to build a .jar. Defaults to <code>jar</code>.</li>

      <li><b>JarcatTool</b><br/>
        Defines the tool used to concatenate .jar files which we use to build the output
        of <code>java_binary</code> and <code>java_test</code>.Defaults to <code>jarcat</code>
	in the Please install directory.<br/>
	Any resemblance to
	<a href="http://4.bp.blogspot.com/_fzolLOGJOn0/TRkl9BFE_4I/AAAAAAAAEGQ/vxs9pwhDCVA/s1600/Cat-Packed.in.Glass.jpg">this</a>
	or <a href="http://d104xtrw2rzoau.cloudfront.net/wp-content/uploads/2013/06/15806-cat_stuck_jar_27_8_2012.jpg">this</a>
	is purr-ly coincidental.</li>

      <li><b>PleaseMavenTool</b><br/>
        Defines the tool used to fetch information from Maven in <code>maven_jars</code> rules.<br/>
        Defaults to <code>please_maven</code> in the Please install directory.</li>

      <li><b>DefaultMavenRepo</b><br/>
        Default location to load artifacts from in maven_jar rules.</li>

      <li><b>JUnitRunner</b><br/>
        Defines the .jar containing the JUnit runner. This is built into all <code>java_test</code> rules
        since it's necessary to make JUnit do anything useful.<br/>
        Defaults to <code>junit_runner.jar</code> in the Please install directory.</li>

      <li><b>DefaultTestPackage</b><br/>
        The Java classpath to search for functions annotated with <code>@Test</code>.</li>

      <li><b>SourceLevel</b> (int)<br/>
        The default Java source level when compiling. Defaults to 8.</li>

      <li><b>TargetLevel</b> (int)<br/>
        The default Java bytecode level to target. Defaults to 8.</li>

      <li><b>ReleaseLevel</b> (int)<br/>
        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+.</li>
    </ul>

    <h3><a name="cpp">[Cpp]</a></h3>

    <p>Properties that affect how the various C++ build rules work.</p>

    <ul>
      <li><b>CCTool</b><br/>
        The tool invoked to compile C code. Defaults to <code>gcc</code> but you might
        want to set it to <code>clang</code>, for example.</li>

      <li><b>CppTool</b><br/>
        The tool invoked to compile C++ code. Defaults to <code>g++</code> but you might
        want to set it to <code>clang++</code>, for example.</li>

      <li><b>LdTool</b><br/>
        The tool invoked to link object files. Defaults to <code>ld</code> but you could
        also set it to <code>gold</code>, for example.</li>

      <li><b>ArTool</b><br/>
        The tool invoked to archive static libraries. Defaults to <code>ar</code>.</li>

      <li><b>AsmTool</b><br/>
        The tool invoked as an assembler. Currently only used on OSX for
	<code>cc_embed_binary</code> rules and so defaults to <code>nasm</code>.</li>

      <li><b>LinkWithLdTool</b><br/>
	If true, instructs Please to use the tool set earlier in <code>ldtool</code>
	to link binaries instead of <code>cctool</code>.<br/>
	This is an esoteric setting that most people don't want; a vanilla <code>ld</code>
	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.</li>

      <li><b>DefaultOptCflags</b><br/>
        Compiler flags passed to all C rules during <code>opt</code> builds;
	these are typically pretty basic things like
        what language standard you want to target, warning flags, etc.<br/>
        Defaults to <code>--std=c99 -O3 -DNDEBUG -Wall -Werror</code></li>

      <li><b>DefaultDbgCflags</b><br/>
        Compiler rules passed to all C rules during <code>dbg</code> builds.<br/>
        Defaults to <code>--std=c99 -g3 -DDEBUG -Wall -Werror</code>.</li>

      <li><b>DefaultOptCppflags</b><br/>
        Compiler flags passed to all C++ rules during <code>opt</code> builds;
	these are typically pretty basic things like
        what language standard you want to target, warning flags, etc.<br/>
        Defaults to <code>--std=c++11 -O3 -DNDEBUG -Wall -Werror</code></li>

      <li><b>DefaultDbgCppflags</b><br/>
        Compiler rules passed to all C++ rules during <code>dbg</code> builds.<br/>
        Defaults to <code>--std=c++11 -g3 -DDEBUG -Wall -Werror</code>.</li>

      <li><b>DefaultLdFlags</b><br/>
        Linker flags passed to all C++ rules.<br/>
        By default this is empty.</li>

      <li><b>DefaultNamespace</b><br/>
        Namespace passed to all <code>cc_embed_binary</code> rules when not overridden
        by the <code>namespace</code> argument to that rule.<br/>
        Not set by default, if you want to use those rules you'll need to set it or
        pass it explicitly to each one.</li>

      <li><b>Coverage</b><br/>
        If true (the default), coverage will be available for C and C++ build rules.<br/>
        This is still a little experimental but should work for GCC. Right now it does
        <b>not</b> work for Clang (it likely will in Clang 4.0 which will likely support
        <code>--fprofile-dir</code>) and so this can be useful to disable it.<br/>
        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.</li>
    </ul>

    <h3>[Proto]</h3>

    <p>Properties that affect how the <code>proto_library</code> and
      <code>grpc_library</code> rules work.</p>

    <p>As noted elsewhere, these rules are fairly complex and do a bunch of things
      internally, so they correspondingly have a lot of options here.</p>

    <p>Obviously the various gRPC-related properties only apply to <code>grpc_library</code>
      rules, whereas <code>proto_library</code> rules are affected by all of them.</p>

    <ul>

      <li><b>ProtocTool</b><br/>
        The binary invoked to compile .proto files. Defaults to <code>protoc</code>.</li>

      <li><b>ProtocGoPlugin</b><br/>
        The binary passed to protoc as a plugin to generate Go code. Defaults to
        <code>protoc-gen-go</code>.<br/>
        We've found this easier to manage with a <code>go_get</code> rule instead
        though, so you can also pass a build label here. See the Please repo for an example.</li>

      <li><b>GrpcPythonPlugin</b><br/>
        The plugin invoked to compile Python code for <code>grpc_library</code>.<br/>
        Defaults to <code>grpc_python_plugin</code>.</li>

      <li><b>GrpcJavaPlugin</b><br/>
        The plugin invoked to compile Java code for <code>grpc_library</code>.<br/>
        Defaults to <code>protoc-gen-grpc-java</code>.</li>

      <li><b>Language</b> (repeated string)<br/>
        Sets the default set of languages that proto rules are built for.<br/>
        Chosen from the set of {<code>cc</code>, <code>java</code>, <code>go</code>,
        <code>py</code>}.<br/>
        Defaults to multiple <code>Language</code> lines, one line for each of
        the following values: <code>cc</code>, <code>py</code>, <code>java</code>,
        <code>go</code>, and <code>js</code>.</li>

      <li><b>PythonDep</b><br/>
        An in-repo dependency that's applied to any Python targets built.
        Defaults to <code>//third_party/python:protobuf</code>.</li>

      <li><b>JavaDep</b><br/>
        An in-repo dependency that's applied to any Java targets built.
        Defaults to <code>//third_party/java:protobuf</code>.</li>

      <li><b>GoDep</b><br/>
        An in-repo dependency that's applied to any Go targets built.
        Defaults to <code>//third_party/go:protobuf</code>.</li>

      <li><b>PythonGrpcDep</b><br/>
        An in-repo dependency that's applied to any Python gRPC targets built.
        Defaults to <code>//third_party/python:grpc</code>.</li>

      <li><b>JavaGrpcDep</b><br/>
        An in-repo dependency that's applied to any Java gRPC targets built.
        Defaults to <code>/third_party/java:grpc-all</code>.</li>

      <li><b>GoGrpcDep</b><br/>
        An in-repo dependency that's applied to any Go gRPC targets built.
        Defaults to <code>//third_party/go:grpc</code>.</li>

    </ul>

    <h3>[Licences]</h3>

    <p>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.</p>

    <ul>
      <li><b>Accept</b> (repeated string)<br/>
        Licences that are accepted in this repository.<br/>
	When this is empty licences are ignored. As soon as it's set any licence
	detected or assigned must be accepted explicitly here.<br/>
	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.</li>

      <li><b>Reject</b><br/>
	Licences that are explicitly rejected in this repository.<br/>
	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.</li>
    </ul>

    <h3>[Aliases]</h3>

    <p>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.</p>

    <p>They're written with a simple <code>alias = replacement</code> syntax:</p>

    <pre><code>
	[aliases]
	deploy = run //deployment:deployer --
    </code></pre>

    <p>This would transform <code>plz deploy //src:please</code> into
      <code>plz run //deployment:deployer -- //src:please</code>.</p>

    <p>You can also do subcommands of aliases, with a slightly different syntax:</p>

    <pre><code>
	[aliases "deploy"]
	dev = run //deployment:deployer -- --env=dev
	prod = run //deployment:deployer -- --env=prod
    </code></pre>

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

    <h3>[Alias]</h3>

    <p>This is (unsurprisingly) very similar to the <code>[Aliases]</code> section, but
      allows more information to be defined against each one. For example:</p>

    <pre><code>
	[alias "deploy"]
    cmd = run //deployment:deployer --
    subcommand = dev
    subcommand = prod
    subcommand = real prod
    flag = --force
    flag = -f
    </code></pre>

    <p>This will tab-complete, taking into account the various sub-commands and flags etc.</p>


    <h3>[Bazel]</h3>

    <p>This section defines some settings to help with limited Bazel compatibility.<br/>
      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.</p>

    <p>Currently the only attribute here is <code>compatibility</code>, when that is enabled
      some aspects of the parser behave a little differently; some of the rule names and flags
      change, <code>//visibility:public</code> is interpreted specially and WORKSPACE files are
      parsed to find external dependencies.<p>

    <p>There is a <code>--bazel_compat</code> flag to <code>plz init</code> which sets this
      on initialising a new repo.</p>

    <p>We don't have a separate setting for it, but switching this on will also allow limited
      Buck compatibility. Specifically <code>include_defs</code> becomes available and the
      various C++ rules gain <code>cxx_</code> aliases.</p>