The Lexicon of Please

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

Python style builtins

The build language largely resembles Python. As such, the following Python-inspired functions are available as builtins:

  • len(x) - returns the length of x.
  • chr(i) - returns a string containing the character whose Unicode code point is the integer i.
  • ord(c) - returns an integer representing the Unicode code point of the (single) character in the string c.
  • enumerate(seq) - returns a list of pairs of the index and object for each item in seq.
  • zip(x, y, ...) - returns a list in which each element has one item from each argument.
  • isinstance(x, type) - returns True if x is of the given type.
  • range([start, ]stop[, step]) - returns a list of integers up to stop (or from start to stop).
  • any(seq) - returns true if any of the items in seq are considered true.
  • all(seq) - returns true if all of the items in seq are considered true.
  • min(seq[,key]) - returns the least item in seq. key is a function that is applied to each item before comparison.
  • max(seq[,key]) - returns the greatest item in seq. key is a function that is applied to each item before comparison.
  • sorted(seq) - returns a copy of the given list with the contents sorted.
  • reversed(seq) - returns a copy of the given list with the items in reverse order.
  • filter(filter, seq) - returns a copy of the given list with the items filtered using function.
  • map(mapper, seq) - returns a copy of the given list with the items transformed using function.
  • reduce(reducer, seq, initializer=None) - returns a single value by applying function cumulatively to the list items, from left to right.
  • package_name() - returns the package being currently parsed.
  • subrepo_name() - returns the subrepo of the package being currently parsed or the empty string if this is not a subrepo.
  • join_path(x, ...) - joins the given path elements using the OS separator. It will intelligently handle repeated or missing separators.
  • split_path(path) - splits the given path into the directory and filename.
  • splitext(filename) - splits the given filename into base name and extension at the final dot.
  • basename(path) - returns the basename of a file.
  • dirname(path) - returns the directory name of a file.
  • breakpoint() - breaks into an interactive debugger allowing inspection of the current scope. To enable breakpoints, pass the --debug flag.
  • json(x) - returns a JSON-formatted representation of a plz value.
  • is_semver(s) - returns true if s is a semantic version (either with or without a leading "v"), or false if not.
  • semver_check(version, constraint) - checks if a semantic version meets a constraint. Supported version and constraint formats are listed on this site.

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.

Please builtins

In addition to the python builtins, Please also has a rich set of its own functions.

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

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

Argument Default Type
include list List of paths to include. Each is globbed separately.
exclude None list List of glob patterns to exclude from anything matched by include.
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 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

tag

tag(name, 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

fail(message)

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

Use this where you might raise in Python.

Misc rules

Miscellaneous rules that aren't language-specific.

genrule

genrule(name, cmd, srcs, out, outs, deps, exported_deps, labels, visibility, building_description, data, hashes, timeout, binary, sandbox, needs_transitive_deps, output_is_complete, test_only, secrets, requires, provides, pre_build, post_build, tools, pass_env, local, output_dirs, exit_on_error, entry_points, env, optional_outs)

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.
exported_deps list Dependencies that will become visible to any rules that depend on 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.
data list or dict Runtime data for this rule. Can be a list of files or rules, or a dict of names to lists, with similar semantics to those of srcs.
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 str or 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.
local bool Forces the rule to be built locally; when remote execution is enabled it will not be sent remotely but executed on the local machine.
output_dirs list Directories to add to the output of the rule. Files inside these directories will be added to the root of the rule e.g. if you have an outdir foo, foo/bar.txt will be added as if bar.txt was in the root of the build directory.
exit_on_error bool If true, the executed command will fail immediately on any error (i.e. it is executed in a shell with -e).
entry_points dict A subset of outputs of this rule that can be used as entry points by other rules. Entry points can be referenced though the `//path/to:rule|entry-point` syntax.
env dict 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.
optional_outs list Any additional outputs this rule might produce. These are are not made available to rules
that depend on this rule. They are only copied to plz-out. These can be useful for symbols,
source maps and other metadata like that.

gentest

gentest(name, test_cmd, labels, cmd, srcs, outs, deps, exported_deps, tools, test_tools, data, visibility, timeout, needs_transitive_deps, flaky, secrets, no_test_output, test_outputs, output_is_complete, requires, sandbox, size, local, pass_env, env, exit_on_error, no_test_coverage)

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 list 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 list 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.
exported_deps list Dependencies that will become visible to any rules that depend on this rule.
tools str or list or dict Tools used to build this rule; similar to srcs but are not copied to the temporary build directory.
test_tools str or list or dict Like tools but available to test_cmd instead.
data list or dict 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. Implies no_test_coverage as well.
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.
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).
local bool Forces the rule to be built locally; when remote execution is enabled it will not be sent remotely but executed on the local machine.
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.
env dict 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.
exit_on_error bool If true, the executed command will fail immediately on any error (i.e. it is
executed in a shell with -e).
no_test_coverage bool If true, the test is not expected to produce any coverage output under `plz cover`. By default this is false, but coverage is optional, so Please will not fail if no coverage file is output; this is mostly relevant for remote execution where not producing an expected output will inhibit caching.

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, exported_files, entry_points, username, password_file, headers, secret_headers, pass_env)

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.
exported_files A list of files to export from the archive when extracting.
entry_points dict
username str Username for accessing a private file or repo.
password_file str A file on disk that contains a password or access token.
headers dict Headers to pass to curl.
secret_headers dict Headers contained in files to pass to curl.
pass_env list Any environment variables referenced by headers that should be passed in from the host.

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.

