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

    <h1>Extra rules (aka. Pleasings)</h1>

    <p>Please comes with built-in rules for Go, Python, Java, C++, Protocol Buffers
      and a few other bits & pieces. While it's nice to have a bunch of capabilities by
      default, it's obviously not practical for every language to be part of the core repo,
      and indeed part of the original design was to make it easy to add support for new
      languages without having to update the core code.
    </p>

    <p>We collect support for additional languages in
      <a href="https://github.com/thought-machine/pleasings">a separate repo</a>.
      These are somewhat pithily named Pleasings and have rules for various new languages that are
      either still pretty early stage and unstable (the rules, not the language :) ) or
      sufficiently esoteric that having them part of the core seems inappropriate.
    </p>

    <h2>Loading additional rules</h2>

    <p>The simplest and most lightweight way to load new rules is to do it directly with
      <code>subinclude</code>, like so:</p>

    <pre><code>
        subinclude('https://github.com/thought-machine/pleasings/raw/master/rust/rust.build_defs')

        rust_library(
            name = 'my_rust_lib',
            srcs = ['mine.rs'],
        )
    </code></pre>

    <p>Some rules may have extra requirements, for example some single package in which you have
      to set up a one-off set of targets. The individual rules will document what's required.</p>

    <h2>The more repeatable solution</h2>

    <p>As noted the above solution is nice and lightweight, and Please will take care of
      deduplicating & caching the download from github, so it works fairly well for straightforward
      cases. But there are times when you might want more control, like pinning to a particular
      version so you're not broken by any incompatible changes, or hash verifying the downloaded
      rules so you know you're always getting what you expect.
    </p>

    <p>The idiomatic way of achieving this is to set up one centralised package to do the
      download more carefully and subinclude from there. Conventionally we use
      <code>//build_defs</code> but of course this package can be anywhere. You'd set up
      <code>//build_defs/BUILD</code> as follows:
    </p>

    <pre><code>
        package(default_visibility = ['PUBLIC'])

        remote_file(
            name = 'rust',
            url = 'https://raw.githubusercontent.com/thought-machine/pleasings/4a8158a65ef39e7dd9a1569fbfa1e5eec398e066/rust/rust.build_defs',
            hashes = [
                'bbfa10e522cfc870bfcbfbae6b899b770b54031a',
            ],
        )
    </code></pre>

    <p>Then from any other package in your repo you could write the following:</p>

    <pre><code>
        subinclude('//build_defs:rust')

        rust_library(
            name = 'my_rust_lib',
            srcs = ['mine.rs'],
        )
    </code></pre>

    <p>This has the advantage of a shorter call to <code>subinclude</code> in each package,
      but more seriously states the expected revision & hash in a centralised location so
      your build always uses the same upstream version of the rules to compile it.
    </p>