Please Plugins

Please plugins are a way to extend Please's functionality. They can be loaded into Please by adding them to the .plzconfig file. For example, to load the python plugin, add the following to your .plzconfig file:

    
    
    [Plugin "python"]
    target = //plugins:python
    

where //plugins:python is the target that builds the plugin. For example:


    
    plugin_repo(
        name = "python",
        plugin = "python-rules",
        revision = "v0.1.0",
    )
    

There are some first-class plugins that are supported and maintained by the Please team. These are listed below.

C/C++ rules

The cc-rules plugin provides rules for building C/C++ code.

c_library / cc_library

c_library(name, srcs, hdrs, private_hdrs, deps, out, visibility, test_only, compiler_flags, linker_flags, pkg_config_libs, pkg_config_cflags, includes, defines, alwayslink, labels)

Generate a C library target.

Argument Required Type
name yes str Name of the rule
srcs list C source files to compile.
hdrs list Header files. These will be made available to dependent rules, so the distinction between srcs and hdrs is important.
private_hdrs list Header files that are available only to this rule and not exported to dependent rules.
deps list Dependent rules.
out str Name of the output library. Defaults to lib<name>.a (or just <name>.a if name already begins with 'lib').
visibility list Visibility declaration for this rule.
test_only bool If True, is only available to other test rules.
compiler_flags list Flags to pass to the compiler.
linker_flags list Flags to pass to the linker; these will not be used here but will be picked up by a c_binary or c_test rule.
pkg_config_libs list Libraries to declare a dependency on using pkg-config. Again, the ldflags will be picked up by cc_binary or cc_test rules.
pkg_config_cflags list Libraries to declare a dependency on using `pkg-config --cflags`.
includes list List of include directories to be added to the compiler's path.
defines list or dict List of tokens to define in the preprocessor. Alternatively can be a dict of name -> value to define, in which case values are surrounded by quotes.
alwayslink bool If True, any binaries / tests using this library will link in all symbols, even if they don't directly reference them. This is useful for e.g. having static members that register themselves at construction time.
labels list Labels to attach to this rule.

c_static_library / cc_static_library

c_static_library(name, srcs, hdrs, compiler_flags, linker_flags, deps, out, visibility, test_only, pkg_config_libs, pkg_config_cflags, labels)

Generates a C static library (.a).

This is essentially just a collection of other c_library rules into a single archive.
Optionally this rule can have sources of its own, but it's quite reasonable just to use
it as a collection of other rules.

Argument Required Type
name yes str Name of the rule
srcs list C or C++ source files to compile.
hdrs list Header files.
compiler_flags list Flags to pass to the compiler.
linker_flags list Flags to pass to the linker.
deps list Dependent rules.
out str Name of the output library. Defaults to lib<name>.a (or just <name>.a if name already begins with 'lib').
visibility list Visibility declaration for this rule.
test_only bool If True, is only available to other test rules.
pkg_config_libs list Libraries to declare a dependency on using pkg-config
pkg_config_cflags list Libraries to declare a dependency on using `pkg-config --cflags`
labels list

c_shared_object / cc_shared_object

c_shared_object(name, srcs, hdrs, out, compiler_flags, linker_flags, deps, visibility, test_only, pkg_config_libs, pkg_config_cflags, includes, labels)

Generates a C shared object (.so) with its dependencies linked in.

Argument Required Type
name yes str Name of the rule
srcs list C or C++ source files to compile.
hdrs list Header files. These will be made available to dependent rules, so the distinction between srcs and hdrs is important.
out str Name of the output .so. Defaults to name + .so.
compiler_flags list Flags to pass to the compiler.
linker_flags list Flags to pass to the linker.
deps list Dependent rules.
visibility list Visibility declaration for this rule.
test_only bool If True, is only available to other test rules.
pkg_config_libs list Libraries to declare a dependency on using pkg-config
pkg_config_cflags list Libraries to declare a dependency on using `pkg-config --cflags`
includes list Include directories to be added to the compiler's lookup path.
labels list

c_binary / cc_binary

c_binary(name, srcs, hdrs, private_hdrs, compiler_flags, linker_flags, deps, visibility, pkg_config_libs, pkg_config_cflags, test_only, static, includes, defines, labels)

Builds a binary from a collection of C rules.

Argument Required Type
name yes str Name of the rule
srcs list C source files to compile.
hdrs list Header files.
private_hdrs list Header files that are available only to this rule and not exported to dependent rules.
compiler_flags list Flags to pass to the compiler.
linker_flags list Flags to pass to the linker.
deps list Dependent rules.
visibility list Visibility declaration for this rule.
pkg_config_libs list Libraries to declare a dependency on using pkg-config
pkg_config_cflags list Libraries to declare a dependency on using `pkg-config --cflags`
test_only bool If True, this rule can only be used by tests.
static bool If True, the binary will be linked statically.
includes list List of include directories to be added to the compiler's path.
defines list or dict List of tokens to define in the preprocessor. Alternatively can be a dict of name -> value to define, in which case values are surrounded by quotes.
labels list

c_test / cc_test

c_test(name, srcs, hdrs, compiler_flags, linker_flags, pkg_config_libs, pkg_config_cflags, deps, worker, data, visibility, flags, labels, flaky, test_outputs, size, timeout, sandbox)

Defines a C test target.

Note that you must supply your own main() and test framework (ala cc_test when
write_main=False).

Argument Required Type
name yes str Name of the rule
srcs list C or C++ source files to compile.
hdrs list Header files.
compiler_flags list Flags to pass to the compiler.
linker_flags list Flags to pass to the linker.
pkg_config_libs list Libraries to declare a dependency on using pkg-config
pkg_config_cflags list Libraries to declare a dependency on using `pkg-config --cflags`
deps list Dependent rules.
worker str
data list or dict Runtime data files for this test.
visibility list Visibility declaration for this rule.
flags str Flags to pass to the compiler.
labels list Labels to attach to this test.
flaky bool or int If true the test will be marked as flaky and automatically retried.
test_outputs list Extra test output files to generate from this test.
size str Test size (enormous, large, medium or small).
timeout int Length of time in seconds to allow the test to run for before killing it.
sandbox bool Sandbox the test on Linux to restrict access to namespaces such as network.