text_file

text_file(name, content, strip, hashes, data, out, binary, visibility, licences, test_only, labels, deps, exported_deps, entry_points)

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

Argument Required Type
name yes str Name of the rule
content yes str The text content of the file.
strip bool True to strip the input.
hashes list List of hashes; the output must match at least one of these.
data list or dict List of runtime data for this rule.
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 or dict List of dependencies for this rule.
exported_deps list Dependencies that will become visible to any rules that depend on this rule.
entry_points dict

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.

Subrepo rules

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

plugin_repo

plugin_repo(name, revision, plugin, owner, hashes)

Defines a please plugin to use from the configured plugin repositories. See
https://please.build/config.html#please.pluginrepositories for more information.

Argument Required Type
name yes str Name of the rule
revision yes str The revision or version of the plugin pass to the template URLS.
plugin str The name of the plugin. Defaults to the name of this rule.
owner str The owner of the plugin to be passed to the template URLS.
hashes list A list of valid hashes for the downloaded archive file.

http_archive

http_archive(name, urls, strip_prefix, patches, labels, hashes, 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.
patches list A list of patches to apply to the expanded archive (with `patch -p1`), in the order in which they should be applied.
labels list Labels to apply to this rule.
hashes str or list List of hashes to verify the rule with.
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, patches, strip_build, plugin, labels, hashes, username, password_file, headers, secret_headers, config, bazel_compat, visibility, pass_env)

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.
patches list A list of patches to apply to the expanded archive (with `patch -p1`), in the order in which they should be applied.
strip_build bool True to strip any BUILD files from the archive after download.
plugin bool
labels list Labels to apply to this rule.
hashes str or list List of hashes to verify the rule with.
username str Username for accessing a private file or repo.
password_file str A file on disk that contains a password or access token.
headers dict Headers to pass to curl.
secret_headers dict Headers contained in files to pass to curl.
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.
pass_env list Any environment variables referenced by headers that should be passed in from the host.

github_repo

github_repo(name, repo, revision, build_file, labels, hashes, strip_prefix, patches, strip_build, config, access_token, 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. This can be either a release version, commit or branch.
build_file str The file to use as a BUILD file for this subrepository.
labels list Labels to apply to this rule.
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.
patches list A list of patches to apply to the repository's contents (with `patch -p1`), in the order in which they should be applied.
strip_build bool True to strip any BUILD files from the archive after download.
config str Configuration file to apply to this subrepo.
access_token str An environment variable containing a github personal access token. This can be used to access private repos.
bazel_compat bool Shorthand to turn on Bazel compatibility. This is equivalent to
specifying a config file with `compatibility = true` in the `[bazel]`
section.

gitlab_repo

gitlab_repo(name, repo, revision, instance, build_file, labels, hashes, strip_prefix, patches, strip_build, config, bazel_compat)

Defines a new subrepo corresponding to a GitLab project.

Like github_repo, this is a convenience alias to new_http_archive.

Argument Required Type
name yes str Name of the rule.
repo yes str GitLab repository to fetch from (e.g. "gitlab-org/gitlab-foss").
revision yes str Revision to download.
instance str The root URL of the GitLab instance to fetch from (e.g. "gitlab.gnome.org" for the GNOME GitLab instance at https://gitlab.gnome.org). Defaults to "gitlab.com", the official public GitLab instance.
build_file str The file to use as a BUILD file for this subrepository.
labels list Labels to apply to this rule.
hashes str or list List of hashes to verify the rule with.
strip_prefix str Prefix to strip from the contents of the zip. This is usually automatically detected.
patches list A list of patches to apply to the repository's contents (with `patch -p1`), in the order in which they should be applied.
strip_build bool True to strip any BUILD files from the archive after download.
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.

arch

arch(name, os, 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.

Argument Required Type
name yes str Name of the rule.
os yes str Target operating system (e.g. "darwin")..
arch yes str Target architecture (e.g. "amd64").