config.html

<h1 id="config-file-reference" class="title-1">Please config file reference</h1>

<p>
  The root of a Please repo is identified by a <code class="code">.plzconfig</code> 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):
</p>

<ul class="bulleted-list">
  <li>
    <span><code class="code">/etc/please/plzconfig</code></span>
  </li>
  <li>
    <span><code class="code">~/.config/please/plzconfig</code></span>
  </li>
  <li>
    <span><code class="code">.plzconfig</code></span>
  </li>
  <li>
    <span
      ><code class="code">.plzconfig_&lt;arch&gt;</code> (e.g.
      <code class="code">.plzconfig_linux_amd64</code>)</span
    >
  </li>
  <li>
    <span>
      <code class="code">.plzconfig.*</code> read from <code class="code">--profile</code>
      (e.g. <code class="code">--profile=remote</code>)</span>
  </li>
  <li>
    <span><code class="code">.plzconfig.local</code></span>
  </li>
</ul>

<p>
  Profile-specific config files can be defined and take precedence over the config file being
  evaluated. Except <code class="code">.plzconfig.local</code> which always has highest precedence.
  This is achieved by having a sibling config file with the name ending with the
  profile name (i.e. <code class="code" >.plzconfig.remote</code>, <code class="code"
  >.plzconfig_linux_amd64.remote</code>, etc.) and running the command with the
  <code class="code">--profile</code> flag set (ie. <code class="code">--profile=remote</code>).
</p>

<p>
  One would normally check in <code class="code">.plzconfig</code> (and
  arch-specific equivalents if needed).<br />
  <code class="code">/etc/please/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 class="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
    class="copy-link"
    href="https://git-scm.com/docs/git-config#_syntax"
    target="_blank"
    rel="noopener"
    >Git's config</a
  >; it's broken into sections by headers in square brackets, and each section
  contains <code class="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 class="code">true</code>, <code class="code">false</code>,
  <code class="code">yes</code>, <code class="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.
</p>

<pre class="code-container">
  <!-- prettier-ignore -->
  <code>
    buildfilename = BUILD
    buildfilename = BUILD.plz
  </code>
</pre>

<p>Comma-separating on the same line won't generally work.</p>

<section class="mt4">
  <h2 id="please" class="title-2">[Please]</h2>

  <ul class="bulleted-list">
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="please.version">Version</h3>

        <p>
          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 class="code">SelfUpdate</code> is set Please will attempt to
          download an appropriate version, otherwise it will issue a warning and
          continue.
        </p>

        <p>
          Note that if this is not set, you can run
          <code class="code">plz update</code> to update to the latest version
          available on the server.
        </p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="please.versionchecksum">VersionChecksum</h3>

        <p>
          Defines a hex-encoded sha256 checksum that the downloaded version must
          match. Can be specified multiple times to support different
          architectures.
        </p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="please.location">Location</h3>

        <p>
          Defines the directory Please is installed into.<br />
          Defaults to <code class="code">~/.please</code> but you might want it
          to be somewhere else if you're installing via another method.
        </p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="please.selfupdate">
          SelfUpdate <span class="normal">(bool)</span>
        </h3>

        <p>
          Sets whether plz will attempt to update itself when the version set in
          the config file is different.
        </p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="please.downloadlocation">DownloadLocation <span class="normal">(bool)</span></h3>

        <p>
          Defines the location to download Please from when self-updating.
          Defaults to the Please web server (<a
            class="copy-link"
            href="https://get.please.build"
            target="_blank"
            rel="noopener"
            >https://get.please.build</a
          >), 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.
        </p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title">Nonce</h3>

        <p>
          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.
        </p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="please.numthreads">
          NumThreads <span class="normal">(int)</span>
        </h3>

        <p>
          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.
        </p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="please.defaultrepo">DefaultRepo</h3>

        <p>
          Location of the please repo to use by default, if not already in a please repo.
        </p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="please.pluginrepo">PluginRepo  <span class="normal">(repeated string)</span></h3>

        <p>
          {{ index .ConfigHelpText "please.pluginrepo" }}
        </p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="please.autoclean">Autoclean <span class="normal">(b ool)</span></h3>

        <p>
          Automatically clean stale versions without prompting. Defaults to true.
        </p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="please.numoldversions">NumOldVersions <span class="normal">(int)</span></h3>

        <p>
          The number of old versions to keep. Defaults to 10.
        </p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="please.toolsurl">ToolsUrl</h3>

        <p>
          {{ index .ConfigHelpText "please.toolsurl" }}
        </p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="please.motd">MOTD</h3>

        <p>
          {{ index .ConfigHelpText "please.motd" }}
        </p>
      </div>
    </li>
  </ul>