c_embed_binary / cc_embed_binary

c_embed_binary(name, src, deps, visibility, test_only)

Build rule to embed an arbitrary binary file into a C library.

You can depend on the output of this as though it were a c_library rule.
There are five functions available to access the data once compiled, all of which are
prefixed with the file's basename:
filename_start(): returns a const char* pointing to the beginning of the data.
filename_end(): returns a const char* pointing to the end of the data.
filename_size(): returns the length of the data in bytes.
filename_start_nc(): returns a char* pointing to the beginning of the data.
This is a convenience wrapper using const_cast, you should not
mutate the contents of the returned pointer.
filename_end_nc(): returns a char* pointing to the end of the data.
Again, don't mutate the contents of the pointer.
You don't own the contents of any of these pointers so don't try to delete them :)

Argument Required Type
name yes str Name of the rule.
src yes str Source file to embed.
deps list Dependencies.
visibility list Rule visibility.
test_only bool If True, is only available to test rules.

c_object / cc_object

c_object(name, src, hdrs, private_hdrs, out, test_only, compiler_flags, linker_flags, pkg_config_libs, pkg_config_cflags, includes, defines, alwayslink, visibility, deps, labels)

Generate a C object file from a single source.

N.B. This is fairly low-level; for most use cases c_library should be preferred.

Argument Required Type
name yes str Name of the rule
src yes str C or C++ source file to compile. This can be another rule, but if so it must have exactly one output.
hdrs list Header files. These will be made available to dependent rules, so the distinction between srcs and hdrs is important.
private_hdrs list Header files that are available only to this rule and not exported to dependent rules.
out str Name of the output file. Defaults to name + .o.
test_only bool If True, is only available to other test rules.
compiler_flags list Flags to pass to the compiler.
linker_flags list Flags to pass to the linker; these will not be used here but will be picked up by a c_binary or c_test rule.
pkg_config_libs list Libraries to declare a dependency on using pkg-config. Again, the ldflags will be picked up by cc_binary or cc_test rules.
pkg_config_cflags list Libraries to declare a dependency on using `pkg-config --cflags`. Again, the ldflags will be picked up by cc_binary or cc_test rules.
includes list List of include directories to be added to the compiler's path.
defines list or dict List of tokens to define in the preprocessor. Alternatively can be a dict of name -> value to define, in which case values are surrounded by quotes.
alwayslink bool If True, any binaries / tests using this library will link in all symbols,
even if they don't directly reference them. This is useful for e.g. having
static members that register themselves at construction time.
visibility list Visibility declaration for this rule.
deps list Dependent rules.
labels list

cc_module

cc_module(name, srcs, hdrs, interfaces, private_hdrs, deps, visibility, test_only, compiler_flags, linker_flags, pkg_config_libs, pkg_config_cflags, includes, defines, alwayslink, labels)

Generate a C++ module.

This is still experimental. Currently it has only been tested with clang; support for GCC
will be added later once versions of GCC supporting modules are more conveniently available.

Argument Required Type
name yes str Name of the rule
srcs list C++ source files to compile.
hdrs list Header files. These will be made available to dependent rules, so the distinction between srcs and hdrs is important.
interfaces list Module interface files. Again, these are treated differently to `srcs` in terms of compilation so the distinction is important.
private_hdrs list Header files that are available only to this rule and not exported to dependent rules.
deps list Dependent rules.
visibility list Visibility declaration for this rule.
test_only bool If True, is only available to other test rules.
compiler_flags list Flags to pass to the compiler.
linker_flags list Flags to pass to the linker; these will not be used here but will be picked up by a cc_binary or cc_test rule.
pkg_config_libs list Libraries to declare a dependency on using `pkg-config --libs`. Again, the ldflags will be picked up by cc_binary or cc_test rules.
pkg_config_cflags list Libraries to declare a dependency on using `pkg-config --cflags`. Again, the ldflags will be picked up by cc_binary or cc_test rules.
includes list List of include directories to be added to the compiler's path.
defines list or dict List of tokens to define in the preprocessor. Alternatively can be a dict of name -> value to define, in which case values are surrounded by quotes.
alwayslink bool If True, any binaries / tests using this library will link in all symbols, even if they don't directly reference them. This is useful for e.g. having static members that register themselves at construction time.
labels list Labels to attach to this rule.

Go rules

The go-rules plugin provides rules for building Go code.

go_toolchain

go_toolchain(name, url, version, hashes, visibility, architectures, strip_srcs, tags)

Downloads Go and exposes :<name>|go and :<name>|gofmt as entry points. To use this rule add the
following to your .plzconfig:

[go]
GoTool = //.../<name>|go

Argument Required Type
name yes str Name of the rule.
url str or dict The URL used to download Go. Can be a single string or a dictionary mapping GOOS-GOARCH to URLs i.e. linux-amd64: 'https://...'. Either provide url or version, but not both.
version str The version of Go to download. Go will be downloaded from https://golang.org/dl/... and the rule will use the current platforms GOOS and GOARCH setting. Either provide url or version, but not both.
hashes list A list of possible hashes for the downloaded archive. Optional.
visibility list Visibility specification. Defaults to public.
architectures list Any additional architectures to install in go architecture format e.g. linux_amd64. This rule will automatically install the arch provided through --arch. This is only useful if you want to manually cross-compile parts of the repo but not others.
strip_srcs bool Whether to strip sources from the SDK which can reduce the size of the cached artifacts and improve performance, especially for remote execution. This doesn't work with go_get() however it is recommended to set this to True if you're using go_module() exclusively.
tags list Build tags to pass when installing the standard library.

