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

glob

glob(include, exclude=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
include list List of paths to include. Each is globbed separately.
exclude 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, all=False)

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.
all False bool Returns labels from all dependencies, even past those marked as output_is_complete.

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.

add_licence

add_licence(target, licence)

Adds a new licence to a target. The assumption (as usual) is that if multiple are added, they are options, so any one can be accepted.

Argument Default Type
target str Label of the target to add the licence to.
licence str Name of the licence to add.

get_licences

get_licences(target)

Returns all the licences that are currently known to apply to a target.

Argument Default Type
target str Label of the target to get licences for.

package

package(...)

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.

decompose

decompose(label)

Decomposes a build label into the package and name parts.

Consider carefully when you should use this - command replacements may be more appropriate.
Most rules should be able to accept labels without having to know anything about their structure.

The input label can be given in either relative or absolute form. It will fail with an error if it's not a structurally valid label.

canonicalise

canonicalise(label)

Converts the given build label to its full form.

For example:

  • //package:target -> //package:target
  • //package -> //package:package
  • :target -> //current_package:target

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

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

Generate a C library target.

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

c_static_library / cc_static_library

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

Generates a C static library (.a).

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

Argument Required Type
name yes str Name of the rule
srcs list C or C++ source files to compile.
hdrs list Header files.
compiler_flags list Flags to pass to the compiler.
linker_flags list Flags to pass to the linker.
deps list Dependent rules.
visibility list Visibility declaration for this rule.
test_only bool If True, is only available to other test rules.
pkg_config_libs list Libraries to declare a dependency on using pkg-config
pkg_config_cflags list Libraries to declare a dependency on using `pkg-config --cflags`

c_shared_object / cc_shared_object

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

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

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

c_binary / cc_binary

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

Builds a binary from a collection of C rules.

Argument Required Type
name yes str Name of the rule
srcs list C source files to compile.
hdrs list Header files.
private_hdrs list Header files that are available only to this rule and not exported to dependent rules.
compiler_flags list Flags to pass to the compiler.
linker_flags list Flags to pass to the linker.
deps list Dependent rules.
visibility list Visibility declaration for this rule.
pkg_config_libs list Libraries to declare a dependency on using pkg-config
pkg_config_cflags list Libraries to declare a dependency on using `pkg-config --cflags`
test_only bool If True, this rule can only be used by tests.
static bool If True, the binary will be linked statically.

c_test / cc_test

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

Defines a C test target.

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

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

Go rules

Rules to build Go code.

Go has a strong built-in concept of packages so while it's not 100% required to strictly keep to 1 package per dir as in classic Go, it's still probably a good idea to match Please rules to Go packages.

go_library

go_library(name, srcs, asm_srcs, hdrs, out, deps, visibility, test_only, complete, _needs_transitive_deps, _all_srcs, cover, filter_srcs, _link_private, _link_extra)

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

Argument Required Type
name yes str Name of the rule.
srcs yes list Go source files to compile.
asm_srcs list Source files to assemble with `go tool assemble`.
hdrs list Header files needed for assembly. Has no effect if asm_srcs is not given.
out str Name of the output library to compile (defaults to name suffixed with .a)
deps list Dependencies
visibility list Visibility specification
test_only bool If True, is only visible to test rules.
complete bool Indicates whether the library is complete or not (ie. buildable with `go tool build -complete`). In nearly all cases this is True (the main exception being for cgo).
_needs_transitive_deps
_all_srcs
cover bool Indicates whether this library should be considered for coverage annotations. Libraries are only annotated when using `plz cover` (or `plz build -c cover`), but if this is false they never will be. Can be useful for e.g. third-party code that you never want to be instrumented.
filter_srcs bool If True, filters source files through Go's standard build constraints.
_link_private bool
_link_extra bool

cgo_library

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

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

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

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

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

go_binary

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

Compiles a Go binary.

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

go_test

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

Defines a Go test rule.

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

