The Lexicon of Please

This is the reference for the complete set of builtin rules & functions.

Builtin functions

subinclude

subinclude(target)

Includes the output of a build target as extra rules in this one.

This is the closest equivalent to import in the BUILD language. It behaves somewhat differently though in that the contents of the subincluded file are added to the globals of the current module so can be called directly.

The target that you attempt to subinclude is simply a normal build target, with the restriction that it must have exactly one output. The simplest form of this is a single-file filegroup or export_file rule, but it is possible to have more complex rules generating your BUILD definitions.

For example:

subinclude('//build_defs:my_build_rules')

Note that you can also subinclude remote files as follows:

subinclude('https://raw.githubusercontent.com/thought-machine/pleasings/master/grm/grm.build_defs')

These are deduplicated internally so they're only downloaded & parsed once, so it's reasonably performant, although it's still often preferable to vendorise them yourself.

glob

glob(includes, excludes=None, hidden=False)

Matches all filenames by a pattern, in a manner reminiscent of shell-style pattern expansion or Python's builtin glob module.

Note that the only expansion patterns accepted are * to match an arbitrary number of non-separator characters (i.e. not /), and ** to match any number of complete path components.
These are often referred to as "Ant-style" patterns since Ant introduced them.

It bears noting that you cannot glob generated files, only source files. Also glob will not descend into any directories that contain a BUILD file; this maintains an invariant that each file is owned by exactly one package (or potentially none, but then Please doesn't know or care about them). If you want to pull in files from another package, export them there using a filegroup and depend on that in the package you want it.

Argument	Default	Type
includes		list	List of paths to include. Each is globbed separately.
excludes	None	list	List of filenames to exclude from any patterns matched by includes. These are subject to glob expansion of * themselves, but ** is not expanded (although since these are applied to each file found individually, it's not necessary).
hidden	False	bool	Set to True to include hidden files / folders.

get_labels

get_labels(target, prefix)

Gets the unique set of labels for a rule and all its transitive dependencies.

Two formats are accepted for target: the first is a string containing just the target name, which is resolved in the current package. This facilitates calling them from a pre-build function, which is in fact the only time it's safe to call this way.
The other is a full build target, which should be a transitive dependency of the target whose pre/post build function you're in. If the target isn't built when you ask for the labels the build will terminate.
In either case this is only safe to call from a pre / post-build function and should never be called at initial parse time, because at that point you generally don't have the full set of labels available yet.

Uses for this are normally fairly language-specific. The clearest example is maybe the builtin Python rules, where python_binary and python_test use this to identify if any of their dependencies have marked them as not being zip-safe.

Argument	Default	Type
target		str	Label of the target to get labels for.
prefix	None	str	Filters the returned labels to only ones starting with this prefix.

has_label

has_label(target, prefix)

Returns True if the target has any matching label that would be returned by get_labels.

Argument	Default	Type
target		str	Label of the target to get labels for.
prefix	None	str	Checks only labels that start with this prefix.

package

package(**kwargs)

Defines settings affecting the current package - for example, default visibility.

With this you can override any current value in CONFIG by name for all subsequent targets in the current package. Only existing values can be replaced.

There are also a couple of special values which aren't normally in CONFIG: default_licences and default_visibility. As the names suggest these set defaults for those attributes for all following targets that don't set them.

This function must be called before any targets are defined.

log

log.warning(message, [args...])

Logs an arbitrary message at some given level. The available levels, from most quiet to most severe, are:

• log.debug
• log.info
• log.notice
• log.warning
• log.error
• log.fatal

These correspond to Please's built in messages and are controlled as usual by the -v command-line argument.

As the name suggests, log.fatal immediately terminates the program with a fatal error. The others have no side effect other than showing the message.

The message and arguments together are interpolated like Python's normal string interpolation, similar to the builtin logging package.

C and C++ rules

Rules to build C and C++ targets.

The process of building C or C++ code is fairly complex so while these rules do their best to keep things reasonably simple, there's a lot of scope for things going wrong.

There is very little difference between the c_ and cc_ variants of each rule, in nearly all cases they simply use different tools and flags in the relevant config section.

c_library / cc_library

cc_library(name, srcs=None, hdrs=None, deps=None, visibility=None, test_only=False, compiler_flags=None, linker_flags=None, pkg_config_libs=None, archive=False)

Generate a C++ library target.

Argument	Default	Type
name		str	Name of the rule
srcs	None	list	C or C++ source files to compile.
hdrs	None	list	Header files. These will be made available to dependent rules, so the distinction between srcs and hdrs is important.
deps	None	list	Dependent rules.
visibility	None	list	Visibility declaration for this rule.
test_only	False	bool	If True, is only available to other test rules.
compiler_flags	None	list	Flags to pass to the compiler.
linker_flags	None	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	None	list	Libraries to declare a dependency on using pkg-config. Again, the ldflags will be picked up by cc_binary or cc_test rules.
alwayslink	False	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.

c_static_library / cc_static_library

cc_static_library(name, srcs=None, hdrs=None, compiler_flags=None, linker_flags=None, deps=None, visibility=None, test_only=False, pkg_config_libs=None)

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	Default	Type
name		str	Name of the rule
srcs	None	list	C or C++ source files to compile.
hdrs	None	list	Header files.
compiler_flags	None	list	Flags to pass to the compiler.
linker_flags	None	list	Flags to pass to the linker.
deps	None	list	Dependent rules.
visibility	None	list	Visibility declaration for this rule.
test_only	False	bool	If True, is only available to other test rules.
pkg_config_libs	None	list	Libraries to declare a dependency on using pkg-config.

c_shared_object / cc_shared_object

cc_shared_object(name, srcs=None, hdrs=None, compiler_flags=None, linker_flags=None, deps=None, visibility=None, test_only=False, pkg_config_libs=None)

Generates a C++ shared object with its dependencies linked in.

Argument	Default	Type
name		str	Name of the rule
srcs	None	list	C or C++ source files to compile.
hdrs	None	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 file. Defaults to name + '.so'.
compiler_flags	None	list	Flags to pass to the compiler.
linker_flags	None	list	Flags to pass to the linker.
deps	None	list	Dependent rules.
visibility	None	list	Visibility declaration for this rule.
test_only	False	bool	If True, is only available to other test rules.
pkg_config_libs	None	list	Libraries to declare a dependency on using pkg-config.

c_binary / cc_binary

cc_binary(name, srcs=None, hdrs=None, compiler_flags=None, linker_flags=None, deps=None, visibility=None, pkg_config_libs=None)

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

Argument	Default	Type
name		str	Name of the rule
srcs	None	list	C or C++ source files to compile.
hdrs	None	list	Header files.
compiler_flags	None	list	Flags to pass to the compiler.
linker_flags	None	list	Flags to pass to the linker.
deps	None	list	Dependent rules.
visibility	None	list	Visibility declaration for this rule.
pkg_config_libs	None	list	Libraries to declare a dependency on using pkg-config.
test_only	False	bool	If True, this binary can only be used by test rules or other test_only rules.
static	False	bool	Attempts to compile a static binary. Default is false for dynamic linking, but note that in either case the repo-internal libraries will still be linked statically.

c_test / cc_test

cc_test(name, srcs=None, compiler_flags=None, linker_flags=None, pkg_config_libs=None, deps=None, data=None, visibility=None, labels=None, flaky=False, test_outputs=None, timeout=0, container=False, write_main=True)

Defines a C++ test using UnitTest++.

If write_main is true (the default for C++) then we template in a main file so you don't have to supply your own.

Later we might add support for other test frameworks, for now you can add your own by setting write_main=False and writing your own main function.

Argument	Default	Type
name		str	Name of the rule
srcs	None	list	C or C++ source files to compile.
compiler_flags	None	list	Flags to pass to the compiler.
linker_flags	None	list	Flags to pass to the linker.
pkg_config_libs	None	list	Libraries to declare a dependency on using pkg-config.
deps	None	list	Dependent rules.
data	None	list	Runtime data files for this test.
visibility	None	list	Visibility declaration for this rule.
flags		str	Flags to apply to the test invocation - i.e. passed on the command line when it's run.
labels	None	list	Labels to attach to this test.
flaky		bool | int	If true the test will be marked as flaky and automatically retried.
test_outputs	None	list	Extra test output files to generate from this test.
timeout		int	Length of time in seconds to allow the test to run for before killing it.
container	False	bool | dict	If true the test is run in a container (eg. Docker).
write_main	True for cc_test, False for c_test	bool	If true then a main function is written automatically for you. This will only work in C++ mode since it uses UnitTest++.

c_embed_binary / cc_embed_binary

cc_embed_binary(name, src, deps=None, visibility=None, test_only=False, namespace=None)

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 :)

N.B. The implementation on OSX requires nasm, because Apple's ld doesn't support binary embedding. On other platforms it simply uses ld.

Argument	Default	Type
name		str	Name of the rule.
src		str	Source file to embed.
deps	None	list	Dependencies.
visibility	None	list	Rule visibility.
test_only	False	bool	If True, is only available to test rules.
namespace	None	str	Allows specifying the namespace the symbols will be available in. If not given you'll have to set it in .plzconfig

Go rules

Rules to build Go code.

Go has a strong built-in concept of packages so it's probably a good idea to match Please rules to Go packages.

go_library

go_library(name, srcs, out=None, deps=None, visibility=None, test_only=False, go_tools=None)

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

Argument	Default	Type
name		str	Name of the rule.
srcs		list	Go source files to compile.
out	None	str	Name of the output library to compile (defaults to name suffixed with .a)
deps	None	list	Dependencies
visibility	None	list	Visibility specification
test_only	False	bool	If True, is only visible to test rules.
go_tools	None	list	A list of targets to pre-process your src files with go generate.

go_generate

go_generate(name, srcs, tools, deps=None, visibility=None)

Generates a `go generate` rule.

Argument	Default	Type
name		str	Name of the rule.
srcs		list	Go source files to run go generate over.
tools		list	A list of targets which represent binaries to be used via `go generate`.
deps	None	list	Dependencies
visibility	None	list	Visibility specification

cgo_library

cgo_library(name, srcs, go_srcs, c_srcs, hdrs, env=None, deps=None, visibility=None, test_only=False, package)

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	Default	Type
name		str	Name of the rule.
srcs		list	Go source files to compile that have 'import "C"' declarations in them.
go_srcs		list	Go source files to compile that do not have 'import "C"' declarations.
hdrs		list	Any C header files to include.
c_srcs		list	Any C source files to include.
out	None	str	Name of the output file. Defaults to name + '.a'.
compiler_flags	None	list	List of compiler flags to be passed when compiling the C code. Roughly equivalent to cgo CFLAGS directives in source files.
linker_flags	None	list	List of linker flags to be passed when linking the C code. Roughly equivalent to cgo LDFLAGS directives in source files.
deps	None	list	Dependencies Note that if you intend to depend on cc_library rules, you will likely be better off wrapping them into a cc_static_library and depending on that.
visibility	None	list	Visibility specification
test_only	False	bool	If True, is only visible to test rules.

go_binary

go_binary(name, main=None, deps=None, visibility=None, test_only=False)

Compiles a Go binary.

Argument	Default	Type
name		str	Name of the rule.
main	None	str	Go source file containing the main function.
deps	None	list	Dependencies
visibility	None	list	Visibility specification
test_only	False	bool	If True, is only visible to test rules.
static	False	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. Not yet tested against cgo.

go_test

go_test(name, srcs, data=None, deps=None, visibility=None, container=False, timeout=0, flaky=False, test_outputs=None, labels=None)

Defines a Go test rule.

Argument	Default	Type
name		str	Name of the rule.
srcs		list	Go source files to compile.
data	None	list	Runtime data files for the test.
deps	None	list	Dependencies
visibility	None	list	Visibility specification
flags		str	Flags to apply to the test invocation - i.e. passed on the command line when it's run.
container	False	bool | dict	True to run this test in a container.
timeout		int	Timeout in seconds to allow the test to run for.
flaky		int | bool	True to mark the test as flaky, or an integer to specify how many reruns.
test_outputs	None	list	Extra test output files to generate from this test.
labels	None	list	Labels for this rule.

cgo_test

cgo_test(name, srcs, data=None, deps=None, visibility=None, container=False, timeout=0, flaky=False, test_outputs=None, labels=None, tags=None)

Defines a Go test rule for a library that uses cgo.

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.

Argument	Default	Type
name		str	Name of the rule.
srcs		list	Go source files to compile.
data	None	list	Runtime data files for the test.
deps	None	list	Dependencies
visibility	None	list	Visibility specification
flags		str	Flags to apply to the test invocation - i.e. passed on the command line when it's run.
container	False	bool | dict	True to run this test in a container.
timeout		int	Timeout in seconds to allow the test to run for.
flaky		int | bool	True to mark the test as flaky, or an integer to specify how many reruns.
test_outputs	None	list	Extra test output files to generate from this test.
labels	None	list	Labels for this rule.
tags	None	list	Tags to pass to go build (see 'go help build' for details).

go_get

go_get(name, get=None, outs=None, deps=None, visibility=None, patch=None, binary=False, test_only=False, install=None, revision=None)

Defines a dependency on a third-party Go library.

Argument	Default	Type
name		str	Name of the rule
get	None	str	Target to get (eg. "github.com/gorilla/mux")
outs	None	list	Output files from the rule. Default autodetects.
deps	None	list	Dependencies
visibility	None	list	Visibility specification
patch	None	str	Patch file to apply
binary	False	bool	True if the output of the rule is a binary.
test_only	False	bool	If true this rule will only be visible to tests.
install	None	list	Allows specifying extra packages to install. Convenient in some cases where we want to go get something with an extra subpackage.
revision	None	str	Git hash to check out before building. Only works for git at present, not for other version control systems.

Java rules

Built-in rules to compile Java code.

java_library

java_library(name, srcs=None, resources=None, resources_root=None, deps=None, exported_deps=None, visibility=None, source=None, target=None, test_only=False)

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

Argument	Default	Type
name		str	Name of the rule
srcs	None	list	Java source files to compile for this library
resources	None	list	Resources to include in the .jar file
resources_root	None	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	None	list	Dependencies of this rule.
exported_deps	None	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	None	list	Visibility declaration of this rule.
source	None	int	Java source level to compile sources as. Defaults to whatever's set in the config, which itself defaults to 8.
target	None	int	Java bytecode level to target after compile. Defaults to whatever's set in the config, which itself defaults to 8.
test_only	False	bool	If True, this rule can only be depended on by tests.

java_binary

java_binary(name, main_class, deps=None, data=None, visibility=None, jvm_args=None, self_executable=False)

Compiles a .jar from a set of Java libraries.

Argument	Default	Type
name		str	Name of the rule.
main_class		str	Main class to set in the manifest.
deps	None	list	Dependencies of this rule.
data	None	list	Runtime data files for this rule.
visibility	None	list	Visibility declaration of this rule.
jvm_args	None	str	Arguments to pass to the JVM in the run script.
self_executable	False	bool	True to make the jar self executable.

java_test

java_test(name, srcs, data=None, deps=None, labels=None, visibility=None, container=False, timeout=0, flaky=False, test_outputs=None, test_package=Set in config, jvm_args)

Defines a Java test.

Argument	Default	Type
name		str	Name of the rule.
srcs		list	Java files containing the tests.
data	None	list	Runtime data files for this rule.
deps	None	list	Dependencies of this rule.
labels	None	list	Labels to attach to this test.
visibility	None	list	Visibility declaration of this rule.
flags		str	Flags to apply to the test invocation - i.e. passed on the command line when it's run.
container	False	bool | dict	True to run this test within a container (eg. Docker).
timeout		int	Maximum length of time, in seconds, to allow this test to run for.
flaky		int | bool	True to mark this as flaky and automatically rerun.
test_outputs	None	list	Extra test output files to generate from this test.
test_package	Set in config	str	Java package to scan for test classes to run.
jvm_args		str	Arguments to pass to the JVM in the run script.

maven_jars

maven_jars(name, id, repository='https://repo1.maven.org/maven2', exclude=None, hashes=None, combine=False, hash=None, deps=None, visibility=None, filename=None, deps_only=False, optional=None)

Fetches a transitive set of dependencies from Maven.

Requires post build commands to be allowed for this repo.

Note that this is still fairly experimental; the interface is unlikely to change much but it still has issues with some Maven packages.

Argument	Default	Type
name		str	Name of the output rule.
id		str	Maven id of the artifact (eg. org.junit:junit:4.1.0)
repository	https://repo1.maven.org/maven2	str	Maven repo to fetch deps from.
exclude	None	list	Dependencies to ignore when fetching this one.
hashes	None	dict	Map of Maven id -> rule hash for each rule produced.
combine	False	bool	If True, we combine all downloaded .jar files into one uberjar.
hash	None	string	Hash of final produced .jar. For brevity, implies combine=True. Can optionally be a list for cases where there are jars with multiple possible outputs, e.g. architecture-specific.
deps	None	list	Labels of dependencies, as usual.
visibility	None	list	Visibility label.
filename	None	str	Filename we attempt to download. Defaults to standard Maven name.
deps_only	False	bool	If True we fetch only dependent rules, not this one itself. Useful for some that have a top-level target as a facade which doesn't have actual code.
optional	None	list	List of optional dependencies to fetch. By default we fetch none of them.

maven_jar

maven_jar(name, id, repository='https://repo1.maven.org/maven2', hash=None, hashes=None, deps=None, visibility=None, filename=None, sources=True, licences=None, exclude_paths=None, native=False)

Fetches a single Java dependency from Maven.

Argument	Default	Type
name		str	Name of the output rule.
id		str	Maven id of the artifact (eg. org.junit:junit:4.1.0)
repository	https://repo1.maven.org/maven2	str	Maven repo to fetch deps from.
hash	None	str	Hash for produced rule.
hashes	None	list	Hashes for produced rule. This is generally only useful for rules with native set, other jars will normally only have one hash.
deps	None	list	Labels of dependencies, as usual.
visibility	None	list	Visibility label.
filename	None	str	Filename we attempt to download. Defaults to standard Maven name.
sources	True	bool	True to download source jars as well.
licences	None	list	Licences this package is subject to.
exclude_paths	None	list	Paths to remove from the downloaded .jar.
native	False	bool	Attempt to download a native jar (i.e. add "-linux-x86_64" or "-osx-x86_64" etc to the URL).

Misc rules

Miscellaneous rules that aren't language-specific.

genrule

genrule(name, cmd, srcs=None, out=None, outs=None, deps=None, visibility=None, building_description=Building..., hashes=None, timeout=0, binary=False, needs_transitive_deps=False, output_is_complete=True, test_only=False, requires=None, provides=None, pre_build=None, post_build=None, tools=None)

A general build rule which allows the user to specify a command.

Argument	Default	Type
name		str	Name of the rule
cmd		str	Command to run. It's subject to various sequence replacements: $(location //path/to:target) expands to the location of the given build rule, which must have a single output only. $(locations //path/to:target) expands to the locations of the outputs of the given build rule, which can have any number of outputs. $(exe //path/to:target) expands to a command to run the output of the given target. The rule must be marked as binary. $(out_location //path_to:target) expands to the output of the given build rule, with the preceding plz-out/gen etc. Also a number of environment variables will be defined: ARCH: architecture of the system, eg. amd64 OS: current operating system (linux, darwin, etc). PATH: usual PATH environment variable as defined in your .plzconfig TMP_DIR: the temporary directory you're compiling within. SRCS: the sources of your rule OUTS: the outputs of your rule PKG: the path to the package containing this rule NAME: the name of this build rule OUT: the output of this rule. Only present when there is only one output. SRC: the source of this rule. Only present when there is only one source. SRCS_<suffix>: Present when you've defined named sources on a rule. Each group creates one of these these variables with paths to those sources.
srcs	None	list or dict	Sources of this rule. Can be a list of files or rules, or a dict of names to similar lists. In the latter case they can be accessed separately which is useful when you have separate kinds of things in a rule.
out	None	str	A single output of this rule, as a string. Discouraged in favour of 'outs'.
outs	None	list	Outputs of this rule.
deps	None	list	Dependencies of this rule.
visibility	None	list	Visibility declaration of this rule
building_description	Building...	str	Description to display to the user while the rule is building.
hashes	None	list	List of hashes; if given the outputs must match one of these. They can be optionally preceded by their method. Currently the only supported method is sha1.
timeout		int	Maximum time in seconds this rule can run for before being killed.
binary	False	bool	True to mark a rule that produces a runnable output. Its output will be placed into plz-out/bin instead of plz-out/gen and can be run with 'plz run'. Binary rules can only have a single output.
needs_transitive_deps	False	bool	If True, all transitive dependencies of the rule will be made available to it when it builds (although see below...). By default rules only get their immediate dependencies.
output_is_complete	True	bool	If this is true then the rule blocks downwards searches of transitive dependencies by other rules (ie. it will be available to them, but not its dependencies as well).
test_only	False	bool	If True it can only be used by test rules.
requires	None	list	A list of arbitrary strings that define kinds of output that this rule might want. See 'provides' for more detail; it's mostly useful to match up rules with multiple kinds of output with ones that only need one of them, eg. a proto_library with a python_library that doesn't want the C++ or Java proto outputs. Entries in 'requires' are also implicitly labels on the rule.
provides	None	dict	A map of arbitrary strings to dependencies of the rule that provide some specific type of thing. For example: provides = {'py': ':python_rule', 'go': ':go_rule'}, A Python rule would have requires = ['py'] and so if it depended on a rule like this it would pick up a dependency on :python_rule instead. See the proto rules for an example of where this is useful. Note that the keys of provides and entries in requires are arbitrary and have no effect until a matched pair meet one another.
pre_build	None	function	A function to be executed immediately before the rule builds. It receives one argument, the name of the building rule. This is mostly useful to interrogate the metadata of dependent rules which isn't generally available at parse time; see the get_labels function for a motivating example.
post_build	None	function	A function to be executed immediately after the rule builds. It receives two arguments, the rule name and its command line output. This is significantly more useful than the pre_build function, it can be used to dynamically create new rules based on the output of another.
tools	None	list	Tools used to build this rule; similar to srcs but are not copied to the temporary build directory. Should be accessed via $(exe //path/to:tool) or similar. Entries that are not build labels are assumed to be system-level commands and resolved within the path given in the config file (note that the value of $PATH in the outside environment is not propagated to the build rule).

gentest

gentest(name, test_cmd, labels=None, cmd=None, srcs=None, outs=None, deps=None, tools=None, data=None, visibility=None, timeout=0, needs_transitive_deps=False, flaky=False, no_test_output=False, output_is_complete=True, requires=None, container=False)

A rule which creates a test with an arbitrary command.

The command must return zero on success and nonzero on failure. Test results are written to test.results (or not if no_test_output is True).

Most arguments are similar to genrule() so we cover them in less detail here.

Argument	Default	Type
name		str	Name of the rule
test_cmd		str	Command to run for the test.
labels	None	list	Labels to apply to this test.
cmd	None	str	Command to run to build the test.
srcs	None	list or dict	Source files for this rule.
outs	None	list	Output files of this rule.
deps	None	list	Dependencies of this rule.
tools	None	list	Tools used to build this rule; similar to srcs but are not copied to the temporary build directory. Should be accessed via $(exe //path/to:tool) or similar.
data	None	list	Runtime data files for the test.
visibility	None	list	Visibility declaration of this rule.
timeout		int	Length of time in seconds to allow the test to run for before killing it.
needs_transitive_deps	False	bool	True if building the rule requires all transitive dependencies to be made available.
flaky		bool | int	If true the test will be marked as flaky and automatically retried.
no_test_output	False	bool	If true the test is not expected to write any output results, it's only judged on its return value.
output_is_complete	True	bool	If this is true then the rule blocks downwards searches of transitive dependencies by other rules.
requires	None	list	Kinds of output from other rules that this one requires.
container	False	bool | dict	If true the test is run in a container (eg. Docker).

export_file

export_file(name, src, visibility=None, binary=False, test_only=False)

Essentially a single-file alias for filegroup.

Argument	Default	Type
name		str	Name of the rule
src		str	Source file for the rule
visibility	None	list	Visibility declaration
binary	False	bool	True to mark the rule outputs as binary
test_only	False	bool	If true the exported file can only be used by test targets.

filegroup

filegroup(name, srcs=None, deps=None, exported_deps=None, visibility=None, labels=None, binary=False, output_is_complete=True, requires=None, provides=None, link=True, test_only=False)

Defines a collection of files which other rules can depend on.

Sources can be omitted entirely in which case it acts simply as a rule to collect other rules, which is often more handy than you might think.

Argument	Default	Type
name		str	Name of the rule
srcs	None	list	Source files for the rule.
deps	None	list	Dependencies of the rule.
exported_deps	None	list	Dependencies that will become visible to any rules that depend on this rule.
visibility	None	list	Visibility declaration
labels	None	list	Labels to apply to this rule
binary	False	bool	True to mark the rule outputs as binary
output_is_complete	True	bool	If this is true then the rule blocks downwards searches of transitive dependencies by other rules.
requires	None	list	Kinds of output from other rules that this one requires.
provides	None	dict	Kinds of output that this provides for other rules (see genrule() for a more in-depth discussion of this).
link	True
test_only	False	bool	If true the exported file can only be used by test targets.

system_library

system_library(name, srcs, deps=None, hashes=None, visibility=None, test_only=False)

Defines a rule to collect some dependencies from outside the build tree.

This is essentially the same as a filegroup; it will simply copy files from the system into the build tree, you must add additional rules if compilation is necessary.

Argument	Default	Type
name
srcs
deps	None
hashes	None
visibility	None	list	Visibility declaration of the rule.
test_only	False	bool	If true the rule is only visible to test targets.

remote_file

remote_file(name, url, hashes=None, out=None, binary=False, visibility=None, test_only=False)

Defines a rule to fetch a file over HTTP(S).

Argument	Default	Type
name		str	Name of the rule
url		str	URL to fetch
hashes	None	list	List of hashes; the output must match at least one of these.
out	None	str	Output name of the file. Chosen automatically if not given.
binary	False	bool	True to mark the output as binary and runnable.
visibility	None	list	Visibility declaration of the rule.
test_only	False	bool	If true the rule is only visible to test targets.

github_file

github_file(name, repo, file, revision=master, hash=None, visibility=None, test_only=False)

Defines a rule to fetch a file from Github.

This is just a convenience wrapper around remote_file but is somewhat clearer to write.

Argument	Default	Type
name
repo
file
revision	master
hash	None
visibility	None	list	Visibility declaration of the rule.
test_only	False	bool	If true the rule is only visible to test targets.

fpm_package

fpm_package(name, files, version, package_type, links=None, package_name=None, options, srcs=None, deps=None, visibility=None, labels=None)

Defines a rule to build a package using fpm.

Argument	Default	Type
name		str	Rule name
files		dict	Dict of locations -> files to include, for example: { '/usr/bin/plz': '//src:please', '/usr/share/plz/junit_runner': '//src/build/java:junit_runner', '/usr/share/plz/some_file': 'some_file', # file in this package }
version		str	Version of the package.
package_type		str	Type of package to build (deb, rpm, etc)
links	None	dict	Dict of locations -> file to link to, for example: { '/usr/bin/plz': '/opt/please', }
package_name	None	str	Name of package. Defaults to rule name.
options		str	Extra options to pass to fpm.
srcs	None	list	Extra sources (it's not necessary to mention entries in 'files' here)
deps	None	list	Dependencies
visibility	None	list	Visibility specification.
labels	None	list	Labels associated with this rule.

fpm_deb

fpm_deb(name, files, version, links=None, package_name=None, options, srcs=None, deps=None, visibility=None, labels=None)

Convenience wrapper around fpm_package that always builds a .deb package.

Argument	Default	Type
name		str	Rule name
files		dict	Dict of locations -> files to include, for example: { '/usr/bin/plz': '//src:please', '/usr/share/plz/junit_runner': '//src/build/java:junit_runner', '/usr/share/plz/some_file': 'some_file', # file in this package }
version		str	Version of the package.
links	None	dict	Dict of locations -> file to link to, for example: { '/usr/bin/plz': '/opt/please', }
package_name	None	str	Name of package. Defaults to rule name.
options		str	Extra options to pass to fpm.
srcs	None	list	Extra sources (it's not necessary to mention entries in 'files' here)
deps	None	list	Dependencies
visibility	None	list	Visibility specification.
labels	None	list	Labels associated with this rule.

tarball

tarball(name, srcs, out=None, deps=None, subdir=None, compression=gzip, visibility=None, labels=None)

Defines a rule to create a tarball containing outputs of other rules.

Argument	Default	Type
name		str	Rule name
srcs		list	Source files to include in the tarball
out	None	str	Name of output tarball (defaults to `name`.tar.gz, but see below re compression)
deps	None	list	Dependencies
subdir	None	str	Subdirectory to create in (defaults to 'name')
compression	gzip	str	Kind of compression to use. Either one of {gzip, bzip2, xz, lzma} to filter through known tar methods, an explicit flag, or None for no compression.
visibility	None	list	Visibility specification.
labels	None	list	Labels associated with this rule.

Proto rules

Build rules for compiling protocol buffers & gRPC service stubs.

Note that these are some of the most complex of our built-in build rules, because of their cross-language nature. Each proto_library rule declares a set of sub-rules to run protoc & the appropriate java_library, go_library rules etc. Users shouldn't worry about those sub-rules and just declare a dependency directly on the proto_library rule to get its appropriate outputs.

proto_library

proto_library(name, srcs, plugins=None, deps=None, visibility=None, labels=None, python_deps=None, cc_deps=None, java_deps=None, go_deps=None, protoc_version=Set in config, languages=None)

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

Argument	Default	Type
name		str	Name of the rule
srcs		list	Input .proto files.
plugins	None	dict	Plugins to invoke for code generation.
deps	None	list	Dependencies
visibility	None	list	Visibility specification for the rule. labels(list): List of labels to apply to this rule.
labels	None
python_deps	None	list	Additional deps to add to the python_library rules
cc_deps	None	list	Additional deps to add to the cc_library rules
java_deps	None	list	Additional deps to add to the java_library rules
go_deps	None	list	Additional deps to add to the go_library rules
protoc_version	Set in config	str	Version of protoc compiler, used to invalidate build rules when it changes.
languages	None	list	List of languages to generate rules for, chosen from the set {cc, py, go, java}.

grpc_library

grpc_library(name, srcs, deps=None, visibility=None, languages=None, python_deps=None, java_deps=None, go_deps=None)

Defines a rule for a grpc library.

Argument	Default	Type
name		str	Name of the rule
srcs		list	Input .proto files.
deps	None	list	Dependencies (other proto_library rules)
visibility	None	list	Visibility specification for the rule.
languages	None	list	List of languages to generate rules for, chosen from the set {cc, py, go, java}. At present this will not create any service definitions for C++, but 'cc' is still accepted for forwards compatibility.
python_deps	None	list	Additional deps to add to the python_library rules
java_deps	None	list	Additional deps to add to the java_library rules
go_deps	None	list	Additional deps to add to the go_library rules
cc_deps	None	list	Additional deps to add to the cc_library rules

Python rules

Rules to build Python code.

The output artifacts for Python rules are .pex files (see https://github.com/pantsbuild/pex).

Pex is a rather nice system for combining Python code and all needed dependencies (excluding the actual interpreter and possibly some system level bits) into a single file.

The process of compiling pex files can be a little slow when including many large files, as often happens when one's binary includes large compiled dependencies (eg. numpy...). Hence we have a fairly elaborate optimisation whereby each python_library rule builds a little zipfile containing just its sources, and all of those are combined at the end to produce the final .pex. This builds at roughly the same pace for a clean build of a single target, but is drastically faster for building many targets with similar dependencies or rebuilding a target which has only had small changes.

python_library

python_library(name, srcs=None, resources=None, deps=None, visibility=None, test_only=False, zip_safe=True, labels=None, interpreter=None)

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	Default	Type
name		str	Name of the rule.
srcs	None	list	Python source files for this rule.
resources	None	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	None	list	Dependencies of this rule.
visibility	None	list	Visibility specification.
test_only	False	bool	If True, can only be depended on by tests.
zip_safe	True	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	None	list	Labels to apply to this rule.
interpreter	Set in config	str	The Python interpreter to use. Defaults to the config setting which is normally just 'python', but could be 'python3' or 'pypy' or whatever.

python_binary

python_binary(name, main, out=None, deps=None, visibility=None, zip_safe=None, interpreter=Set in config)

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.

Argument	Default	Type
name		str	Name of the rule.
main		str	Python file which is the entry point and __main__ module.
resources		list	Non-Python files that this rule collects which will be included in the final .pex.
out	None	str	Name of the output file. Default to name + .pex
deps	None	list	Dependencies of this rule.
visibility	None	list	Visibility specification.
zip_safe	None	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	Set in config	str	The Python interpreter to use. Defaults to the config setting which is normally just 'python', but could be 'python3' or 'pypy' or whatever.
shebang		str	The exact shebang (minus the leading #!) to apply to the generated .pex. By default pex will choose something appropriate for the current interpreter, but this allows overriding it if you need something different.

python_test

python_test(name, srcs, data=None, resources=None, deps=None, labels=None, visibility=None, container=False, timeout=0, flaky=False, test_outputs=None, zip_safe=None, interpreter=Set in config)

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

Argument	Default	Type
name		str	Name of the rule.
srcs		list	Source files for this test.
data	None	list	Runtime data files for the test.
resources	None	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	None	list	Dependencies of this rule.
labels	None	list	Labels for this rule.
visibility	None	list	Visibility specification.
flags		str	Flags to apply to the test invocation - i.e. passed on the command line when it's run.
container	False	bool | dict	If True, the test will be run in a container (eg. Docker).
timeout		int	Maximum time this test is allowed to run for, in seconds.
flaky		int | bool	True to mark this test as flaky, or an integer for a number of reruns.
test_outputs	None	list	Extra test output files to generate from this test.
zip_safe	None	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	Set in config	str	The Python interpreter to use. Defaults to the config setting which is normally just 'python', but could be 'python3' or 'pypy' or whatever.

pip_library

pip_library(name, version, hashes=None, package_name=None, outs=None, test_only=False, env=None, deps=None, post_install_commands=None, install_subdirectory=False, repo=None, use_pypi=None, patch=None, visibility=None, zip_safe=True, licences=None)

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

Argument	Default	Type
name		str	Name of the build rule.
version		str	Specific version of the package to install.
hashes	None	list	List of acceptable hashes for this target.
package_name	None	str	Name of the pip package to install. Defaults to the same as 'name'.
outs	None	list	List of output files / directories. Defaults to [name].
test_only	False
env	None	dict	Environment variables to provide during pip install, as a dict (or similar).
deps	None	list	List of rules this library depends on.
post_install_commands	None	list	Commands run after pip install has completed.
install_subdirectory	False	bool	Forces the package to install into a subdirectory with this name.
repo	None	str	Allows specifying a custom repo to fetch from.
use_pypi	None	bool	If True, will check PyPI as well for packages.
patch	None	str	A patch file to be applied after install.
visibility	None	list	Visibility declaration for this rule.
zip_safe	True	bool	Flag to indicate whether a pex including this rule will be zip-safe.
licences	None	list	Licences this rule is subject to. Default attempts to detect from package metadata.

Sh rules

Rules to 'build' shell scripts.

Note that these do pretty much nothing beyond collecting the files. In future we might implement something more advanced (ala .sar files or whatever).

sh_library

sh_library(name, src, deps=None, visibility=None, link=True, labels=None)

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	Default	Type
name		str	Name of the rule
src		str	Source file for the rule
deps	None	list	Dependencies of this rule
visibility	None	list	Visibility declaration of the rule.
link	True	bool	Deprecated, has no effect.
labels	None	list	Labels to apply to this test.

sh_binary

sh_binary(name, main, deps=None, visibility=None, link=True, labels=None)

Generates a shell binary, essentially just the shell script itself.

Argument	Default	Type
name		str	Name of the rule
main		str	Main script file.
deps	None	list	Dependencies of this rule
visibility	None	list	Visibility declaration of the rule.
link	True	bool	If True, outputs will be linked in plz-out; if False they'll be copied.
labels	None	list	Labels to apply to this test.

sh_test

sh_test(name, src=None, args=None, labels=None, data=None, deps=None, visibility=None, flaky=False, test_outputs=None, timeout=0, container=False)

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

Argument	Default	Type
name		str	Name of the rule
src	None	str	Test script file.
args	None	list	Arguments that will be passed to this test when run. Deprecated in favour of flags.
flags		str	Flags to apply to the test invocation - i.e. passed on the command line when it's run.
labels	None	list	Labels to apply to this test.
data	None	list	Runtime data for the test.
deps	None	list	Dependencies of this rule
visibility	None	list	Visibility declaration of the rule.
flaky		int | bool	True to mark this as flaky and automatically rerun.
test_outputs	None	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.
container	False	bool | dict	True to run this test within a container (eg. Docker).