go_library

go_library(name, srcs, resources, asm_srcs, hdrs, deps, visibility, test_only, complete, cover, filter_srcs, import_path, labels, package)

Generates a Go library which can be reused by other rules.

Argument Required Type
name yes str Name of the rule.
srcs yes list Go source files to compile.
resources list Files to embed in the library using //go:embed directives.
asm_srcs list Source files to assemble with `go tool assemble`.
hdrs list Header files needed for assembly. Has no effect if asm_srcs is not given.
deps list Dependencies
visibility list Visibility specification
test_only bool If True, is only visible to test rules.
complete bool Indicates whether the library is complete or not (ie. buildable with `go tool build -complete`). In nearly all cases this is True (the main exception being for cgo).
cover bool Indicates whether this library should be considered for coverage annotations. Libraries are only annotated when using `plz cover` (or `plz build -c cover`), but if this is false they never will be. Can be useful for e.g. third-party code that you never want to be instrumented.
filter_srcs bool If True, filters source files through Go's standard build constraints.
import_path str If set, this will override the import path of the generated go package.
labels list
package str The package as it would appear at the top of the go source files. Defaults
to name.

cgo_library

cgo_library(name, srcs, resources, go_srcs, c_srcs, hdrs, package, compiler_flags, linker_flags, pkg_config, subdir, deps, visibility, test_only, import_path)

Generates a Go library which can be reused by other rules.

Note that by its nature this is something of a hybrid of Go and C rules. It can depend
on C / C++ rules, given the limitations of cgo (i.e. you will have to interact with them
through a C interface, although the objects themselves can contain C++). As mentioned
below, you will likely be better off wrapping your dependencies into a cc_static_library
rule and depending on that rather than depending directly on cc_library rules.

Note also that this does not honour Go's syntactic comments; you have to explicitly
specify which Go files are cgo vs. which are not, as well as C headers & sources and
any required cflags or ldflags.

Argument Required Type
name yes str Name of the rule.
srcs list Go source files to compile that have 'import "C"' declarations in them.
resources list Files to embed in the library using //go:embed directives.
go_srcs list Any Go source files that do *not* have 'import "C"' declarations.
c_srcs list Any C source files to include.
hdrs list Any C header files to include.
package str
compiler_flags list List of compiler flags to be passed when compiling the C code.
linker_flags list List of linker flags to be passed when linking a Go binary.
pkg_config list List of packages to pass to pkg-config.
subdir str Subdirectory that source files are in. Required if they're not in the current directory.
deps list Dependencies. Note that if you intend to depend on cc_library rules, you will likely be better off wrapping them into a cc_static_library and depending on that.
visibility list Visibility specification
test_only bool If True, is only visible to test rules.
import_path str If set, this will override the import path of the generated go package.

go_binary

go_binary(name, srcs, resources, asm_srcs, out, deps, data, visibility, labels, test_only, static, filter_srcs, definitions, stamp)

Compiles a Go binary.

Argument Required Type
name yes str Name of the rule.
srcs list Go source files, one of which contains the main function.
resources list Files to embed in the library using //go:embed directives.
asm_srcs list Assembly source files.
out str Name of the output file to create. Defaults to the same as `name`.
deps list Dependencies
data list Runtime dependencies of this rule.
visibility list Visibility specification
labels list Labels for this rule.
test_only bool If True, is only visible to test rules.
static bool If True, passes flags to the linker to try to force fully static linking. (specifically `-linkmode external -extldflags static`). Typically this increases size & link time a little but in return the binary has absolutely no external dependencies. Note that it may have negative consequences if the binary contains any cgo (including net/http DNS lookup code potentially).
filter_srcs bool If True, filters source files through Go's standard build constraints.
definitions str or list or dict If set to a string, defines importpath.name=value when calling the Go linker. If set to a list, pass each value as a definition to the linker. If set to a dict, each key/value pair is used to contruct the list of definitions passed to the linker.
stamp bool Allows this rule to gain access to information about SCM revision etc
via env vars. These can be useful to pass into `definitions`.

go_test

go_test(name, srcs, resources, data, deps, worker, visibility, flags, sandbox, cgo, filter_srcs, external, timeout, flaky, test_outputs, labels, size, static, definitions, env)

Defines a Go test rule.

Argument Required Type
name yes str Name of the rule.
srcs yes list Go source files to compile.
resources list Files to embed in the library using //go:embed directives.
data list or dict Runtime data files for the test.
deps list Dependencies
worker str Reference to worker script, A persistent worker process that is used to set up the test.
visibility list Visibility specification
flags str Flags to apply to the test invocation.
sandbox bool Sandbox the test on Linux to restrict access to namespaces such as network.
cgo bool True if this test depends on a cgo_library.
filter_srcs bool If True, filters source files through Go's standard build constraints.
external bool True if this test is external to the library it's testing, i.e. it uses the feature of Go that allows it to be in the same directory with a _test suffix.
timeout int Timeout in seconds to allow the test to run for.
flaky bool or int True to mark the test as flaky, or an integer to specify how many reruns.
test_outputs list Extra test output files to generate from this test.
labels list Labels for this rule.
size str Test size (enormous, large, medium or small).
static bool If True, passes flags to the linker to try to force fully static linking. (specifically `-linkmode external -extldflags static`). Typically this increases size & link time a little but in return the binary has absolutely no external dependencies. Note that it may have negative consequences if the binary contains any cgo (including net/http DNS lookup code potentially).
definitions str or list or dict If set to a string, defines importpath.name=value when calling the Go linker. If set to a list, pass each value as a definition to the linker. If set to a dict, each key/value pair is used to contruct the list of definitions passed to the linker.
env dict Additional environment variables to set for the test

go_benchmark