cgo_test

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

Defines a Go test rule over a cgo_library.

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

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

go_get

go_get(name, get, repo, deps, exported_deps, visibility, patch, binary, test_only, install, revision, strip, hashes, extra_outs, licences)

Defines a dependency on a third-party Go library.

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

Note also that while a single go_get is sufficient to compile all parts of a library,
one may also want separate ones for a binary. Since two rules can't both output the same
source files (and you only want to download them once anyway) you should handle that by
marking the non-binary rule as a dependency of the binary one - if you don't there may
be warnings issued about conflicting output files.

Argument Required Type
name yes str Name of the rule
get yes str or list Target to get (eg. "github.com/gorilla/mux"). Can also be a list of multiple in which case they are fetched separately and compiled together, which can be useful for avoiding issues with circular dependencies.
repo str Location of a Git repository to fetch from.
deps list Dependencies
exported_deps list Dependencies to make available to anything using this rule.
visibility list Visibility specification
patch str Patch file to apply
binary bool True if the output of the rule is a binary.
test_only bool If true this rule will only be visible to tests.
install list Allows specifying the exact list of packages to install. If this is not passed, the package passed to 'get' is installed. If you pass this for subpackages, you will need to explicitly add an empty string to the list if you want to install the root package from this repo.
revision str or list Git hash to check out before building. Only works for git at present, not for other version control systems.
strip list List of paths to strip from the installed target.
hashes list List of hashes to verify the downloaded sources against.
extra_outs list List of additional output files after the compile.
licences list Licences this rule is subject to.

Java rules

Built-in rules to compile Java code.

java_library

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

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

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

java_module

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

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

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

java_binary

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

Compiles a .jar from a set of Java libraries.

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

java_runtime_image

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

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

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

java_test

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

Defines a Java test.

Argument Required Type
name yes str Name of the rule.
srcs yes list Java files containing the tests.
resources list Resources to include in the .jar file
data list Runtime data files for this rule.
deps list Dependencies of this rule.
worker str Reference to worker script, A persistent worker process that is used to set up the test.
labels list Labels to attach to this test.
visibility list Visibility declaration of this rule.
flags str Flags to pass to the test invocation.
container bool or dict True to run this test within a container (eg. Docker).
sandbox bool Sandbox the test on Linux to restrict access to namespaces such as network.
timeout int Maximum length of time, in seconds, to allow this test to run for.
flaky bool or int True to mark this as flaky and automatically rerun.
test_outputs list Extra test output files to generate from this test.
size str Test size (enormous, large, medium or small).
test_package str Java package to scan for test classes to run.
jvm_args str Arguments to pass to the JVM in the run script.

maven_jar

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

Fetches a single Java dependency from Maven.

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

Misc rules

Miscellaneous rules that aren't language-specific.

genrule

genrule(name, cmd, srcs, out, outs, deps, labels, visibility, building_description, hashes, timeout, binary, sandbox, needs_transitive_deps, output_is_complete, test_only, secrets, requires, provides, pre_build, post_build, tools, pass_env)

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

