The Lexicon of Please

Strings

The following are available as member functions of strings:

• join(seq) - joins the elements of seq together with this string as a separator.
• split(sep) - splits this string at each occurrence of the given separator.
• replace(old, new) - returns a copy of this string with all instances of old replaced with new.
• partition(sep) - breaks this string around the first occurrence of sep and returns a 3-tuple of (before, sep, after).
• rpartition(sep) - breaks this string around the last occurrence of sep and returns a 3-tuple of (before, sep, after).
• startswith(prefix) - returns true if this string begins with prefix
• endswith(suffix) - returns true if this string ends with suffix
• format(arg1=val1, arg2=val2, ...) - Replaces named parameters in the string.
• lstrip(cutset) - strips all characters in cutset from the beginning of this string.
• rstrip(cutset) - strips all characters in cutset from the end of this string.
• strip(cutset) - strips all characters in cutset from the beginning & end of this string.
• removeprefix(prefix) - strips the exact string prefix from the beginning of this string.
• removesuffix(suffix) - strips the exact string suffix from the end of this string.
• find(needle) - returns the index of the first occurrence of needle in this string.
• rfind(needle) - returns the index of the last occurrence of needle in this string.
• count(needle) - returns the number of times needle occurs in this string.
• upper() - returns a copy of this string converted to uppercase.
• lower() - returns a copy of this string converted to lowercase.

Dictionaries

The following are available as member functions of dictionaries:

• get(key[, default]) - returns the item with the given key, or the default (None if that is not given).
• setdefault(key[, default]) - If the given key is in the dict, return its value, otherwise insert it with the given value (None if that is not given).
• keys() - returns an iterable sequence of the keys of this dictionary, in a consistent order.
• values() - returns an iterable sequence of the values of this dictionary, in a consistent order.
• items() - returns an iterable sequence of pairs of the keys and values of this dictionary, in a consistent order.
• copy() - deprecated, use a comprehension if needed. Returns a shallow copy of this dictionary.

log

Messages can be logged to Please's usual logging mechanism. These may or may not be displayed depending on the -v flag; by default only warning and above are visible.

• log.debug(msg[, args...]) - the lowest level of messages, output at this level is very verbose.
• log.info(msg[, args...]) - Informational messages, typically this is the highest level per-target information is logged at.
• log.notice(msg[, args...]) - Messages of general interest during the build; it is rare for this to be appropriate from a BUILD file.
• log.warning(msg[, args...]) - A warning message that something seems wrong, but it may be recoverable.
• log.error(msg[, args...]) - A message indicating that something has gone wrong and it will not be recoverable. This is usually followed shortly by some kind of failure.
• log.fatal(msg[, args...]) - Indicates that something has gone catastrophically wrong, and causes the process to exit immediately and unsuccessfully. Usually you are better off using assert or fail() to indicate failure, since plz can handle those and annotate with additional output.

subinclude

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

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

Note that the expansion patterns accepted are * to match an arbitrary number of non-separator characters (i.e. not /), ** to match any number of complete path components, ? to match a single character, and [class] to match a class of character e.g. [a-z], [^0-9], or [abc].
These are often referred to as "Ant-style" patterns since Ant introduced them.

Glob exclude patterns can be evaluated relative to the matched file or the package root. If the exclude pattern does not contain a path separator, it is considered relative and will be evaluated against the file name of the match only, otherwise it will be evaluated from the directory of the build file. This means that glob(["**/*.go"], exclude = ["*_test.go"]) will exclude all files ending in "test.go".

Hidden files (those starting with a .) are not matched by any patterns unless you pass hidden=True.

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.

get_labels

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.

has_label

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

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

get_licences

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

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

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

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

Converts the given build label to its full form.

For example:

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

tag

Tags a build label name with a given tag. This can be useful to keep following the intermediate build target naming convention when a build definition doesn't expose the tag parameter.

For example:

• tag("name", "foo") -> "_name#foo"
• tag("_name#foo", "bar") -> "_name#foo_bar"

fail

Causes an immediate failure in parsing of the current build file.

Use this where you might raise in Python.

c_library / cc_library

Generate a C library target.

c_static_library / cc_static_library

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.

c_shared_object / cc_shared_object

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

c_binary / cc_binary

Builds a binary from a collection of C rules.

c_test / cc_test

Defines a C test target.

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

go_toolchain

Downloads Go and exposes :<name>|go and :<name>|gofmt as entry points. To use this rule add the
following to your .plzconfig:

[go]
GoTool = //.../<name>|go

go_library

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

cgo_library

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.

go_binary

Compiles a Go binary.

go_test

Defines a Go test rule.

go_benchmark

Defines a Go test suite that will be run as a benchmark.

cgo_test

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.

go_test_main

Outputs the main file for a Go test.

This essentially does the test discovery and templates out the entry point from it. Note that
it only generates the main; you will likely need to arrange for compilation of the inputs via
a separate go_library rule.

go_module

Defines a dependency on a third-party Go module.

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

This rule is different to go_get() in that it is go module aware. It handles vanity imports and major versions
correctly so is the recommended approach.

go_mod_download

Downloads a third-party Go module using `go mod download`

This rule is typically used in conjunction with go_module() to resolve cyclic dependencies between modules. This rule
can be passed to go_module() via the download param which enables multiple go_module() rules to compile parts of the
whole module. It can also be useful to download from a fork of a module where the import path doesn't match the
repo path.

go_get

Deprecated: use go_module() instead. Will be removed in v17.

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.

java_library

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

java_module

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

java_binary

Compiles a .jar from a set of Java libraries.

java_runtime_image

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

java_test

Defines a Java test.

maven_jar

Fetches a single Java dependency from Maven.

java_toolchain

This is an experimental feature and is subject to breaking changes in minor releases.

Defines a toolchain that downloads a JDK that can be used with java languages rules. This can be configured in your
.plzconfig via the config option java.toolchain.

This rule is aliased please_java_toolchain as well. When Bazel compatibility is enabled, this alias must be used
instead.

genrule

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

gentest

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.

export_file

Essentially a single-file alias for filegroup.

filegroup

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.

hash_filegroup

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

system_library

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.

remote_file

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

tarball

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.

text_file

Defines a rule to convert a string in the build language into a text file.

git_branch

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

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

Calls git show -s --format={format} and returns the result. format is limited to a subset of values accepted by 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

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.

proto_library

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

grpc_library

Defines a rule for a grpc library.

proto_language

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

python_library

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

python_binary

Generates a Python binary target.

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

This target can be debugged via:
plz debug [-o python.debugger:[pdb|debugpy]] [--port] //:target

python_test

Generates a Python test target.

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

This target can be debugged via:
plz debug [-o python.debugger:[pdb|debugpy]] [--port] //:target

pip_library

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

python_wheel

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

sh_library

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.

sh_binary

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.

sh_cmd

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

sh_test

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

http_archive

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.

new_http_archive

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.

github_repo

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.

arch

Defines an architecture subrepo.

This is a convenience alias to the more general subrepo rule. It allows for a user-defined
subrepo for cross-built rules targeting a specific architecture. This lets users define
architectures that won't conflict with the subrepos implicitly instantiated by plz.