go_benchmark(name, srcs, data, deps, visibility, sandbox, cgo, filter_srcs, external, timeout, labels, static, definitions, test_only)

Defines a Go test suite that will be run as a benchmark.

Argument Required Type
name yes str Name of the rule.
srcs yes list Go source files to compile.
data list or dict Runtime data files for the test.
deps list Dependencies
visibility list Visibility specification
sandbox bool Sandbox the test on Linux to restrict access to namespaces such as network.
cgo bool True if this test depends on a cgo_library.
filter_srcs bool If True, filters source files through Go's standard build constraints.
external bool True if this test is external to the library it's testing, i.e. it uses the feature of Go that allows it to be in the same directory with a _test suffix.
timeout int Timeout in seconds to allow the test to run for.
labels list Labels for this rule.
static bool If True, passes flags to the linker to try to force fully static linking. (specifically `-linkmode external -extldflags static`). Typically this increases size & link time a little but in return the binary has absolutely no external dependencies. Note that it may have negative consequences if the binary contains any cgo (including net/http DNS lookup code potentially).
definitions str or list or dict If set to a string, defines importpath.name=value when calling the Go linker. If set to a list, pass each value as a definition to the linker. If set to a dict, each key/value pair is used to contruct the list of definitions passed to the linker.
test_only If True, is only visible to test rules.

cgo_test

cgo_test(name, srcs, data, deps, visibility, flags, sandbox, timeout, flaky, test_outputs, labels, size, static)

Defines a Go test rule over a cgo_library.

If the library you are testing is a cgo_library, you must use this instead of go_test.
It's ok to depend on a cgo_library though as long as it's not the same package
as your test; in that (any any other case of testing a go_library) you must use go_test.

Argument Required Type
name yes str Name of the rule.
srcs yes list Go source files to compile.
data list Runtime data files for the test.
deps list Dependencies
visibility list Visibility specification
flags str Flags to apply to the test invocation.
sandbox bool Sandbox the test on Linux to restrict access to namespaces such as network.
timeout int Timeout in seconds to allow the test to run for.
flaky bool or int True to mark the test as flaky, or an integer to specify how many reruns.
test_outputs list Extra test output files to generate from this test.
labels list Labels for this rule.
size str Test size (enormous, large, medium or small).
static bool If True, passes flags to the linker to try to force fully static linking.
(specifically `-linkmode external -extldflags static`).
Typically this increases size & link time a little but in return the binary
has absolutely no external dependencies.
It may not be easy to make cgo tests work when linked statically; depending
on your toolchain it may not be possible or may fail.

go_test_main

go_test_main(name, srcs, test_package, test_only, external, deps, visibility, benchmark, cover, labels)

Outputs the main file for a Go test.

This essentially does the test discovery and templates out the entry point from it. Note that
it only generates the main; you will likely need to arrange for compilation of the inputs via
a separate go_library rule.

Argument Required Type
name yes str Name of the rule
srcs yes list Source .go files that define the tests.
test_package str This is the import path of the package to be tested. Defaults to the import path of the current directory.
test_only bool If True, can only be consumed by tests (or other test_only rules).
external
deps list Any additional dependencies
visibility list Visibility of the rule.
benchmark bool If True, it will run benchmarks instead of tests.
cover bool Indicates whether this library should be considered for coverage annotations. Libraries are only annotated when using `plz cover` (or `plz build -c cover`), but if this is false they never will be. Can be useful for e.g. third-party code that you never want to be instrumented.
labels list Any labels to apply to this rule.

go_module

go_module(name, module, version, download, deps, exported_deps, visibility, test_only, binary, install, labels, hashes, licences, linker_flags, strip, env, patch, build_tags)

Defines a dependency on a third-party Go module.

Note that unlike a normal `go get` call, this does *not* install transitive dependencies.
You will need to add those as separate rules; `go list -f '{{.Deps}}' <package>` can be
useful to discover what they should be.

This rule is different to go_get() in that it is go module aware. It handles vanity imports and major versions
correctly so is the recommended approach.

Argument Required Type
name str Name of the rule
module yes str The module to compile
version str The version of the module.
download str Can be provided instead of version to manage downloading the module separately. This must be a rule that has a single output containing the go sources of the module. Usually this will be a go_mod_download() rule however it doesn't have to be. This can be used for a number of purposes but primarily it is for resolving cyclic dependencies between modules.
deps list Dependencies
exported_deps list Dependencies to make available to anything using this rule.
visibility list Visibility specification
test_only bool If true this rule will only be visible to tests.
binary bool True if the output of the rule is a binary.
install list Only install listed (sub)packages. If the dict form is used, each key should correspond to a target in 'get', with the value defining the list of packages to install for that target. Specify the empty string as an element in the list to install a target's root package.
labels list Additional labels to apply to this rule.
hashes list List of hashes to verify the downloaded sources against.
licences list Licences this rule is subject to.
linker_flags list Any additional linker flags to apply. Linker flags defined in the module itself will automatically be collected so this is typically not necessary.
strip list List of paths to strip from the target after downloading but before building it.
env dict Any env variables to set during build time. This can be useful to set CGO_CFLAGS etc. to control aspects of compilation.
patch list or str
build_tags list Any build tags to apply to the build context.

go_mod_download

go_mod_download(name, module, version, test_only, visibility, strip, licences, hashes, labels, deps, patch)

Downloads a third-party Go module using `go mod download`

This rule is typically used in conjunction with go_module() to resolve cyclic dependencies between modules. This rule
can be passed to go_module() via the download param which enables multiple go_module() rules to compile parts of the
whole module. It can also be useful to download from a fork of a module where the import path doesn't match the
repo path.

Argument Required Type
name yes str Name of the rule
module yes str The module to download
version yes str The version of the module.
test_only bool If true this rule will only be visible to tests.
visibility list Visibility specification
strip list List of paths to strip from the target after downloading but before building it.
licences list Licences this rule is subject to.
hashes list List of hashes to verify the downloaded sources against.
labels list Labels to apply to this rule.
deps list Dependencies
patch list