Argument Required Type
name yes str Name of the rule
cmd yes str or list or dict Command to run. If given as a string, it's a single command that's used always (the most common case). If given as a list, it's a sequence of commands run one after another if the preceding command is successful (i.e. it's equivalent to ' && '.join(cmd)). If given as a dict, the keys correspond to the build config to run and the values are the command to run in that config. The typical use case here is 'opt' vs. 'dbg' but arbitrary names can be given and specified with `plz build -c name`. See https://please.build/build_rules.html for more information about the sequence replacements and environment variables that are made available to this rule.
srcs list or dict Sources of this rule. Can be a list of files or rules, or a dict of names to lists. In the latter case they can be accessed separately which is useful to be able to refer to them distinctly in the command.
out str A single output of this rule, as a string. Discouraged in favour of 'outs'.
outs list or dict Outputs of this rule. All are files relative to this package. If given as a dict, it declares a series of named outputs which work similarly to named srcs; they have separate environment variables and can be accessed directly by other rules.
deps list Dependencies of this rule.
labels list Labels to apply to this rule.
visibility list Visibility declaration of this rule
building_description str Description to display to the user while the rule is building.
hashes 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 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.
sandbox bool If True, the build action is sandboxed within a separate network and process namespace. Only works on Linux and requires plz_sandbox to be installed separately. If False, it opts the target out of sandboxing when that is turned on.
needs_transitive_deps 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 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 bool If True it can only be used by test rules.
secrets list or dict Files containing secrets (credentials etc) used to build this rule. Can be a list of secrets, or a dict to lists. In the latter case they can be accessed separately which is useful to be able to refer to them distinctly in the command. These are all absolute paths (beginning with / or ~) and are not copied to the build directory. They can be accessed through the environment variable $SECRETS (named secrets can be addressed individually as $SECRETS_<NAME_OF_SECRET>). They don't contribute to the key used to retrieve outputs from the cache; this means it's possible for one machine to build a target with the secret and then share the output with others. That also implies that secrets are things like credentials or signing keys and shouldn't be copied directly to outputs, otherwise they might become more widely known.
requires 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 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 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 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 list or dict 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). If tools is given as a dict then the keys of the dict name the various tools and they can be accessed with $TOOLS_KEY.
pass_env list List of environment variables to be passed from outside. Any changes to them will
be recorded in this target's hash and will hence force it to rebuild.

gentest

gentest(name, test_cmd, labels, cmd, srcs, outs, deps, tools, data, visibility, timeout, needs_transitive_deps, flaky, secrets, no_test_output, test_outputs, output_is_complete, requires, container, sandbox, size)

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 Required Type
name yes str Name of the rule
test_cmd yes str or dict Command to run for the test. It works similarly to the cmd attribute; see genrule for a more detailed discussion of its properties. The command should exit with 0 when successful, and nonzero otherwise. Normally this will correspond to the test results that are output, unless no_test_output is True in which case this is the only thing that determines success / failure.
labels list Labels to apply to this test.
cmd str or dict Command to run for the test. It works similarly to the cmd attribute; see genrule for a more detailed discussion of its properties. The command should exit with 0 when successful, and nonzero otherwise. Normally this will correspond to the test results that are output, unless no_test_output is True in which case this is the only thing that determines success / failure.
srcs list or dict Source files for this rule.
outs list Output files of this rule.
deps list Dependencies of this rule.
tools list or dict 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 list Runtime data files for the test.
visibility 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 bool True if building the rule requires all transitive dependencies to be made available.
flaky bool or int If true the test will be marked as flaky and automatically retried.
secrets list or dict Secrets available to this rule while building.
no_test_output bool If true the test is not expected to write any output results, it will pass if the command exits with 0 and fail otherwise.
test_outputs list List of optional additional test outputs.
output_is_complete bool If this is true then the rule blocks downwards searches of transitive dependencies by other rules.
requires list Kinds of output from other rules that this one requires.
container bool or dict If true the test is run in a container (eg. Docker).
sandbox bool If True, the test is run within a sandbox that restricts some cgroups including networking, process, IPC, etc. Only has an effect on Linux. If this is on by default then tests can opt out by setting this to False.
size str Test size (enormous, large, medium or small).

export_file

export_file(name, src, visibility, binary, test_only)

Essentially a single-file alias for filegroup.

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

filegroup