</section>

<section class="mt4">
  <h2 id="parse" class="title-2">[Parse]</h2>

  <ul class="bulleted-list">
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="parse.buildfilename">
          BuildFileName <span class="normal">(repeated string)</span>
        </h3>

        <p>
          Sets the names that Please uses for its build files. Defaults to
          <code class="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 class="code">build</code> on a case-insensitive file system like
          HFS+.
        </p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="parse.blacklistdirs">
          BlacklistDirs <span class="normal">(repeated string)</span>
        </h3>

        <p>
          Directories to blacklist when recursively searching for BUILD files
          (e.g. when using <code class="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 class="code">node_modules</code> that have come from external
          package managers.
        </p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="parse.experimentaldir">
          ExperimentalDir <span class="normal">(repeated string)</span>
        </h3>

        <p>
          Directory containing experimental code. This is subject to some extra
          restrictions:
        </p>

        <ul class="bulleted-list">
          <li>
            <span>
              Code in the experimental dir can override normal visibility
              constraints
            </span>
          </li>
          <li>
            <span>
              Code outside the experimental dir can never depend on code inside
              it
            </span>
          </li>
          <li>
            <span>Tests are excluded from general detection</span>
          </li>
        </ul>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="parse.preloadbuilddefs">
          PreloadBuildDefs <span class="normal">(repeated string)</span>
        </h3>

        <p>
          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 class="code">subinclude()</code> paths.
        </p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="parse.preloadsubincludes">
          PreloadSubincludes <span class="normal">(repeated string)</span>
        </h3>
        <p>
          Subinclude targets to preload by the parser before loading any BUILD files.<br/>
          Subincludes can be slow so it's recommended to use PreloadBuildDefs where possible.
        </p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="parse.builddefsdir">
          BuildDefsDir <span class="normal">(repeated string)</span>
        </h3>
        <p>
          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 <code>build_defs</code>.
        </p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="parse.numthreads">
          NumThreads <span class="normal">(int)</span>
        </h3>
        <p>
          The number of threads to use while parsing the build graph. Default is the number of CPU threads + 2.
        </p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="parse.gitfunctions">GitFunctions</h3>
        <p>
          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.
        </p>
      </div>
    </li>
  </ul>
</section>

<section class="mt4">
  <h2 id="plugindefinition" class="title-2">[PluginDefinition]</h2>
  <p class="red">
    This feature is still experimental; some aspects may not work fully or at all
    just yet. Proceed with caution!
  </p>

  <p>Used in repos that implement a Please plugin. By adding this section to your <code class="code">.plzconfig</code>,
    your project can be included as a plugin in other Please repos.
  </p>

  <p>The following sets up a plugin with ID foo.</p>

  <pre class="code-container">
    <!-- prettier-ignore -->
    <code>
    [PluginDefinition]
    Name = foo

    [PluginConfig "foo_tool"]
    ConfigKey = FooTool
    ; It is resolved relative to the subrepo for this plugin
    DefaultValue = //tools:foo
    </code>
  </pre>

  <p>Another Please repo can then override these values as such:</p>
  <pre class="code-container">
    <!-- prettier-ignore -->
    <code>
    [Plugin "foo"]
    FooTool = foo_tool
    </code>
  </pre>

  <p>This config value is then available to the build definitions as <code class="code">CONFIG.FOO.FOO_TOOL</code>.</p>

  <ul class="bulleted-list">
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="plugindefinition.description">
          Description <span class="normal">(string)</span>
        </h3>

        <p>
        A description of the plugin. If set, this can be read and output by
        <code class="code">plz help &lt;plugin&gt;</code>.
        </p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="plugindefinition.builddefsdir">
          BuildDefsDir <span class="normal">(repeatable string)</span>
        </h3>

        <p>
          Tells Please about any directories in the plugin that contain custom
          build definitions. These are used by <code class="code">plz help &lt;plugin&gt;</code> to provide
          help text for build rules that are not built in. Defaults to <code class="code">build_defs</code>.
        </p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="plugindefinition.documentationsite">
          DocumentationSite <span class="normal">(string)</span>
        </h3>

        <p>
          A link to where the plugin's documentation is hosted.
        </p>
      </div>
    </li>
</section>

<section class="mt4">
  <h2 id="pluginconfig" class="title-2">[PluginConfig "config_key"]</h2>
  <p class="red">
    This feature is still experimental; some aspects may not work fully or at all
    just yet. Proceed with caution!
  </p>

  <p>Used in conjunction with <a href="#plugindefinition" class="copy-link">[PluginDefinition]</a> to define configuration
    values for a plugin.
  </p>

  <ul class="bulleted-list">
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="pluginconfig.configkey">
          ConfigKey
        </h3>
        <p>
          The key consumers of this plugin will use to set this value in their
          <a href="#plugin" class="copy-link">[Plugin]</a> section.
        </p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="pluginconfig.defaultvalue">
          DefaultValue
        </h3>
        <p>
          The default value for this config value, if any.
        </p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="pluginconfig.optional">
          Optional <span class="normal">(bool)</span>
        </h3>
        <p>
          If true, this config value may be empty.
        </p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="pluginconfig.repeatable">
          Repeatable <span class="normal">(bool)</span>
        </h3>
        <p>
          If true, this config value may be repeated.
        </p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="pluginconfig.inherit">
          Inherit <span class="normal">(bool)</span>
        </h3>
        <p>
          If true, this config value will always be inherited by the parent repo, when this repo is a subrepo.
        </p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="pluginconfig.type">Type</h3>
        <p>
          The type of this config value. The options are <code class="code">str</code>, <code class="code">int</code>,
          or <code class="code">bool</code>. Defaults to <code class="code">str</code>.
        </p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="pluginconfig.help">Help</h3>
        <p>
          A help string describing what this config property does.
        </p>
      </div>
    </li>
  </ul>
</section>

<section class="mt4">
  <h2 id="plugin" class="title-2">[Plugin "plugin-id"]</h2>
  <p class="red">
    This feature is still experimental; some aspects may not work fully or at all
    just yet. Proceed with caution!
  </p>

  <p>This section can be used to define configuration specific to a plugin identified by its ID.</p>

  <ul class="bulleted-list">
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="plugin.target">
          Target <span class="normal">(build label)</span>
        </h3>
          <p>{{ index .ConfigHelpText "plugin.target" }}</p>
      </div>
    </li>
  </ul>
</section>

<section class="mt4">
  <h2 id="display" class="title-2">[Display]</h2>

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

  <ul class="bulleted-list">
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="display.updatetitle">
          UpdateTitle <span class="normal">(bool)</span>
        </h3>

        <p>
          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.
        </p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="display.systemstats">
          SystemStats <span class="normal">(bool)</span>
        </h3>

        <p>
          Whether or not to show basic system resource usage in the interactive
          display. Defaults to <code class="code">False</code>.
        </p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="display.colourscheme">ColourScheme</h3>
        <p>
          Shell colour scheme mode, dark or light. Adapts interactive display
          colours to the colour scheme mode. Defaults to
          <code class="code">dark</code>.
        </p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="display.maxworkers">
          MaxWorkers <span class="normal">(int)</span>
        </h3>
        <p>{{ index .ConfigHelpText "display.maxworkers" }}</p>
      </div>
    </li>
  </ul>
</section>

<section class="mt4">
  <h2 id="colours" class="title-2">[Colours]</h2>
  <p>{{ index .ConfigHelpText "colours" }}</p>
</section>

<section class="mt4">
  <h2 id="build" class="title-2">[Build]</h2>

  <ul class="bulleted-list">
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="build.arch">Arch</h3>

        <p>Architecture to compile for. Defaults to the host architecture.</p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="build.timeout">
          Timeout <span class="normal">(int)</span>
        </h3>

        <p>
          Timeout for build operations, in seconds. Defaults to 600 (ten
          minutes).
        </p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="build.path">
          Path <span class="normal">(repeated string)</span>
        </h3>

        <p>
          The PATH variable that will be passed to the build processes.<br />
          Defaults to <code class="code">/usr/local/bin:/usr/bin:/bin</code> but
          of course can be modified if you need to get binaries from other
          locations.
        </p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="build.config">Config</h3>

        <p>
          The build config to use when one is not chosen on the command line.
          Defaults to <code class="code">opt</code>.
        </p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="build.fallbackconfig">FallbackConfig</h3>

        <p>
          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 class="code">opt</code>.
        </p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="build.passenv">
          PassEnv <span class="normal">(repeated string)</span>
        </h3>

        <p>
          A list of environment variables to pass from the current environment
          to build rules. For example
          <code class="code">PassEnv = HTTP_PROXY</code>
          would copy your HTTP_PROXY environment variable to the build env for
          any rules.
        </p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="build.passunsafeenv">
          PassUnsafeEnv <span class="normal">(repeated string)</span>
        </h3>

        <p>
          Similar to PassEnv. A list of environment variables to pass from the
          current environment to build rules. For example
          <code class="code">PassUnsafeEnv = HTTP_PROXY</code> 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.
        </p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="build.lang">Lang</h3>

        <p>
          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 class="code">en_GB.UTF-8</code>.
        </p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="build.downloadlinkable">DownloadLinkable</h3>

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

        <p>
          Linkable targets are identified by rules with the following labels: <code class="code">link:destination</code>,
          <code class="code">hlink:destination</code>, <code class="code">dlink:destination</code>,
          <code class="code">dhlink:destination</code> and <code class="code">codegen</code>.
        </p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="build.linkgeneratedsources">LinkGeneratedSources</h3>

        <p>
          When set, Please will link generated sources back into the source tree. A <code>.gitignore</code> can be
          generated with <code>plz generate --update_gitignore .gitignore</code>. This can help with getting Please to
          work with IDEs and tooling. This can be set to <code class="code">hard</code> to generate hard links.
        </p>
        <p>
          Generated sources are identified by rules with the <code class="code">codegen</code> label.
        </p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="build.updategitignore">UpdateGitignore</h3>
        <p>
          When set, Please will update the nearest <code class="code">.gitignore</code> with generated sources
          automatically during builds. This must be used in conjunction with LinkGeneratedSources.
        </p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="build.arcattool">ArcatTool</h3>

        <p>
          Defines the tool used to concatenate files which we use to build
          the output of various build rules. Defaults to
          <code class="code">arcat</code> (formerly <code class="code">jarcat</code>).<br />
          For more information, feel free to purr-use the arcat page
          <a class="copy-link" href="https://github.com/please-build/arcat" rel="noopener">here</a>.
        </p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="build.xattrs">XAttrs</h3>

        <p>{{ index .ConfigHelpText "build.xattrs" }}</p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="build.nonce">Nonce</h3>

        <p>{{ index .ConfigHelpText "build.nonce" }}</p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="build.httpproxy">HttpProxy</h3>

        <p>{{ index .ConfigHelpText "build.httpproxy" }}</p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="build.hashcheckers">HashCheckers</h3>

        <p>{{ index .ConfigHelpText "build.hashcheckers" }}</p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="build.hashfunction">HashFunction</h3>

        <p>{{ index .ConfigHelpText "build.hashfunction" }}</p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="build.exitonerror">ExitOnError <span class="normal">(bool)</span></h3>

        <p>{{ index .ConfigHelpText "build.exitonerror" }}</p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="build.paralleldownloads">ParallelDownloads <span class="normal">(int)</span></h3>

        <p>{{ index .ConfigHelpText "build.paralleldownloads" }}</p>
      </div>
    </li>
  </ul>
</section>

<section class="mt4">
  <h2 id="buildenv" class="title-2">[BuildEnv]</h2>

  <p>
    A set of extra environment variables to define for build rules. For example:
  </p>

  <pre class="code-container">
    <!-- prettier-ignore -->
    <code>
    [buildenv]
    secret-passphrase = 12345
    </code>
  </pre>

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

<section class="mt4">
  <h2 id="sandbox" class="title-2">[Sandbox]</h2>
  <ul class="bulleted-list">
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="sandbox.tool">
          Tool
        </h3>

        <p>
          The binary to use for sandboxing build/test actions. Typically this
          is <code>please_sandbox</code>, which currently only does anything on Linux.<br />
          It receives the program to execute and all its arguments in its <code>argv</code>,
          it is expected to do whatever it needs to then <code>exec</code> the real action.
        </p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="sandbox.build">
          Build <span class="normal">(bool)</span>
        </h3>

        <p>
          Activates sandboxing for build actions, which isolates them
          from network access, IPC and the repo-local filesystem. Currently
          only works on Linux. Defaults to <code class="code">False</code>.
        </p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="sandbox.test">
          Test <span class="normal">(bool)</span>
        </h3>

        <p>
          Activates sandboxing for test actions, which isolates them
          from network access, IPC and the repo-local filesystem. Currently
          only works on Linux. Defaults to <code class="code">False</code>.
        </p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="sandbox.dir">
          Dir <span class="normal">(repeated string)</span>
        </h3>

        <p>
          Directories that the sandbox tool should mask (it's unspecified how, although mounting an
          empty filesystem over the top is the current implementation).<br />
          These are passed to the tool itself in the <code>SANDBOX_DIRS</code> env var as a comma-separated list.
        </p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="sandbox.namespace">
          Namespace <span class="normal">(bool)</span>
        </h3>
        <p>{{ index .ConfigHelpText "sandbox.namespace" }}</p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="sandbox.excludeabletargets">
          ExcludeableTargets (repeated build label)
        </h3>

        <p>
        <p>{{ index .ConfigHelpText "sandbox.excludeabletargets" }}. Values can be wildcards, e.g.
        <code class="code">//third_party/...</code></p>
        </p>
      </div>
    </li>
  </ul>
  <p>N.B. On Ubuntu Noble (24.04) or later, sandboxing may fail with a "Permission denied" error (often referring
    to <code class="code">/proc/self/setgroups</code>). This is due to a
    <a href="https://ubuntu.com/blog/ubuntu-23-10-restricted-unprivileged-user-namespaces">security change</a>
    which prohibits unprivileged user namespaces, which the sandboxing relies upon.<br/>
    To fix this, you need to create an AppArmor profile allowing it; we have an
    <a href="https://github.com/thought-machine/please/blob/master/tools/misc/apparmor_profile">example</a>
    for the default install location, which you should copy to <code class="code">/etc/apparmor.d/build.please</code>,
    then run <code class="code">sudo systemctl reload apparmor</code> to apply the new profile.</p>
</section>

<section class="mt4">
  <h2 id="remote" class="title-2">[Remote]</h2>
  <ul class="bulleted-list">
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="remote.url">URL</h3>

        <p>
          Sets the URL to communicate with the remote server on.<br />
          Typically this would look something like
          <code class="code">127.0.0.1:8989</code>, i.e. it is given without a
          protocol.
        </p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="remote.instance">Instance</h3>

        <p>
          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.
        </p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="remote.numexecutors">
          NumExecutors <span class="normal">(int)</span>
        </h3>

        <p>Defines the number of remote executors to use simultaneously.</p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="remote.name">Name</h3>

        <p>
          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.
        </p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="remote.casurl">CasUrl</h3>
        <p>{{ index .ConfigHelpText "remote.casurl" }}</p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="remote.asseturl">AssetUrl</h3>
        <p>{{ index .ConfigHelpText "remote.asseturl" }}</p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="remote.displayurl">DisplayUrl</h3>
        <p>{{ index .ConfigHelpText "remote.displayurl" }}</p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="remote.tokenfile">TokenFile</h3>
        <p>{{ index .ConfigHelpText "remote.tokenfile" }}</p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="remote.timeout">Timeout <span class="normal">(int)</span></h3>
        <p>{{ index .ConfigHelpText "remote.timeout" }}</p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="remote.secure">Secure <span class="normal">(bool)</span></h3>
        <p>{{ index .ConfigHelpText "remote.secure" }}</p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="remote.verifyoutputs">VerifyOutputs <span class="normal">(bool)</span></h3>
        <p>{{ index .ConfigHelpText "remote.verifyoutputs" }}</p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="remote.uploaddirs">UploadDirs <span class="normal">(bool)</span></h3>
        <p>{{ index .ConfigHelpText "remote.uploaddirs" }}</p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="remote.optionaloutputsrequired">OptionalOutputsRequired <span class="normal">(bool)</span></h3>
        <p>{{ index .ConfigHelpText "remote.optionaloutputsrequired" }}</p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="remote.shell">Shell </h3>
        <p>{{ index .ConfigHelpText "remote.shell" }}</p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="remote.platform">Platform <span class="normal">(repeated string)</span></h3>
        <p>{{ index .ConfigHelpText "remote.platform" }}</p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="remote.cacheduration">CacheDuraction <span class="normal">(int)</span></h3>
        <p>{{ index .ConfigHelpText "remote.cacheduration" }}</p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="remote.buildid">BuildId</h3>
        <p>{{ index .ConfigHelpText "remote.buildid" }}</p>
      </div>
    </li>
  </ul>
</section>

<section class="mt4">
  <h2 id="cache" class="title-2">[Cache]</h2>

  <ul class="bulleted-list">
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="cache.dir">Dir</h3>

        <p>
          Sets the directory to use for the dir cache.<br />
          The default is <code class="code">.plz-cache</code>, if set to the
          empty string the dir cache will be disabled.
        </p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="cache.dircachehighwatermark">
          DirCacheHighWaterMark <span class="normal">(size)</span>
        </h3>

        <p>
          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 class="code">10GiB</code>.
        </p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="cache.dircachelowwatermark">
          DirCacheLowWaterMark <span class="normal">(size)</span>
        </h3>

        <p>
          When cleaning the directory cache, it's reduced to at most this size.
          Defaults to <code class="code">8GiB</code>.
        </p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="cache.httpurl">HttpUrl</h3>

        <p>
          Base URL of the HTTP cache.<br />
          Not set to anything by default which means the cache will be disabled.
        </p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="cache.httpwriteable">
          HttpWriteable <span class="normal">(bool)</span>
        </h3>

        <p>
          If True this plz instance will write content back to the HTTP
          cache.<br />
          By default it runs in read-only mode.
        </p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="cache.httptimeout">
          HttpTimeout <span class="normal">(int)</span>
        </h3>

        <p>Timeout for operations contacting the HTTP cache, in seconds.</p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="cache.workers">Workers</h3>
        <p>{{ index .ConfigHelpText "cache.workers" }}</p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="cache.dirclean">
          DirClean <span class="normal">(bool)</span>
        </h3>
        <p>{{ index .ConfigHelpText "cache.dirclean" }}</p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="cache.dircompress">
          DirCompress <span class="normal">(bool)</span>
        </h3>
        <p>{{ index .ConfigHelpText "cache.dircompress" }}</p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="cache.httpconcurrentrequestlimit">
          HttpConcurrentRequestLimit <span class="normal">(int)</span>
        </h3>
        <p>{{ index .ConfigHelpText "cache.httpconcurrentrequestlimit" }}</p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="cache.httpretry">
          HttpRetry <span class="normal">(int)</span>
        </h3>
        <p>{{ index .ConfigHelpText "cache.httpretry" }}</p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="cache.retrievecommand">RetrieveCommand</h3>

        <p>
          Use a custom command to retrieve cache entries.<br />
          Disabled by default.
        </p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="cache.storecommand">StoreCommand</h3>

        <p>
          Use a custom command to store cache entries.<br />
          Disabled by default. You can only enable it together with RetrieveCommand.
        </p>
      </div>
    </li>
  </ul>
</section>

<section class="mt4">
  <h2 id="size" class="title-2">[Size]</h2>
  <p>{{ index .ConfigHelpText "size" }}</p>
  <ul class="bulleted-list">
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="size.timeout">
          Timeout <span class="normal">(int)</span>
        </h3>
        <p>{{ index .ConfigHelpText "size.timeout" }}</p>

      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="size.timeoutname">TimeoutName</h3>
        <p>{{ index .ConfigHelpText "size.timeoutname" }}</p>
      </div>
    </li>
  </ul>
</section>

<section class="mt4">
  <h2 id="test" class="title-2">[Test]</h2>

  <ul class="bulleted-list">
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="test.timeout">
          Timeout <span class="normal">(int)</span>
        </h3>

        <p>
          Sets the default timeout length, in seconds, for any test that isn't
          explicitly given one. Defaults to 600 (10 minutes).
        </p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="test.disablecoverage">
          DisableCoverage <span class="normal">(repeated string)</span>
        </h3>

        <p>
          Disables coverage for tests that have any of these labels specified.
        </p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="test.upload">
          Upload <span class="normal">(string)</span>
        </h3>

        <p>
          URL to upload test results to. The request is a POST containing the
          results in XML format.
        </p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="test.uploadgzipped">
          UploadGzipped <span class="normal">(bool)</span>
        </h3>

        <p>
        <p>{{ index .ConfigHelpText "test.uploadgzipped" }}</p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="test.storetestoutputonsuccess">
          StoreTestOutputOnSuccess <span class="normal">(bool)</span>
        </h3>
        <p>
        <p>{{ index .ConfigHelpText "test.storetestoutputonsuccess" }}</p>
      </div>
    </li>
  </ul>
</section>

<section class="mt4">
  <h2 id="cover" class="title-2">[Cover]</h2>

  <ul class="bulleted-list">
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="cover.fileextension">
          FileExtension <span class="normal">(repeated string)</span>
        </h3>

        <p>Extensions of files to consider for coverage.\nDefaults to
          <code class="code">.go</code>, <code class="code">.py</code>,
          <code class="code">.java</code>, <code class="code">.tsx</code>,
          <code class="code">.ts</code>, <code class="code">.js</code>,
          <code class="code">.cc</code>, <code class="code">.h</code>, and
          <code class="code">.c</code>.</p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="cover.excludeextension">
          ExcludeExtension <span class="normal">(repeated string)</span>
        </h3>

        <p>
          Extensions of files to exclude from coverage.<br />
          Typically this is for generated code; the default is to exclude
          protobuf extensions like
          <code class="code">.pb.go</code>, <code class="code">_pb2.py</code>.
          Defaults to <code class="code">.pb.go</code>, <code class="code">.spec.tsx</code>,
          <code class="code">.spec.ts</code>, <code class="code">.spec.js</code>,
          <code class="code">_pb2.py</code>, <code class="code">.pb.cc</code>,
          <code class="code">.pb.h</code>, <code class="code">_test.py</code>,
          <code class="code">_test.go</code>, <code class="code">_pb.go</code>,
          <code class="code">_bindata.go</code>, and
          <code class="code">_test_main.cc</code>.
        </p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="cover.excludeglob">
          ExcludeGlob<span class="normal">(repeated string)</span>
        </h3>

        <p>
          Exclude glob pattern from coverage. <br />
          Typically this is for generated code and it is useful when there is no other discrimination possible.
        </p>
      </div>
    </li>
  </ul>
</section>

<section class="mt4">
  <h2 id="gc" class="title-2">[Gc]</h2>

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

  <ul class="bulleted-list">
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="gc.keep">
          Keep <span class="normal">(build label)</span>
        </h3>

        <p>
          Marks targets that gc should always keep. Can include meta-targets
          such as <code class="code">//test/...</code> and
          <code class="code">//docs:all</code>.
        </p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="gc.keeplabel">KeepLabel</h3>

        <p>
          Defines a target label to be kept; for example, if you set this to
          <code class="code">go</code>, no Go targets would ever be considered
          for deletion.
        </p>
      </div>
    </li>
  </ul>
</section>

<section class="mt4">
  <h2 id="alias" class="title-2">[Alias "name"]</h2>
  <p>This section can be used to add custom commands to the plz cli. The section
    can be repeated multiple times to add many aliases.</p>
  <ul class="bulleted-list">
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="alias.cmd">Cmd</h3>
        <p>
          The actual command to run. Will be prefixed by `plz` and all arguments will be passed to this literally.
        </p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="alias.subcommand">
          Subcommand <span class="normal">(repeated string)</span>
        </h3>
        <p>
          Any subcommands of this alias. Used for tab completion.
        </p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="alias.flag">
          Flag <span class="normal">(repeated string)</span>
        </h3>
        <p>
          Any flags of this alias. Used for tab completion.
        </p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="alias.positionallabels">
          PositionalLabels <span class="normal">(repeated string)</span>
        </h3>
        <p>
          Whether this alias's positional arguments are build labels.
        </p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="alias.desc">Desc</h3>
        <p>{{ index .ConfigHelpText "alias.desc" }}</p>
      </div>
    </li>
  </ul>
  <h4 class="title-3">Example</h4>
  <p>
    An alias to run <code class="code">//deployment:deployer</code> with the form
    <code class="code">plz deploy prod --force //my:target</code> would look
    like this in the config:
  </p>

  <pre class="code-container">
    <!-- prettier-ignore -->
    <code>
    [alias "deploy"]
    cmd = run //deployment:deployer --
    subcommand = dev
    subcommand = prod
    subcommand = real prod
    flag = --force
    flag = -f
    positionallabels = true
    </code>
  </pre>

  <p>
    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 <code class="code">positionallabels</code> field
    adds tab-completion for build labels to the alias which can be useful for
    those that operate on build targets.
  </p>

  <p>
    To enable Please completions, add this line to your
    <code class="code">.bashrc</code> or <code class="code">.zshrc</code>:
  </p>

  <pre class="code-container">
    <!-- prettier-ignore -->
    <code>
    source &lt;(plz --completion_script)
    </code>
  </pre>

  <p>
    Aliases for personal use can be added to your local (personal) please
    configuration i.e. <code class="code">.plzconfig.local</code>.
  </p>

</section>

<section class="mt4">
  <h2 id="python" class="title-2">[Python]</h2>

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

  <ul class="bulleted-list">
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="python.piptool">PipTool</h3>

        <p>
          The tool that is invoked during
          <code class="code">pip_library</code> rules. Defaults to
          <code class="code">pip3</code>.
        </p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="python.pextool">PexTool</h3>

        <p>
          The tool that's invoked to build pexes. Defaults to
          <code class="code">please_pex</code> in the install directory.
        </p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="python.defaultinterpreter">DefaultInterpreter</h3>

        <p>
          The interpreter used for <code class="code">python_binary</code> and
          <code class="code">python_test</code> 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 <code class="code">python3</code>.
        </p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="python.testrunner">TestRunner</h3>

        <p>
          The test runner used to discover &amp; run Python tests; one of
          <code class="code">unittest</code>,
          <code class="code">pytest</code> or <code class="code">behave</code>.
          Defaults to <code class="code">unittest</code>.
        </p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="python.testrunnerbootstrap">TestRunnerBootstrap</h3>
        <p>{{ index .ConfigHelpText "python.testrunnerbootstrap" }}</p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="python.debugger">Debugger</h3>
        <p>{{ index .ConfigHelpText "python.debugger" }}</p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="python.moduledir">ModuleDir</h3>

        <p>
          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 class="code">pip_library</code> rules in
          <code class="code">third_party/python</code> and set this
          appropriately. Hence any of those third-party libraries that try
          something like <code class="code">import six</code> will have it work
          as they expect, even though it's actually in a different location
          within the .pex.
        </p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="python.defaultpiprepo">DefaultPipRepo</h3>

        <p>
          Defines a location for a pip repo to download wheels from.<br />
          By default <code class="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 class="code">repo</code> argument to
          <code class="code">pip_library</code>.
        </p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="python.wheelrepo">WheelRepo</h3>

        <p>
          Defines a location for a remote repo that python_wheel rules will
          download from. See
          <a class="copy-link" href="/plugins.html#python_wheel"
            >python_wheel</a
          >
          for more information.
        </p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="python.usepypi">
          UsePyPI <span class="normal">(bool)</span>
        </h3>

        <p>
          Whether or not to use PyPI for
          <code class="code">pip_library</code> rules or not. Defaults to
          <code class="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 class="code">use_pypi</code> argument to
          <code class="code">pip_library</code>.
        </p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="python.wheelnamescheme">WheelNameScheme</h3>
        <p>
          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 class="code">url_base</code>,
          <code class="code">package_name</code>, and
          <code class="code">version</code>. The default search pattern is
          <code class="code">{{ "{url_base}/{package_name}-{version}-${{OS}}-${{ARCH}}.whl" }}</code>
          along with a few common variants.
        </p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="python.disablevendorflags">
          DisableVendorFlags <span class="normal">(bool)</span>
        </h3>

        <p>
          Disables injection of vendor specific flags for <code class="code">pip</code> while using
          <code class="code">pip_library</code>. The option can be useful if you are using
          something like <code class="code">Pyenv</code>, and the passing of additional
          flags or configuration that are vendor specific, e.g. <code class="code">--system</code>,
          breaks your build.
        </p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="python.pipflags">PipFlags</h3>
        <p>{{ index .ConfigHelpText "python.pipflags" }}</p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="python.interpreteroptions">InterpreterOptions</h3>
        <p>{{ index .ConfigHelpText "python.interpreteroptions" }}</p>
      </div>
    </li>
  </ul>
</section>

<section class="mt4">
  <h2 id="licences" class="title-2">[Licences]</h2>

  <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 class="bulleted-list">
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="licences.accept">
          Accept <span class="normal">(repeated string)</span>
        </h3>

        <p>
          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.
        </p>
      </div>
    </li>
    <li>
      <div>
        <h3 class="mt1 f6 lh-title" id="licences.reject">Reject</h3>

        <p>
          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.
        </p>
      </div>
    </li>
  </ul>
</section>

<section class="mt4">
  <h2 id="buildconfig" class="title-2">[BuildConfig]</h2>

  <p>
    This section lets you define arbitrary key-value pairs that can be consumed
    by custom build rules. For example:
  </p>

  <pre class="code-container">
    <!-- prettier-ignore -->
    <code>
    [buildconfig]
    rust-toolchain = //third_party/rust:toolchain
    </code>
  </pre>

  <p>
    The above can then be read in a .build_def or BUILD file as
    <code class="code">CONFIG.RUST_TOOLCHAIN</code>, i.e. they are upper-cased
    and hyphens are converted to underscores.
  </p>
</section>


<section class="mt4">
  <h2 id="bazel" class="title-2">[Bazel]</h2>

  <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 class="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 class="code">//visibility:public</code> is interpreted
    specially and WORKSPACE files are parsed to find external dependencies. The
    <a class="copy-link" href="/lexicon.html#glob"
      ><code class="code">glob</code></a
    >
    builtin also changes to include hidden files by default.
  </p>

  <p>
    There is a <code class="code">--bazel_compat</code> flag to
    <code class="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 class="code">include_defs</code> becomes available and the various C++
    rules gain <code class="code">cxx_</code> aliases.
  </p>
</section>