merge_cgo_obj

merge_cgo_obj(name, a_rule, o_rule, visibility, test_only, tag, linker_flags, deps, exported_deps, provides, package, labels)

Argument Required Type
name yes
a_rule yes
o_rule
visibility
test_only
tag
linker_flags list
deps
exported_deps
provides
package
labels list

Go-proto rules

The go-proto-rules plugin provides rules for building golang protobuf code.

go_proto_library

go_proto_library(name, srcs, deps, visibility, labels, test_only, root_dir, protoc_flags, additional_context)

Compile a .proto file to generate code for golang.

Argument Required Type
name yes str Name of the rule
srcs yes list Input .proto files.
deps list Dependencies (other grpc_library or proto_library rules)
visibility list Visibility specification for the rule.
labels list List of labels to apply to this rule.
test_only bool If True, this rule can only be used by test rules.
root_dir str The directory that the protos are compiled relative to. Useful if your proto files have import statements that are not relative to the repo root.
protoc_flags list Additional flags to pass to protoc.
additional_context dict This is unused. It will error if set

go_grpc_library

go_grpc_library(name, srcs, deps, visibility, labels, test_only, root_dir, protoc_flags, additional_context)

Defines a rule for a go grpc library.

Argument Required Type
name yes str Name of the rule
srcs yes list Input .proto files.
deps list Dependencies (other grpc_library or proto_library rules)
visibility list Visibility specification for the rule.
labels list List of labels to apply to this rule.
test_only bool If True, this rule can only be used by test rules.
root_dir str The directory that the protos are compiled relative to. Useful if your proto files have import statements that are not relative to the repo root.
protoc_flags list Additional flags to pass to protoc.
additional_context dict This is unused. It will error if set

go_grpc_language

go_grpc_language()

Argument Required Type

go_proto_language

go_proto_language()

Argument Required Type

Java rules

The java-rules plugin provides rules for building Java code.

java_library

java_library(name, srcs, src_dir, resources, resources_root, deps, modular, exported_deps, visibility, test_only, javac_flags, labels, toolchain)

Compiles Java source to a .jar which can be collected by other rules.

Argument Required Type
name yes str Name of the rule
srcs list Java source files to compile for this library
src_dir str Directory containing Java source files to compile.
resources list Resources to include in the .jar file
resources_root str Root directory to treat resources relative to; ie. if we are in //project/main/resources and resources_root is project/main then the resources in the .jar will be in the subdirectory 'resources'.
deps list Dependencies of this rule.
modular bool Whether the produced file should be modular. Only supported with java 9+.
exported_deps list Exported dependencies, ie. dependencies that other things depending on this rule will also receive when they're compiling. This is quite important for Java; any dependency that forms part of the public API for your classes should be an exported dependency.
visibility list Visibility declaration of this rule.
test_only bool If True, this rule can only be depended on by tests.
javac_flags list List of flags passed to javac.
labels list Additional labels to apply to this rule.
toolchain str A label identifying a java_toolchain rule which will be used to build this java library.

java_module

java_module(name, srcs, src_dir, resources, resources_root, deps, visibility, test_only, javac_flags, toolchain)

Compiles Java source to a modular .jar which can be collected by other rules.

Argument Required Type
name yes str Name of the rule
srcs list Java source files to compile for this library
src_dir str Directory containing Java source files to compile.
resources list Resources to include in the .jar file
resources_root str Root directory to treat resources relative to; ie. if we are in //project/main/resources and resources_root is project/main then the resources in the .jar will be in the subdirectory 'resources'.
deps list Dependencies of this rule.
visibility list Visibility declaration of this rule.
test_only bool If True, this rule can only be depended on by tests.
javac_flags list List of flags passed to javac.
toolchain str A label identifying a java_toolchain rule which will be used to build this java module.

java_binary

java_binary(name, main_class, out, srcs, deps, data, visibility, jvm_args, labels, self_executable, manifest, toolchain)

Compiles a .jar from a set of Java libraries.

Argument Required Type
name yes str Name of the rule.
main_class str Main class to set in the manifest.
out str Name of output .jar file. Defaults to name + .jar.
srcs list Source files to compile.
deps list Dependencies of this rule.
data list Runtime data for this rule.
visibility list Visibility declaration of this rule.
jvm_args str Arguments to pass to the JVM in the run script.
labels list any labels to apply to this rule.
self_executable bool True to make the jar self executable.
manifest str Manifest file to put into the jar. Can't be passed at the same time as main_class.
toolchain str A label identifying a java_toolchain rule which will be used to build this java binary.

java_runtime_image

java_runtime_image(name, main_module, main_class, modules, out, deps, data, visibility, jlink_args)

Assembles a set of modules into an executable java runtime image.

Argument Required Type
name yes str Name of the rule.
main_module yes str Main module to set in the manifest. Has to be included in 'modules'.
main_class yes str Main class to set in the manifest. Has to belong to 'main_module'.
modules yes list Modules to be included in the runtime image.
out str Name of the folder that contains the runtime image and the binary contained by it. Defaults to 'name'.
deps list Dependencies of this rule.
data list Deprecated, has no effect.
visibility list Visibility declaration of this rule.
jlink_args str Arguments to pass to the JVM in the run script.

java_test

java_test(name, srcs, resources, resources_root, data, deps, worker, labels, visibility, flags, sandbox, timeout, flaky, test_outputs, size, test_package, jvm_args, toolchain)

Defines a Java test.