filegroup(name, tag, srcs, deps, exported_deps, visibility, labels, binary, output_is_complete, requires, provides, hashes, test_only)

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 Required Type
name yes str Name of the rule
tag str Tag applied to name; generates a private rule, for example name='a',tag='b' gives _a#b. Typically used for "private" rules.
srcs list Source files for the rule.
deps list Dependencies of the rule.
exported_deps list Dependencies that will become visible to any rules that depend on this rule.
visibility list Visibility declaration
labels list Labels to apply to this rule
binary bool True to mark the rule outputs as binary
output_is_complete bool If this is true then the rule blocks downwards searches of transitive dependencies by other rules.
requires list Kinds of output from other rules that this one requires.
provides dict Kinds of output that this provides for other rules (see genrule() for a more in-depth discussion of this).
hashes list List of acceptable output hashes for this rule.
test_only bool If true the exported file can only be used by test targets.

hash_filegroup

hash_filegroup(name, srcs, deps, exported_deps, visibility, labels, test_only, requires)

Copies a set of files to output names which are uniquely hashed based on their contents.

For example, srcs = ["test.txt"] might output "test-b250cnf30f3h.txt".

Argument Required Type
name yes str Name of the rule.
srcs list Source files for the rule.
deps list Dependencies of the rule.
exported_deps list Dependencies that will become visible to any rules that depend on this rule.
visibility list Visibility declaration
labels list Labels to apply to this rule
test_only bool If true the exported file can only be used by test targets.
requires list Kinds of output from other rules that this one requires.

system_library

system_library(name, srcs, deps, hashes, visibility, test_only)

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 Required Type
name yes str Name of the rule.
srcs yes list System-level sources. Should all be absolute paths.
deps list Dependencies of the rule.
hashes list List of hashes; the output must match at least one of these. This is not required but could be used to assert that the system lib is of some known version.
visibility list Visibility declaration of the rule.
test_only bool If true the rule is only visible to test targets.

remote_file

remote_file(name, url, hashes, out, binary, visibility, licences, test_only, labels, deps, exported_deps, extract, strip_prefix, _tag)

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

Argument Required Type
name yes str Name of the rule
url yes str or list URL or URLs to fetch. If multiple are passed then they will be tried in sequence until one succeeds.
hashes list List of hashes; the output must match at least one of these.
out str Output name of the file. Chosen automatically if not given.
binary bool True to mark the output as binary and runnable.
visibility list Visibility declaration of the rule.
licences list List of licences that apply to this rule.
test_only bool If true the rule is only visible to test targets.
labels list Labels to apply to this rule.
deps list List of extra dependencies for this rule.
exported_deps list Dependencies that will become visible to any rules that depend on this rule.
extract bool Extracts the contents of the downloaded file. It must be either zip or tar format.
strip_prefix str When extracting, strip this prefix from the extracted files.
_tag str

tarball

tarball(name, srcs, out, deps, subdir, gzip, xzip, flatten, strip_prefix, test_only, visibility, labels)

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

File mode and ownership are preserved. However, the atime and mtime of all
files will be set to 1 Jan 2000 00:00:00.

Argument Required Type
name yes str Rule name
srcs yes list Source files to include in the tarball
out str Name of output tarball (defaults to `name`.tar.gz, but see below re compression)
deps list Dependencies
subdir str Subdirectory to create in.
gzip bool If True, the output will be gzipped. If False, it will just be a tarball.
xzip bool If True, the output will be xzipped. Overrides gzip if passed.
flatten bool If True, the output will be flattened into the subdirectory.
strip_prefix str If flatten is False, strips this prefix from internal directory structure.
test_only bool
visibility list Visibility specification.
labels list Labels associated with this rule.

git_branch

git_branch(short:bool=True)

Calls git symbolic-ref -q HEAD and returns the corresponding git branch. If short is false, show the full symbolic ref for a branch.

Argument Default Type
short True bool Uses the shortened symbolic ref for a branch.

git_commit

git_commit()

Calls git rev-parse HEAD and returns the corresponding git commit SHA. To return a shortened commit use git_commit()[0:8].

git_show

git_show(format:str)

Calls git show -s --format={format} and returns the result. format is limited to a subset of values accepted by git show.

Argument Default Type
format str String format passed to git show.

