Extra rules (aka. Pleasings)

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.

We collect support for additional languages in a separate repo. 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.

Loading additional rules

To start using pleasings, you will need to add the pleasings repo to your project:

    
    
    $ plz init pleasings --revision=vX.X.X

Then you may use build rules from the pleasings like so:

    
    
    subinclude("@pleasings//rust")

    rust_library(
        name = "my_rust_lib",
        srcs = ["mine.rs"],
    )

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.

To avoid adding the subinclude() to every BUILD file, you can add that target to the list of automatically included targets in your .plzconfig:

    
    
    [Parse]
    PreloadSubincludes = @pleasings//rust

The more repeatable solution

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.

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 //build_defs but of course this package can be anywhere. You'd set up //build_defs/BUILD as follows:

    
    
    package(default_visibility = ["PUBLIC"])

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

Then from any other package in your repo you could write the following:

    
    
    subinclude("//build_defs:rust")

    rust_library(
        name = "my_rust_lib",
        srcs = ["mine.rs"],
    )

This has the advantage of a shorter call to subinclude 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.