Argument Required Type
name yes str Name of the rule.
srcs yes list Java files containing the tests.
resources list Resources to include in the .jar file
resources_root str Root directory to treat resources relative to; ie. if we are in //project/main/resources and resources_root is project/main then the resources in the .jar will be in the subdirectory 'resources'.
data list or dict Runtime data files for this rule.
deps list Dependencies of this rule.
worker str Reference to worker script, A persistent worker process that is used to set up the test.
labels list Labels to attach to this test.
visibility list Visibility declaration of this rule.
flags str Flags to pass to the test invocation.
sandbox bool Sandbox the test on Linux to restrict access to namespaces such as network.
timeout int Maximum length of time, in seconds, to allow this test to run for.
flaky bool or int True to mark this as flaky and automatically rerun.
test_outputs list Extra test output files to generate from this test.
size str Test size (enormous, large, medium or small).
test_package str Java package to scan for test classes to run.
jvm_args str Arguments to pass to the JVM in the run script.
toolchain str A label identifying a java_toolchain rule which will be used to run this java test.

maven_jar

maven_jar(name, id, repository, labels, hash, hashes, source_hashes, deps, visibility, filename, sources, licences, native, artifact_type, test_only, binary, classifier, classifier_sources_override)

Fetches a single Java dependency from Maven.

Argument Required Type
name yes str Name of the output rule.
id yes str Maven id of the artifact (eg. org.junit:junit:4.1.0)
repository str or list Maven repositories to fetch deps from.
labels list Additional labels to apply to this rule.
hash str Hash for produced rule.
hashes list List of hashes downloaded classes jar.
source_hashes list or str List of hashes for the downloaded sources jar.
deps list Labels of dependencies, as usual.
visibility list Visibility label.
filename str Filename we attempt to download. Defaults to standard Maven name.
sources bool True to download source jars as well.
licences list Licences this package is subject to.
native bool Attempt to download a native jar (i.e. add "-linux-x86_64" etc to the URL).
artifact_type str Type of artifact to download (defaults to jar but could be e.g. aar).
test_only bool If True, this target can only be used by tests or other test_only rules.
binary bool If True, we attempt to fetch and download an executable binary. The output is marked as such. Implies native=True and sources=False.
classifier str Maven classifier, allows to distinguish artifacts that were built from the same POM but differ in their content.
classifier_sources_override str Allows to override the classifier used to fetch the
source artifact.
e.g. logback-core-1.1.3-tests.jar and logback-core-1.1.3-test-sources.jar

java_toolchain

java_toolchain(name, jdk_url, jdk, visibility, hashes)

This is an experimental feature and is subject to breaking changes in minor releases.

Defines a toolchain that downloads a JDK that can be used with java languages rules. This can be configured in your
.plzconfig via the config option java.toolchain.

This rule is aliased please_java_toolchain as well. When Bazel compatibility is enabled, this alias must be used
instead.

Argument Required Type
name yes str Name of the rule.
jdk_url str or dict A URL to an archive containing a JDK distribution. Either this or jdk should be provided.
jdk str An archive of a jdk distribution or a label of a rule that produces one. Either this or jdk_url should be provided.
visibility list Visibility of this rule. Defaults to PUBLIC.
hashes list A list of valid hashes for the produced rule.

Proto rules

The proto-rules plugin provides rules for building protobuf code.

merge_languages

merge_languages(lhs_dict, rhs_dict)

Argument Required Type
lhs_dict yes
rhs_dict yes

proto_library

proto_library(name, srcs, deps, visibility, labels, languages, test_only, root_dir, protoc_flags, additional_context)

Compile a .proto file to generated code for various languages.

Argument Required Type
name yes str Name of the rule
srcs yes list Input .proto files.
deps list Dependencies
visibility list Visibility specification for the rule.
labels list List of labels to apply to this rule.
languages list or dict List of languages to generate rules for, chosen from the set {cc, py, go, java, js}. Alternatively, a dict mapping the language name to a definition of how to build it (see proto_language for more details of the values).
test_only bool If True, can only be used in test rules.
root_dir str The directory that the protos are compiled relative to. Useful if your proto files have import statements that are not relative to the repo root.
protoc_flags list Additional flags to pass to protoc. Note that these are inherited by further rules that depend on this one (because in nearly all cases that will be necessary for them to build too).
additional_context dict Additional language context to be passed to the `proto_language()` build definition.
This can be used to provide language specific parameters.

grpc_library

grpc_library(name, srcs, deps, visibility, languages, labels, test_only, root_dir, protoc_flags)

Defines a rule for a grpc library.

Argument Required Type
name yes str Name of the rule
srcs yes list Input .proto files.
deps list Dependencies (other grpc_library or proto_library rules)
visibility list Visibility specification for the rule.
languages list or dict List of languages to generate rules for, chosen from the set {cc, py, go, java}. Alternatively, a dict mapping the language name to a definition of how to build it (see proto_language for more details of the values).
labels list List of labels to apply to this rule.
test_only bool If True, this rule can only be used by test rules.
root_dir str The directory that the protos are compiled relative to. Useful if your proto files have import statements that are not relative to the repo root.
protoc_flags list Additional flags to pass to protoc.

protoc_binary

protoc_binary(name, url, version, hashes, deps, visibility)

Downloads a precompiled protoc binary.

You will obviously need to choose a version that is available on Github - there aren't
necessarily protoc downloads for every protobuf release.

Argument Required Type
name yes Name of the rule
url str or dict The URL used to download protoc. Can be a single string or a dictionary mapping HOSTOS-HOSTARCH to URLs i.e. linux-amd64: 'https://...'. Either provide url or version, but not both.
version str The version of protoc to download (e.g. '3.4.0'). Protoc will be downloaded from https://github.com/protocolbuffers/protobuf/releases/downaload/... and the rule will use the current platforms OS and ARCH setting. Either provide url or version, but not both.
hashes Hashes to verify the download against.
deps Any other dependencies
visibility Visibility of the rule.

Python rules

The python-rules plugin provides rules for building Python code.

python_library