Supported format verbs are limited to:

  • %H commit hash
  • %T tree hash
  • %P parent hashes
  • %an author name
  • %ae author email
  • %at author date, UNIX timestamp
  • %cn committer name
  • %ce committer email
  • %ct committer date, UNIX timestamp
  • %D ref names
  • %e encoding
  • %s subject of commit message
  • %f sanitized subject line, suitable for a filename
  • %b body of commit message
  • %B raw body (unwrapped subject and body)
  • %N commit notes
  • %GG raw verification message from GPG for a signed commit
  • %G? show "G" for a good (valid) signature, "B" for a bad signature, "U" for a good signature with unknown validity, "X" for a good signature that has expired, "Y" for a good signature made by an expired key, "R" for a good signature made by a revoked key, "E" if the signature cannot be checked (e.g. missing key) and "N" for no signature
  • %GS show the name of the signer for a signed commit
  • %GK show the key used to sign a signed commit
  • %n newline
  • %% a raw %

git_state

git_state(clean_label:str="clean", dirty_label:str="dirty")

Calls git status --porcelain and returns the corresponding string. If the repository is clean, the string set in clean_label is returned. If the repository is dirty, the string set in dirty_label is returned.

Argument Default Type
clean_label clean str String returned if the repository is clean.
dirty_label dirty str String returned if the repository is dirty.

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, deps, visibility, labels, languages, test_only, root_dir, protoc_flags)

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

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

grpc_library

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

Defines a rule for a grpc library.

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

proto_language

proto_language(language, extensions, func, use_file_names, protoc_flags, tools, deps, pre_build, proto_language)

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

Argument Required Type
language yes str Name of the language (as we would name it).
extensions yes list or dict File extensions that will get generated.
func yes function Function defining how to build the rule. It will receive the following arguments:
use_file_names bool True if the output file names are normally predictable. This is the case for most languages but not e.g. Java where they depend on the declarations in the proto file. If False we'll attempt to detect them.
protoc_flags list Additional flags for the protoc invocation for this rule.
tools list Additional tools to apply to this rule.
deps list Suggested dependencies.
pre_build function Definition of pre-build function to apply to this language.
proto_language str Name of the language (as protoc would name it). Defaults to the same as language.

Python rules

Rules to build Python code.

The output artifacts for Python rules are .zip files similar to .pex files (and are suffixed as such).

This combines all the in-repo dependencies into a single file that can be deployed and run on any system that has a suitable Python interpreter. Please optimises this process to improve incrementality and includes some hooks to make running from a zipfile as transparent as possible; nonetheless certain file-based operations may not work since there is not a real file system available. If necessary various Python rules can be annotated with zip_safe to control this; if a binary is zip-unsafe it will extract itself before running.

python_library

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

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

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

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

python_binary

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

Generates a Python binary target.

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

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

python_test

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

Generates a Python test target.

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

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

pip_library

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

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

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

python_wheel

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

Downloads a Python wheel and extracts it.

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

Argument Required Type
name yes str Name of the rule. Also doubles as the name of the package if package_name is not set.
version yes str Version of the package to install.
hashes list List of hashes to verify the package against.
package_name str If given, overrides `name` for the name of the package to look for.
outs list List of output files. Defaults to a directory named the same as `name`.
post_install_commands list Commands to run after 'install'.
patch str or list Patch file to apply after install to fix any upstream code that has done bad things.
licences list Licences that this rule is subject to.
test_only bool If True, this library can only be used by tests.
repo str Repository to download wheels from.
zip_safe bool Flag to indicate whether a pex including this rule will be zip-safe.
visibility list Visibility declaration.
deps list Dependencies of this rule.
name_scheme str The templatized wheel naming scheme (available template variables are `url_base`, `package_name`, and `version`).
strip list Files to strip after install. Note that these are done at any level.

Shell 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, visibility, labels)

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

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

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

sh_binary

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

Generates a shell script binary.

It assumes that unzip is in your path.

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

