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