python_library(name, srcs, resources, deps, visibility, test_only, zip_safe, labels, interpreter, strip)

Generates a Python library target, which collects Python files for use by dependent rules.

Note that each python_library performs some pre-zipping of its inputs before they're combined
in a python_binary or python_test. Hence while it's of course not required that all dependencies
of those rules are python_library rules, it's often a good idea to wrap any large dependencies
in one to improve incrementality (not necessary for pip_library, of course).

Argument Required Type
name yes str Name of the rule.
srcs list Python source files for this rule.
resources list Non-Python files that this rule collects which will be included in the final .pex. The distinction between this and srcs is fairly arbitrary and historical, but semantically quite nice and parallels python_test.
deps list Dependencies of this rule.
visibility list Visibility specification.
test_only bool If True, can only be depended on by tests.
zip_safe bool Should be set to False if this library can't be safely run inside a .pex (the most obvious reason not is when it contains .so modules). See python_binary for more information.
labels list Labels to apply to this rule.
interpreter str The Python interpreter to use. Defaults to the value of the Python.DefaultInterpreter setting.
strip bool If True, the original sources are stripped and only bytecode is output.

python_binary

python_binary(name, main, srcs, resources, out, deps, data, visibility, test_only, zip_safe, site, strip, interpreter, shebang, labels)

Generates a Python binary target.

This compiles all source files together into a single .pex file which can
be easily copied or deployed. The construction of the .pex is done in parts
by the dependent python_library rules, and this rule simply builds the
metadata for it and concatenates them all together.

This target can be debugged via:
plz debug [-o python.debugger:[pdb|debugpy]] [--port] //:target

Argument Required Type
name yes str Name of the rule.
main yes str Python file which is the entry point and __main__ module.
srcs list List of additional Python source files for this binary.
resources list List of static resources to include in the .pex.
out str Name of the output file. Default to name + .pex
deps list Dependencies of this rule.
data list Runtime data files for this rule.
visibility list Visibility specification.
test_only bool If True, can only be depended on by tests.
zip_safe bool Allows overriding whether the output is marked zip safe or not. If set to explicitly True or False, the output will be marked appropriately; by default it will be safe unless any of the transitive dependencies are themselves marked as not zip-safe.
site bool Allows the Python interpreter to import site; conversely if False, it will be started with the -S flag to avoid importing site.
strip bool Strips source code from the output .pex file, leaving just bytecode.
interpreter str The Python interpreter to use. Defaults to the value of the Python.DefaultInterpreter setting.
shebang str Exact shebang to apply to the generated file. By default we will determine something appropriate for the given interpreter.
labels list Labels to apply to this rule.

python_test

python_test(name, srcs, data, resources, deps, worker, labels, size, flags, visibility, sandbox, timeout, flaky, test_outputs, zip_safe, interpreter, site, test_runner)

Generates a Python test target.

This works very similarly to python_binary; it is also a single .pex file
which is run to execute the tests. The tests are run via either unittest, pytest, or behave, depending
on which is set for the test runner, which can be configured either via the python_test_runner
package property or python.testrunner in the config.

This target can be debugged via:
plz debug [-o python.debugger:[pdb|debugpy]] [--port] //:target

Argument Required Type
name yes str Name of the rule.
srcs yes list Source files for this test.
data list or dict Runtime data files for the test.
resources list Non-Python files to be included in the pex. Note that the distinction vs. srcs is important here; srcs are passed to unittest for it to run and it may or may not be happy if given non-Python files.
deps list Dependencies of this rule.
worker str Reference to worker script, A persistent worker process that is used to set up the test.
labels list Labels for this rule.
size str Test size (enormous, large, medium or small).
flags str Flags to apply to the test command.
visibility list Visibility specification.
sandbox bool Sandbox the test on Linux to restrict access to namespaces such as network.
timeout int Maximum time this test is allowed to run for, in seconds.
flaky bool or int True to mark this test as flaky, or an integer for a number of reruns.
test_outputs list Extra test output files to generate from this test.
zip_safe bool Allows overriding whether the output is marked zip safe or not. If set to explicitly True or False, the output will be marked appropriately; by default it will be safe unless any of the transitive dependencies are themselves marked as not zip-safe.
interpreter str The Python interpreter to use. Defaults to the value of the Python.DefaultInterpreter setting.
site bool Allows the Python interpreter to import site; conversely if False, it will be started with the -S flag to avoid importing site.
test_runner str Specify which Python test runner to use for these tests. One of
`unittest`, `pytest`, or a custom test runner entry point.

pip_library

pip_library(name, version, labels, hashes, package_name, test_only, deps, post_install_commands, install_subdirectory, repo, use_pypi, patch, visibility, zip_safe, licences, pip_flags, strip)

Provides a build rule for third-party dependencies to be installed by pip.

Argument Required Type
name yes str Name of the build rule.
version yes str Specific version of the package to install.
labels list Additional labels to apply to this rule.
hashes list List of acceptable hashes for this target.
package_name str Name of the pip package to install. Defaults to the same as 'name'.
test_only bool If True, can only be used by test rules or other test_only libraries.
deps list List of rules this library depends on.
post_install_commands list Commands run after pip install has completed.
install_subdirectory str Forces the package to install into a subdirectory with this name.
repo str Allows specifying a custom repo to fetch from.
use_pypi bool If True, will check PyPI as well for packages.
patch str or list A patch file or files to be applied after install.
visibility list Visibility declaration for this rule.
zip_safe bool Flag to indicate whether a pex including this rule will be zip-safe.
licences list Licences this rule is subject to. Default attempts to detect from package metadata.
pip_flags str List of additional flags to pass to pip.
strip list Files to strip after install. Note that these are done at any level.

python_wheel

python_wheel(name, version, labels, hashes, package_name, outs, post_install_commands, patch, licences, test_only, repo, zip_safe, visibility, deps, name_scheme, strip, binary, entry_points)