Argument Required Type
name yes str Name of the rule
main yes str or list The script to execute after all files have been uncompressed
deps list Dependencies of this rule
visibility list Visibility declaration of the rule.
labels list List of labels.

sh_cmd

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

Generates a runnable shell script from a command.

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

Argument Required Type
name yes str Name of the rule.
cmd yes str or dict or list Command to write into the output script file.
srcs list or dict Source files. Can be consumed by the generated command (but are not written into the output in any other way).
out str Name of the output file to create. Defaults to name + .sh.
shell str Shell to invoke in, by default /bin/sh.
labels list Labels to apply to this rule.
deps list Any dependencies for this rule.
visibility list Visibility declaration of the rule.
test_only bool If True, this rule can only be depended on by tests.

sh_test

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

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

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

Subrepo rules

Rules for defining subrepos. See the docs for more information on subrepos in general.

http_archive

http_archive(name, urls, strip_prefix, hashes, sha256, config, bazel_compat, visibility)

Fetches a remote file over HTTP and expands its contents.

The archive should be either a zipfile or a tarball. Which one to use will be autodetected
based on the file extension in the URL given.

This is still experimental and known not to work in many cases.

Argument Required Type
name yes str Name of the rule.
urls yes list List of URLs to fetch from. These are assumed to be mirrors and will be tried in sequence.
strip_prefix str Prefix to strip from the expanded archive.
hashes str or list List of hashes to verify the rule with. sha256: Used for Bazel compat but currently has no effect.
sha256 str Used for Bazel compat but currently has no effect.
config str Configuration file to apply to this subrepo.
bazel_compat bool Shorthand to turn on Bazel compatibility. This is equivalent to specifying a config file with `compatibility = true` in the `[bazel]` section.
visibility list Deprecated, has no effect.

new_http_archive

new_http_archive(name, urls, build_file, build_file_content, strip_prefix, hashes, sha256, config, bazel_compat, visibility)

Fetches a remote file over HTTP and expands its contents, combined with a BUILD file.

The archive should be either a zipfile or a tarball. Which one to use will be autodetected
based on the file extension in the URL given.

The given build file (via build_file or build_file_contents) will replace any existing file
and will therefore be used to build the contents of the subrepo.

This is still experimental and known not to work in many cases.

Argument Required Type
name yes str Name of the rule.
urls yes list List of URLs to fetch from. These are assumed to be mirrors and will be tried in sequence.
build_file str The file to use as a BUILD file for this subrepository.
build_file_content str Text content to use for the BUILD file for the subrepository. We suggest using build_file instead, but this is provided for Bazel compatibility.
strip_prefix str Prefix to strip from the expanded archive.
hashes str or list List of hashes to verify the rule with. sha256: Used for Bazel compat but currently has no effect.
sha256 str Used for Bazel compat but currently has no effect.
config str Configuration file to apply to this subrepo.
bazel_compat bool Shorthand to turn on Bazel compatibility. This is equivalent to specifying a config file with `compatibility = true` in the `[bazel]` section.
visibility list Deprecated, has no effect.

github_repo

github_repo(name, repo, revision, build_file, hashes, strip_prefix, config, bazel_compat)

Defines a new subrepo corresponding to a Github project.

This is a convenience alias to the more general new_http_archive. It knows how to
construct Github URLs appropriately which allows a more concise description.

Argument Required Type
name yes str Name of the rule.
repo yes str Github repo to fetch from (e.g. "thought-machine/please").
revision yes str Revision to download.
build_file str The file to use as a BUILD file for this subrepository.
hashes str or list List of hashes to verify the rule with.
strip_prefix str Prefix to strip from the contents of the zip. Is usually autodetected for you.
config str Configuration file to apply to this subrepo.
bazel_compat bool Shorthand to turn on Bazel compatibility. This is equivalent to
specifying a config file with `compatibility = true` in the `[bazel]`
section.