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"]

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
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.
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
LDTool (string)

If set, LDTool is inherited from the host repo.

Defaults to ld
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
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
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
CPPTool (string)

The path or build label for the C++ compiler

If set, CPPTool is inherited from the host repo.

Defaults to g++
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
PkgConfigPath (string)

A path to the systems package configs

If set, PkgConfigPath is inherited from the host repo.
AsmTool (string)

The tool to use for assembling assembly code

If set, AsmTool is inherited from the host repo.

Defaults to nasm
Coverage (bool)

Whether to build with coverage

If set, Coverage is inherited from the host repo.

Defaults to true
CCTool (string)

The path or build label for the C compiler

If set, CCTool is inherited from the host repo.

Defaults to gcc
ARTool (string)

If set, ARTool is inherited from the host repo.

Defaults to ar
DefaultLdFlags (string)

The default set of flags to apply when linking

If set, DefaultLdFlags is inherited from the host repo.

Defaults to -lpthread -ldl
DefaultNamespace (string)

The default namespace to compile c++ code in

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"]

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.
Buildmode (optional string)

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

Generate pkg info for Go targets

Defaults to true
ValidateModuleVersion (bool)

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

Defaults to false
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
DefaultStatic (bool)

Whether to link binaries statically by default

If set, DefaultStatic is inherited from the host repo.

Defaults to false
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
BuildTags (repeatable optional string)

Build tags to pass to the Go compiler
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
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.
CgoEnabled (optional bool)

If set, cgo will be enabled at build time.

If set, CgoEnabled is inherited from the host repo.

Defaults to false
ArTool (string)

Path to the ar archiving tool to use

If set, ArTool is inherited from the host repo.

Defaults to ar
CppCoverage (bool)

Whether to build C components with coverage

Defaults to false
Race (optional bool)

Compile for the Go race detector

If set, Race is inherited from the host repo.

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.
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.
SplitDebugInfo (optional bool)

Split debug info for binaries into a separate, optional output.
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
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.
TestRootCompat (bool)

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

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.
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
ModFile (optional string)

A built target for a go.mod, which can help avoid the need to pass modules via requirements to go_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
ImportPath (optional string)

The base import path when compiling first party Go code. This usually is set to the module name in go.mod.
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
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.

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"]

ProtoPlugin (string)

Defaults to grpc_go_plugin
GrpcPlugin (string)

Defaults to grpc_go_plugin
ProtoDep (string)

Defaults to //third_party/go:protobuf
GrpcDep (string)

Defaults to //third_party/go:grpc

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
JavacFlags (optional string)

Any additional flags to pass to javac

If set, JavacFlags is inherited from the host repo.
JlinkTool (string)

Path to the jlink tool if not using java_toolchain

If set, JlinkTool is inherited from the host repo.

Defaults to jlink
SourceLevel (string)

The source level to use

Defaults to 8
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
Home (optional string)

Sets the java home variable

If set, Home 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.
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.
DefaultTestPackage (optional string)

The default package to find the test entry point in

If set, DefaultTestPackage is inherited from the host repo.
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
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
TargetLevel (string)

The target byte code language level

If set, TargetLevel is inherited from the host repo.

Defaults to 8
ReleaseLevel (optional string)

The release byte code level

If set, ReleaseLevel 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, interpreter)

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		dict or str	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
interpreter		str	The Python interpreter to use. Defaults to the value of the Python.DefaultInterpreter setting.

[Plugin "python"]

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
DefaultPipRepo (optional string)

The default repository to look for pip dependencies in
FeatureFlags (repeatable optional string)

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

If set, FeatureFlags is inherited from the host repo.
DefaultInterpreter (string)

If set, DefaultInterpreter is inherited from the host repo.

Defaults to python3
Debugger (string)

The debugger to use when debugging python binaries

If set, Debugger is inherited from the host repo.

Defaults to pdb
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
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.
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
Verbosity (optional string)

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

Defaults to info
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
UsePypi (bool)

Whether to use PyPi as a repository for python_wheel

Defaults to true
WheelTool (optional string)

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

If set, WheelTool is inherited from the host repo.
Prereleases (bool)

Allow prereleased versions in python_wheel targets

Defaults to false
InterpreterOptions (string)

Any additional flags to pass to the python interpreter
TestrunnerBootstrap (string)
PipTool (optional string)

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

If set, PipTool is inherited from the host repo.
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
WheelRepo (optional string)

The root URL for the wheel 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.

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.

Please Plugins

C/C++ rules

c_binary

c_embed_binary

c_library

c_object

c_shared_object

c_static_library

c_test

cc_binary

cc_embed_binary

cc_library

cc_module

cc_object

cc_shared_object

cc_static_library

cc_test

[Plugin "cc"]

DefaultDbgCppFlags (string)

DsymTool (string)

CoverageTool (string)

LDTool (string)

DefaultOptCFlags (string)

DefaultOptCppFlags (string)

TestMain (string)

CPPTool (string)

DefaultDbgCFlags (string)

PkgConfigPath (string)

AsmTool (string)

Coverage (bool)

CCTool (string)

ARTool (string)

DefaultLdFlags (string)

DefaultNamespace (string)

Go rules

cgo_library

cgo_test

go_benchmark

go_binary

go_library

go_mod_download

go_module

go_repo

go_stdlib

go_system_toolchain

go_test

go_test_main

go_toolchain

merge_cgo_obj

[Plugin "go"]

StripBinaries (optional bool)

Buildmode (optional string)

PkgInfo (bool)

ValidateModuleVersion (bool)

LegacyImports (bool)

DefaultStatic (bool)

PleaseGoTool (string)

BuildTags (repeatable optional string)

GoTool (string)

GoCoverTool (optional string)

CgoEnabled (optional bool)

ArTool (string)

CppCoverage (bool)

Race (optional bool)

GoCompileTool (optional string)

CFlags (repeatable optional string)

SplitDebugInfo (optional bool)

StripTool (string)

CcTool (optional string)

LdFlags (repeatable optional string)

TestRootCompat (bool)

FeatureFlags (repeatable optional string)

Coverageredesign (bool)

ModFile (optional string)

Stdlib (optional string)

RequireLicences (bool)

ImportPath (optional string)

DelveTool (string)

GoLinkTool (optional string)

Go proto rules