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:

Strings

The following are available as member functions of strings:

Dictionaries

The following are available as member functions of dictionaries:

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.

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:

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:

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:

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.

{{ template "lexicon_entry.html" .Named "genrule" }} {{ template "lexicon_entry.html" .Named "gentest" }} {{ template "lexicon_entry.html" .Named "export_file" }} {{ template "lexicon_entry.html" .Named "filegroup" }} {{ template "lexicon_entry.html" .Named "hash_filegroup" }} {{ template "lexicon_entry.html" .Named "system_library" }} {{ template "lexicon_entry.html" .Named "remote_file" }} {{ template "lexicon_entry.html" .Named "tarball" }} {{ template "lexicon_entry.html" .Named "text_file" }}

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:

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.

{{ template "lexicon_entry.html" .Named "plugin_repo" }} {{ template "lexicon_entry.html" .Named "http_archive" }} {{ template "lexicon_entry.html" .Named "new_http_archive" }} {{ template "lexicon_entry.html" .Named "github_repo" }} {{ template "lexicon_entry.html" .Named "gitlab_repo" }} {{ template "lexicon_entry.html" .Named "arch" }}