This is the reference for the complete set of builtin rules & functions.
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(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 | |
|---|---|---|---|
| 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(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(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(...)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.warning(message, [args...])Logs an arbitrary message at some given level. The available levels, from most quiet to most severe, are:
log.debuglog.infolog.noticelog.warninglog.errorlog.fatal-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(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(label)Converts the given build label to its full form.
For example:
//package:target -> //package:target//package -> //package:package:target -> //current_package:targetRules 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(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(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(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(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(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. |
c_embed_binary(name, src, deps, visibility, test_only)Build rule to embed an arbitrary binary file into a C library.
You can depend on the output of this as though it were a c_library rule.
There are five functions available to access the data once compiled, all of which are
prefixed with the file's basename:
filename_start(): returns a const char* pointing to the beginning of the data.
filename_end(): returns a const char* pointing to the end of the data.
filename_size(): returns the length of the data in bytes.
filename_start_nc(): returns a char* pointing to the beginning of the data.
This is a convenience wrapper using const_cast, you should not
mutate the contents of the returned pointer.
filename_end_nc(): returns a char* pointing to the end of the data.
Again, don't mutate the contents of the pointer.
You don't own the contents of any of these pointers so don't try to delete them :)
| Argument | Required | Type | |
|---|---|---|---|
| name | yes | str | Name of the rule. |
| src | yes | str | Source file to embed. |
| deps | list | Dependencies. | |
| visibility | list | Rule visibility. | |
| test_only | list | If True, is only available to test 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(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(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(name, srcs, asm_srcs, out, deps, visibility, test_only, static, filter_srcs)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. |
go_test(name, srcs, data, deps, worker, visibility, flags, container, sandbox, cgo, external, timeout, flaky, test_outputs, labels, size, static)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). |
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(name, get, repo, deps, exported_deps, visibility, patch, binary, test_only, install, revision, strip, hashes, extra_outs)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. |
Built-in rules to compile Java code.
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(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(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(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(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(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 |
maven_jars(name, id, ids, repository, exclude, hashes, combine, hash, deps, visibility, filename, deps_only, optional)Fetches a transitive set of dependencies from Maven.
| Argument | Required | Type | |
|---|---|---|---|
| name | yes | str | Name of the output rule. |
| id | str | Maven id of the artifact (e.g. org.junit:junit:4.1.0) | |
| ids | list | Maven ids of artifacts to fetch (e.g. org.junit:junit:4.1.0, io.grpc:grpc-all:1.4.0) | |
| repository | str or list | Maven repositories to fetch deps from. | |
| exclude | list | Dependencies to ignore when fetching this one. | |
| hashes | list | Map of Maven id -> rule hash for each rule produced. | |
| combine | bool | If True, we combine all downloaded .jar files into one uberjar. | |
| hash | str or list | Hash of final produced .jar. For brevity, implies combine=True. | |
| deps | list | Labels of dependencies, as usual. | |
| visibility | list | Visibility label. | |
| filename | str | Filename we attempt to download. Defaults to standard Maven name. | |
| deps_only | 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 | list | List of optional dependencies to fetch. By default we fetch none of them. |
Miscellaneous rules that aren't language-specific.
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)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 | Files containing secrets (credentials etc) used to build this rule. 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. 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. |
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. |
| 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. | |
| 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 | Secrets available to this rule while building. | |
| no_test_output | bool | If true the test is not expected to write any output results, it's only judged on its return value. | |
| 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(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(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(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(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(name, url, hashes, out, binary, visibility, licences, test_only, labels, deps, exported_deps, _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. | |
| _tag |
tarball(name, srcs, out, deps, subdir, gzip, xzip, 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. All files will be flattened into this directory. | |
| 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. | |
| test_only | bool | ||
| visibility | list | Visibility specification. | |
| labels | list | Labels associated with this rule. |
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(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(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. |
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(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(name, main, resources, out, deps, visibility, zip_safe, 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. |
| 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. | |
| 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. | |
| 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(name, srcs, data, resources, deps, worker, labels, size, flags, visibility, container, sandbox, timeout, flaky, test_outputs, zip_safe, interpreter)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. |
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(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. |
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(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(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 | 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(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 | 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 | list | 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(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. |
Rules for defining subrepos. See the docs for more information on subrepos in general.
http_archive(name, urls, strip_prefix, hashes, sha256, 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. | |
| visibility | list | Visibility declaration of the rule. |
new_http_archive(name, urls, build_file, build_file_content, strip_prefix, hashes, sha256, 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. | |
| visibility | list | Visibility declaration of the rule. |