Downloads a Python wheel and extracts it.

This is a lightweight pip-free alternative to pip_library which supports cross-compiling.
Rather than leaning on pip which is difficult to achieve reproducible builds with and
support on different platforms, this rule is a simple wrapper around curl and unzip.
Unless otherwise specified, the wheels are expected to adhere to common naming schemes,
such as:
<package_name>-<version>[-<os>-<arch>].whl
<package_name>-<version>[-<os>_<arch>].whl
<package_name>-<version>.whl

Argument Required Type
name yes str Name of the rule. Also doubles as the name of the package if package_name is not set.
version yes str Version of the package to install.
labels list Additional labels to apply to this rule.
hashes list List of hashes to verify the package against.
package_name str If given, overrides `name` for the name of the package to look for.
outs list List of output files. Defaults to a directory named the same as `name`.
post_install_commands list Commands to run after 'install'.
patch str or list Patch file to apply after install to fix any upstream code that has done bad things.
licences list Licences that this rule is subject to.
test_only bool If True, this library can only be used by tests.
repo str Repository to download wheels from.
zip_safe bool Flag to indicate whether a pex including this rule will be zip-safe.
visibility list Visibility declaration.
deps list Dependencies of this rule.
name_scheme str The templatized wheel naming scheme (available template variables are `url_base`, `package_name`, `initial`, and `version`).
strip list Files to strip after install. Note that these are done at any level.
binary Whether this wheel should be executable. This assumes that the wheel will contain a __main__ module with a main() function. If this is not the case, then entry_points should be used.
entry_points Any entry points into this wheel. These relate to the entrypoints.txt in the dist-info of
the wheel, which define a module, and function in the format "module.path:function".
This parameter can be a string, in which case the rule can be ran directly, or a
dictionary, for example `{"protoc", "protoc.__main__:main"}. For the latter, each key can
be ran using annotated labels, e.g. `plz run //third_party/python:protobuf|protoc`

python_multiversion_wheel

python_multiversion_wheel(name, version, urls, licences, visibility, hashes)

Downloads and combines multiple Python wheels.

Note that python 2 does not support versioned object file names, so this can only work
for one python 2 wheel at a time. For us that's not an issue since we only support 2.7
(and these days that's nearly always what people are using, so often not a big deal).

The wheels are downloaded from the given list of URLs Within those directories, and
combined into a single wheel. Later files will overwrite earlier files however these
common files should be identical if all the wheels are for the same version. The new
files will be the platform specific files.

Argument Required Type
name yes Name of the rule. Also doubles as the name of the package if package_name is not set.
version yes str
urls yes list List of wheels to download.
licences list Licences that this wheel is subject to.
visibility
hashes list List of hashes to verify the package against. These are applied to all
downloads so don't need to be in any specific order.

Shell rules

The shell-rules plugin provides rules for building shell code.

sh_library

sh_library(name, src, deps, visibility, labels)

Generates a shell script binary, essentially just the given source.

Note that these are individually executable so can only have one source file each.
This is a bit tedious and would be nice to improve sometime.

Argument Required Type
name yes str Name of the rule.
src yes str Source file for the rule.
deps list Dependencies of this rule.
visibility list Visibility declaration of the rule.
labels list List of labels.

sh_binary

sh_binary(name, main, out, deps, data, visibility, labels)

Generates a shell script binary.

It assumes that unzip is in your path.

The resulting script will contain three things:
1) Code necessary to unzip dependent files.
2) The user defined shell script.
3) The zipfile containing all dependent files.

Argument Required Type
name yes str Name of the rule
main yes str or list The script to execute after all files have been uncompressed
out str Name of the output file to create. Defaults to name + .sh.
deps list Dependencies of this rule
data list Runtime data for this rule.
visibility list Visibility declaration of the rule.
labels list List of labels.

sh_cmd

sh_cmd(name, cmd, srcs, data, out, shell, labels, deps, visibility, expand_env_vars, test_only)

Generates a runnable shell script from a command.

This is doable with a genrule with a little effort but it's awkward enough to be nice
to have a builtin.
The command is subject to Please's usual variable expansion at build time. Note that if
you want `plz run` to transparently work and refer to other files, you may need to use
$(out_location ...) instead of $(location ...).

Argument Required Type
name yes str Name of the rule.
cmd yes str or dict or list Command to write into the output script file. The commands are subject to shell expansion during build time by default. If that is to be avoided, set expand_env_vars to False, or escape the variables with \\\$, i.e. \\\${@}.
srcs list or dict Source files. Can be consumed as env variables by the generated command (but are not written into the output in any other way).
data list Runtime data for this rule.
out str Name of the output file to create. Defaults to name + .sh.
shell str Shell to invoke in, by default /bin/sh.
labels list Labels to apply to this rule.
deps list Any dependencies for this rule. These can be consumed as env variables in the cmd but are not used in any other way.
visibility list Visibility declaration of the rule.
expand_env_vars bool Whether to expand
test_only bool If True, this rule can only be depended on by tests.

sh_test

sh_test(name, src, labels, data, deps, worker, size, visibility, flags, flaky, test_outputs, timeout, sandbox)

Generates a shell test. Note that these aren't packaged in a useful way.

Argument Required Type
name yes str Name of the rule
src str Test script file.
labels list Labels to apply to this test.
data list or dict Runtime data for the test.
deps list Dependencies of this rule
worker str Reference to worker script, A persistent worker process that is used to set up the test.
size str Test size (enormous, large, medium or small).
visibility list Visibility declaration of the rule.
flags str Flags to apply to the test invocation.
flaky bool or int True to mark this as flaky and automatically rerun.
test_outputs list Extra test output files to generate from this test.
timeout int Maximum length of time, in seconds, to allow this test to run for.
sandbox bool Sandbox the test on Linux to restrict access to namespaces such as network.