Please Plugins

Plugins are a way to extend Please with build rules for additional languages or technologies. The quickest way to get started is by running plz init plugin [go|python|java]. The full list of available plugins can be found here.

Plugins are configured in your .plzconfig file. For example, to load the python plugin, add the following to your .plzconfig file:

    
    
    [Plugin "python"]
    Target = //plugins:python
    DefaultInterpreter = python3 # Optional config
    

Where Target = //plugins:python is the plugin_repo() target for your plugin. For example:


    
    plugin_repo(
        name = "python",
        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

c_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, optional_outs)

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
optional_outs list Name of optional outputs.

c_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 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 :) Args:
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_library

c_library(name, srcs, hdrs, private_hdrs, deps, out, optional_outs, 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').
optional_outs list Name of optional outputs.
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_object

c_object(name, src, hdrs, private_hdrs, out, optional_outs, 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.
optional_outs list Name of optional outputs.
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

c_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, optional_outs)

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
optional_outs list Name of optional outputs.

c_static_library

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

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
optional_outs list Name of optional outputs.

c_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.

cc_binary

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

Builds a binary from a collection of C++ rules.

Argument Required Type
name yes str Name of the rule
srcs list C or 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 --libs`
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.
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.
linkstatic bool Only provided for Bazel compatibility. Has no actual effect since we always link roughly equivalently to their "mostly-static" mode.
labels list Labels to attach to this rule.
optional_outs list Name of optional outputs.

cc_embed_binary

cc_embed_binary(name, src, deps, visibility, test_only, namespace)

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 cc_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 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 :) Args:
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.
namespace str Allows specifying the namespace the symbols will be available in.

cc_library

cc_library(name, srcs, hdrs, private_hdrs, deps, out, optional_outs, visibility, test_only, compiler_flags, linker_flags, pkg_config_libs, pkg_config_cflags, includes, defines, alwayslink, linkstatic, textual_hdrs, 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').
optional_outs list Name of optional outputs.
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.
linkstatic bool Only provided for Bazel compatibility. Has no actual effect.
textual_hdrs list Also provided for Bazel compatibility. Effectively works the same as hdrs for now.
labels list Labels to attach to this rule.

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, optional_outs)

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.
optional_outs list Name of optional outputs.

cc_object

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

Generate a C or C++ object file from a single source.

N.B. This is fairly low-level; for most use cases cc_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.
optional_outs list Name of optional outputs.
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.
visibility list Visibility declaration for this rule.
deps list Dependent rules.
labels list Labels to attach to this rule.

cc_shared_object

cc_shared_object(name, srcs, hdrs, out, optional_outs, 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 lib<name>.so (or just <name>.so if name already begins with 'lib').
optional_outs list Name of optional outputs.
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 --libs`
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 Labels to attach to this rule.

cc_static_library

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

Generates a C++ static library (.a).

This is essentially just a collection of other cc_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.
out str Name of the output library. Defaults to lib<name>.a (or just <name>.a if name already begins with 'lib').
optional_outs list Name of optional outputs.
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 --libs`
pkg_config_cflags list Libraries to declare a dependency on using `pkg-config --cflags`
labels list Labels to attach to this rule.

cc_test

cc_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, write_main, linkstatic)

Defines a C++ test.

We template in a main file so you don't have to supply your own.
(Later we might allow that to be configured to help support other unit test frameworks).

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 --libs`
pkg_config_cflags list Libraries to declare a dependency on using `pkg-config --cflags`
deps list Dependent rules.
worker str Reference to worker script, A persistent worker process that is used to set up the test.
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.
write_main bool Deprecated, has no effect. See `plz help testmain` for more information about how to define a default dependency for the test main.
linkstatic bool Only provided for Bazel compatibility. Has no actual effect since we always
link roughly equivalently to their "mostly-static" mode.

[Plugin "cc"]

  • DefaultDbgCFlags (string)

    The default c compiler flags when compiling for debug

    If set, DefaultDbgCFlags is inherited from the host repo.

    Defaults to --std=c99 -g3 -pipe -DDEBUG -Wall -Werror

  • DsymTool (string)

    Set this to dsymutil or equivalent on MacOS to use this tool to generate xcode symbol information for debug builds.

    If set, DsymTool is inherited from the host repo.

  • PkgConfigPath (string)

    A path to the systems package configs

    If set, PkgConfigPath is inherited from the host repo.

  • CoverageTool (string)

    The path or build target for the C coverage analysis tool

    If set, CoverageTool is inherited from the host repo.

    Defaults to gcov

  • CCTool (string)

    The path or build label for the C compiler

    If set, CCTool is inherited from the host repo.

    Defaults to gcc

  • LDTool (string)

    If set, LDTool is inherited from the host repo.

    Defaults to ld

  • ARTool (string)

    If set, ARTool is inherited from the host repo.

    Defaults to ar

  • TestMain (string)

    A build label with c/c++ source code to use run tests.

    If set, TestMain is inherited from the host repo.

    Defaults to //unittest-pp:main

  • AsmTool (string)

    The tool to use for assembling assembly code

    If set, AsmTool is inherited from the host repo.

    Defaults to nasm

  • DefaultNamespace (string)

    The default namespace to compile c++ code in

  • Coverage (bool)

    Whether to build with coverage

    If set, Coverage is inherited from the host repo.

    Defaults to true

  • CPPTool (string)

    The path or build label for the C++ compiler

    If set, CPPTool is inherited from the host repo.

    Defaults to g++

  • DefaultOptCFlags (string)

    The default c compiler flags when compiling for release

    If set, DefaultOptCFlags is inherited from the host repo.

    Defaults to --std=c99 -O3 -pipe -DNDEBUG -Wall -Werror

  • DefaultLdFlags (string)

    The default set of flags to apply when linking

    If set, DefaultLdFlags is inherited from the host repo.

    Defaults to -lpthread -ldl

  • DefaultOptCppFlags (string)

    The default c++ compiler flags when compiling for release

    If set, DefaultOptCppFlags is inherited from the host repo.

    Defaults to --std=c++11 -O3 -pipe -DNDEBUG -Wall -Werror

  • DefaultDbgCppFlags (string)

    The default c++ compiler flags when compiling for debug

    If set, DefaultDbgCppFlags is inherited from the host repo.

    Defaults to --std=c++11 -g3 -pipe -DDEBUG -Wall -Werror

Go rules

cgo_library

cgo_library(name, srcs, resources, go_srcs, c_srcs, hdrs, package, compiler_flags, linker_flags, pkg_config, subdir, deps, labels, 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.
labels list Labels for this rule.
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.

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_benchmark

go_benchmark(name, srcs, resources, 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.
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
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.

go_binary

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

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 or dict 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`.
strip bool Determines whether the binary will be stripped of debug symbols or not. By
default the value of the strip_binaries plugin configuration option is used;
if this is not set, whether or not the binary is stripped depends on the
build mode.

go_library

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

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 Labels for this rule.
package str The package as it would appear at the top of the go source files. Defaults to name.
pgo_file str The CPU profile to supply for profile-guided optimisation.

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

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_repo() in that it compiles the whole go module in one build action. This can lead to
issues when modules are cyclically dependent on each other. For this reason, go_repo is recommended over go_module().

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_repo

go_repo(module, version, download, name, install, requirements, licences, patch, visibility, deps, build_tags, third_party_path, strip, labels)

Adds a third party go module to the build graph as a subrepo. This is designed to be closer to how the `go.mod`
file works, requiring only the module name and version to be specified. Unlike go_module, each package is compiled
individually, and dependencies between packages are inferred by convention.

This build definition is designed to replace go_module(), requiring less toil to keep up to date, and improving
incrementalism and minimalism by compiling each package, rather than the whole module.

By convention, modules will be registered in subrepos of the same name, replacing forward slashes with
underscores, e.g. `github.com/stretchr/testify` becomes `github.com_stretchr_testify`. Assuming `go_repo` is
being used in the standard third party package, `//third_party/go`, the import path
`github.com/stretchr/testify/assert` is then always resolved to the build label
`///third_party/go/github.com_stretchr_testify//assert`. Similarly, binary targets are also generated for any "main"
package, which can be ran with `plz run` or used as tools e.g. to generate protobuf files.

To avoid cumbersome build labels, you may optionally pass a list of go package wildcards to the install argument of
this build definition. For example, passing in `name = "testify"`, and `install = ["assert"]`, you may depend on
`//third_party/go:testify`, instead of the individual packages within, e.g.
`///third_party/go/github.com_stretchr_testify//assert`

Argument Required Type
module yes str The name of the module
version str The version of the module to download, if not providing the download parameter
download str A build rule to download the module, usually a go_mod_download().
name str The name of the returned rule. Defaults to the module name with forward slashes replaced with underscores.
install list Optional list of package wildcards to return from this rule. This can be useful to avoid cumbersome labels when depending on this module.
requirements list A list of requirements of this module that are not defined in its go.mod file
licences list The licence of this module to be checked against the allowed licences configured in Please.
patch list Any patch files to apply to the downloaded module.
visibility list The visibility for the returned "install" rule. Doesn't affect the subrepo at all.
deps list Any deps on other rule kinds that provide packages, for example go_module(). This can be used to migrate to go_repo incrementally, one module at a time.
build_tags list Build tags to pass to the Go compiler.
third_party_path str Optional path of third_party directory.
strip list A list of directories to strip from the repo
labels list Labels for this rule.

go_stdlib

go_stdlib(name, tags, labels, visibility)

Defines compilation of the Go standard library.

This is idiomatically configured in //third_party/go and set as the gostdlib config value for the Go plugin.

Argument Required Type
name yes str Name of the rule
tags list Go build tags (e.g. 'osusergo' or 'netgo' are relevant to the stdlib)
labels list Additional labels for this rule
visibility list Visibility of this rule

go_system_toolchain

go_system_toolchain(name, cmd, architectures, tags, install_std, labels, visibility)

Defines a Go toolchain that's installed on the local system.

This is similar to using simply `go` as your gotool, but from 1.20 onwards it's necessary in order to
compile the standard library.

Argument Required Type
name yes str Name of the rule
cmd str Command to run to locate it (usually just 'go')
architectures list Architectures to build the standard library for
tags list Build tags to pass when installing the standard library.
install_std bool Whether we should build the standard library. On by default.
labels list Labels for this rule.
visibility list Visibility of this rule

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
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_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_toolchain

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

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.
labels list Labels for this rule.
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.
tags list Build tags to pass when installing the standard library.
install_std Whether we should install the standard library. This is required for go 1.20+. If not set,
Please will do whatever is appropriate based on the Go version.

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

[Plugin "go"]

  • CppCoverage (bool)

    Whether to build C components with coverage

    Defaults to false

  • SplitDebugInfo (optional bool)

    Split debug info for binaries into a separate, optional output.

  • FeatureFlags (repeatable optional string)

    Flags to enable in-development features, or toggle breaking changes

    If set, FeatureFlags is inherited from the host repo.

  • ArTool (string)

    Path to the ar archiving tool to use

    If set, ArTool is inherited from the host repo.

    Defaults to ar

  • GoTool (string)

    A file path or build label for the go tool to use

    If set, GoTool is inherited from the host repo.

    Defaults to go

  • Race (optional bool)

    Compile for the Go race detector

    If set, Race is inherited from the host repo.

    Defaults to false

  • TestRootCompat (bool)

    Changes the test working directory to be the package to be more inline with how go test works

    Defaults to false

  • StripTool (string)

    Tool to use to strip debug info. This is temporary and will be removed later!

    If set, StripTool is inherited from the host repo.

    Defaults to eu-strip

  • BuildTags (repeatable optional string)

    Build tags to pass to the Go compiler

  • GoCoverTool (optional string)

    A file path or build label for the go cover tool to use. If not set, go_tool will be used to find it.

    If set, GoCoverTool is inherited from the host repo.

  • Stdlib (optional string)

    The build label for a go_stdlib target used to re-compile the standard library for different architectures and build modes.

    If set, Stdlib is inherited from the host repo.

  • RequireLicences (bool)

    If set, the licences field on go_module and go_repo will be mandatory

    If set, RequireLicences is inherited from the host repo.

    Defaults to false

  • ValidateModuleVersion (bool)

    If set, the values of go_mod_download's module and version parameters will be validated.

    Defaults to false

  • GoCompileTool (optional string)

    A file path or build label for the go compile tool to use. If not set, go_tool will be used to find it.

    If set, GoCompileTool is inherited from the host repo.

  • LegacyImports (bool)

    Reverts back to the pre-v17 behavior of Please where packages could be imported as {dirname}/{package} rather than just {dirname}

    Defaults to False

  • Coverageredesign (bool)

    Support Go 1.20's coverage redesign. This option now has no effect and will be removed in a future major version of the go-rules plugin.

    If set, Coverageredesign is inherited from the host repo.

    Defaults to true

  • Buildmode (optional string)

    The Go build mode to target (see `go help buildmode` for info)

  • CgoEnabled (optional bool)

    If set, cgo will be enabled at build time.

    If set, CgoEnabled is inherited from the host repo.

    Defaults to false

  • DelveTool (string)

    The path to the delve tool used when debugging Go targets

    If set, DelveTool is inherited from the host repo.

    Defaults to dlv

  • DefaultStatic (bool)

    Whether to link binaries statically by default

    If set, DefaultStatic is inherited from the host repo.

    Defaults to false

  • StripBinaries (optional bool)

    Whether to strip generated Go binaries by default. This overrides the behaviour implied by the build mode - for example, building in dbg mode with this option set to true will still cause Go binaries to be stripped.

    If set, StripBinaries is inherited from the host repo.

  • PkgInfo (bool)

    Generate pkg info for Go targets

    Defaults to true

  • GoLinkTool (optional string)

    A file path or build label for the go link tool to use. If not set, go_tool will be used to find it.

    If set, GoLinkTool is inherited from the host repo.

  • PleaseGoTool (string)

    A path or build label for the please_go tool, an internal tool used to help build Go code

    If set, PleaseGoTool is inherited from the host repo.

    Defaults to //tools:please_go

  • CFlags (repeatable optional string)

    Any additional C flags to pass to the C compiler when compling cgo rules

    If set, CFlags is inherited from the host repo.

  • ModFile (optional string)

    A built target for a go.mod, which can help avoid the need to pass modules via requirements to go_repo.

  • ImportPath (optional string)

    The base import path when compiling first party Go code. This usually is set to the module name in go.mod.

  • CcTool (optional string)

    The C compiler to use with cgo rules

    If set, CcTool is inherited from the host repo.

    Defaults to cc

  • LdFlags (repeatable optional string)

    Any additional linker flags to pass to the linker when linking cgo libraries

    If set, LdFlags is inherited from the host repo.

Go proto rules

go_grpc_language

go_grpc_language()

Argument Required Type

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_proto_language

go_proto_language()

Argument Required Type

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

[Plugin "go_proto"]

  • GrpcPlugin (string)

    Defaults to grpc_go_plugin

  • ProtoDep (string)

    Defaults to //third_party/go:protobuf

  • GrpcDep (string)

    Defaults to //third_party/go:grpc

  • ProtoPlugin (string)

    Defaults to grpc_go_plugin

Java rules

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_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_runtime_image

java_runtime_image(name, out, modules, launcher_module, launcher_class, compression, strip_hdrs, strip_man_pages, jlink_args, data, toolchain, visibility, deps)

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

Argument Required Type
name yes str Name of the rule.
out str Name of the folder that contains the runtime image and the binary contained by it. Defaults to 'name'.
modules yes list Modules to be included in the runtime image.
launcher_module str The module to run in the launcher script. Has to be included in 'modules'. If omitted, no launcher script will be created.
launcher_class str The class within 'launcher_module' to run in the launcher script. Must be specified if 'launcher_module' is specified.
compression int the compression method to apply to resources. Refer to the jlink documentation for --compress for permitted values. Defaults to 2 (zip).
strip_hdrs bool Strip header files from runtime image. Defaults to True, since they are usually not needed at run time.
strip_man_pages bool Strip man pages from runtime image. Defaults to True.
jlink_args str Additional arguments to pass to jlink.
data list Deprecated, has no effect.
toolchain str The build target for a java_toolchain that will be used to build this image. If a toolchain is not defined, this rule falls back to using the jlink tool defined in the plugin configuration.
visibility list Visibility declaration of this rule.
deps list Dependencies of this rule.

java_test

java_test(name, srcs, resources, resources_root, data, deps, 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.
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.

java_toolchain

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

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.
hashes list A list of valid hashes for the produced rule.
jmod_includes dict Additional files to insert into the JDK's JMOD archive files in the jmod/ directory. Keys are the names of archives without the .jmod extension (e.g. "java.base"), and values are dicts mapping paths within the archive to the files or build targets that provide them.
visibility list Visibility of this rule. Defaults to PUBLIC.

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

[Plugin "java"]

  • JavacTool (string)

    Path to the Javac tool if not using java_toolchain

    If set, JavacTool is inherited from the host repo.

    Defaults to javac

  • TargetLevel (string)

    The target byte code language level

    If set, TargetLevel is inherited from the host repo.

    Defaults to 8

  • DefaultTestPackage (optional string)

    The default package to find the test entry point in

    If set, DefaultTestPackage is inherited from the host repo.

  • SourceLevel (string)

    The source level to use

    Defaults to 8

  • MavenRepo (repeatable string)

    The maven repo to use for maven_jar

    Defaults to [[https://repo1.maven.org/maven2 https://repo.maven.apache.org/maven2]]

  • JavaTool (string)

    Path to the Java tool if not using java_toolchain

    If set, JavaTool is inherited from the host repo.

    Defaults to java

  • JavacFlags (optional string)

    Any additional flags to pass to javac

    If set, JavacFlags is inherited from the host repo.

  • JavacTestFlags (optional string)

    Any additional flags to pass to javac for tests

    If set, JavacTestFlags is inherited from the host repo.

  • JunitRunner (string)

    The pass or build label for the junit test runner, a tool that runs .jar files containing junit tests

    If set, JunitRunner is inherited from the host repo.

    Defaults to ///java//tools:junit_runner

  • Toolchain (optional string)

    The build label for the java_toolchain rule. Use this instead of Javac.

    If set, Toolchain is inherited from the host repo.

  • RunSelfExecutablesWithJavaTool (string)

    Run self-executable JAR files outputted by this plugin's rules with the Java tool (whether standalone or from a java_toolchain)

    If set, RunSelfExecutablesWithJavaTool is inherited from the host repo.

    Defaults to False

  • JlinkTool (string)

    Path to the jlink tool if not using java_toolchain

    If set, JlinkTool is inherited from the host repo.

    Defaults to jlink

  • ReleaseLevel (optional string)

    The release byte code level

    If set, ReleaseLevel is inherited from the host repo.

  • Home (optional string)

    Sets the java home variable

    If set, Home is inherited from the host repo.

Proto rules

filter_srcs

filter_srcs(name, srcs, extension)

Argument Required Type
name yes
srcs yes
extension yes

grpc_languages

grpc_languages()

Argument Required Type

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.

merge_languages

merge_languages(lhs_dict, rhs_dict)

Argument Required Type
lhs_dict yes
rhs_dict yes

proto_build_defs

proto_build_defs(name, srcs, proto_languages, visibility)

Argument Required Type
name yes str The name of this rule
srcs yes str or list
proto_languages yes dict A map of proto language types to functions that return the `proto_language()` below.
e.g. `{"grpc_language": ["go_grpc_language"], "proto_language": ["go_proto_language"]}`
where `go_grpc_language` is a function that has a `return proto_language(...)`
visibility

proto_language

proto_language(language, build_def, additional_provides)

Returns the definition of how to build a particular language for proto_library or grpc_library.

This should be wrapped in a function so that the proto_languages() build definition below can

Argument Required Type
language yes str Name of the language (as we would name it).
build_def yes function The build definition lambda. Will be called with the same arguments proto_library was called with, except with an additional `tag` parameter which is to be applied to the final build rule. Should return
additional_provides list or dict Any additional tags from the rule generated by func that should be provided by
the final proto_library rule. The _{name}#{language} tag will already be provided.
Can be a dictionary if the provide key on the `proto_library` should differ from
the language rule. In which case, the key will be the key on the proto_library,
and the value will be the tag to provide from build_def.

proto_languages

proto_languages()

Argument Required Type

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.

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.

protoc_plugins

protoc_plugins(name, build_defs, type, visibility)

Argument Required Type
name yes str The name of the rule
build_defs yes list Build rules outputting the .build_defs files that contain the proto_language() definitions.
type yes str The type of languages to collect. This should match the keys on the `proto_languages` dictionary
passed to `proto_build_defs()`.
visibility

[Plugin "proto"]

  • LanguageDef (repeatable optional string)

    A subinclude target containing a build definition that registers a new language using proto_language()

    If set, LanguageDef is inherited from the host repo.

  • ProtocTool (string)

    The protoc tool, as either a binary in the PATH or a build label

    Defaults to protoc

  • ProtocFlags (repeatable optional string)

    Any additional flags to pass to protoc

Python rules

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_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_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_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.

python_test

python_test(name, srcs, data, resources, deps, worker, labels, size, flags, visibility, sandbox, timeout, flaky, env, 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.
env dict Environment variables to pass to the test
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.

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, tool, prereleases, tool_verbosity)

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.

Wheel URLs are resolved in one or both of two ways:
* If `repo` is passed or `wheel_repo` is set in the .plzconfig, URLs are constructed using
`name_scheme` if passed, else `wheel_name_scheme` if set in the .plzconfig, else using some
reasonable defaults defined in _DEFAULT_WHEEL_NAME_SCHEMES.
* If `tool` is passed or `wheel_tool` is set in the .plzconfig, the tool is used to look up
URLs. If `repo` is also passed or `wheel_repo` is also set in the .plzconfig, the URLs
generated from the naming schemes are passed to the resolver tool.

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 or list The templatized wheel naming scheme(s) (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`
tool str Tool to locate python wheel file in an index
prereleases bool
tool_verbosity str

[Plugin "python"]

  • InterpreterOptions (string)

    Any additional flags to pass to the python interpreter

  • TestrunnerBootstrap (string)

  • ModuleDir (string)

    The path to the third party python directory, in python import path format e.g. third_party.py3 for //third_party/py3

    Defaults to third_party.python

  • DefaultPipRepo (optional string)

    The default repository to look for pip dependencies in

  • WheelTool (optional string)

    The tool used to resolve wheels with using the pypi API.

    If set, WheelTool is inherited from the host repo.

  • WheelNameScheme (repeatable optional string)

    A format string for the wheel repo URL. Format fields url_base, package_name, initial, and version. Initial is the first character of the package name.

  • Verbosity (optional string)

    Passes verbosity level to wheel_tool, for example: wheel_tool --verbosity info

    Defaults to info

  • PipFlags (optional string)

    Any additional flags to pass to pip

  • PipCompileFlags (optional string)

    Flags to pass to pip when compiling

    If set, PipCompileFlags is inherited from the host repo.

  • WheelRepo (optional string)

    The root URL for the wheel repo

  • Prereleases (bool)

    Allow prereleased versions in python_wheel targets

    Defaults to false

  • PipTool (optional string)

    The tool to use for pip. Defaults to using python -m pip

    If set, PipTool is inherited from the host repo.

  • UsePypi (bool)

    Whether to use PyPi as a repository for python_wheel

    Defaults to true

  • DisableVendorFlags (bool)

    Disables any vendor specific flags e.g. the --system flag passed to debians fork of pip

    If set, DisableVendorFlags is inherited from the host repo.

    Defaults to false

  • DefaultInterpreter (string)

    If set, DefaultInterpreter is inherited from the host repo.

    Defaults to python3

  • PexTool (string)

    A path or build label for the pex tool, which is used to create .pex files from python sources

    If set, PexTool is inherited from the host repo.

    Defaults to //tools:please_pex

  • TestRunner (string)

    The test runner to use e.g. unittest or pytest

    Defaults to unittest

  • TestrunnerDeps (string)

    A label for a build target containting the dependencies of the test runner

    Defaults to //third_party/python:unittest_bootstrap

  • Debugger (string)

    The debugger to use when debugging python binaries

    If set, Debugger is inherited from the host repo.

    Defaults to pdb

  • RequireLicences (bool)

    If set, the licences field on pip_library and python_wheel will be mandatory

    If set, RequireLicences is inherited from the host repo.

    Defaults to false

  • FeatureFlags (repeatable optional string)

    Flags to enable in-development features, or toggle breaking changes

    If set, FeatureFlags is inherited from the host repo.

Python proto rules

[Plugin "python_proto"]

  • ProtoPlugin (string)

    If set, ProtoPlugin is inherited from the host repo.

    Defaults to grpc_python_plugin

  • ProtoDep (string)

    If set, ProtoDep is inherited from the host repo.

    Defaults to //third_party/python:protobuf

  • GrpcDep (string)

    If set, GrpcDep is inherited from the host repo.

    Defaults to //third_party/python:grpc

Shell rules

rules for creating .sh files

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_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_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.

[Plugin "shell"]