A label is an identifier for a target. A typical label in its full canonical form looks like:
@@myrepo//my/app/main:app_binary
The first part of the label is the repository name, @@myrepo. The double-@
syntax signifies that this is a canonical repo
name, which is unique within
the workspace. Labels with canonical repo names unambiguously identify a target
no matter which context they appear in.
Often the canonical repo name is an arcane string that looks like
@@rules_java++toolchains+local_jdk. What is much more commonly seen is
labels with an apparent repo name,
which looks like:
@myrepo//my/app/main:app_binary
The only difference is the repo name being prefixed with one @ instead of two.
This refers to a repo with the apparent name myrepo, which could be different
based on the context this label appears in.
In the typical case that a label refers to the same repository from which
it is used, the repo name part may be omitted. So, inside @@myrepo the first
label is usually written as
//my/app/main:app_binary
The second part of the label is the un-qualified package name
my/app/main, the path to the package
relative to the repository root. Together, the repository name and the
un-qualified package name form the fully-qualified package name
@@myrepo//my/app/main. When the label refers to the same
package it is used in, the package name (and optionally, the colon)
may be omitted. So, inside @@myrepo//my/app/main,
this label may be written either of the following ways:
app_binary
:app_binary
It is a matter of convention that the colon is omitted for files, but retained for rules, but it is not otherwise significant.
The part of the label after the colon, app_binary is the un-qualified target
name. When it matches the last component of the package path, it, and the
colon, may be omitted. So, these two labels are equivalent:
//my/app/lib
//my/app/lib:lib
The name of a file target in a subdirectory of the package is the file's path
relative to the package root (the directory containing the BUILD file). So,
this file is in the my/app/main/testdata subdirectory of the repository:
//my/app/main:testdata/input.txt
Strings like //my/app and @@some_repo//my/app have two meanings depending on
the context in which they are used: when Bazel expects a label, they mean
//my/app:app and @@some_repo//my/app:app, respectively. But, when Bazel
expects a package (e.g. in package_group specifications), they reference the
package that contains that label.
A common mistake in BUILD files is using //my/app to refer to a package, or
to all targets in a package--it does not. Remember, it is
equivalent to //my/app:app, so it names the app target in the my/app
package of the current repository.
However, the use of //my/app to refer to a package is encouraged in the
specification of a package_group or in .bzl files, because it clearly
communicates that the package name is absolute and rooted in the top-level
directory of the workspace.
Relative labels cannot be used to refer to targets in other packages; the
repository identifier and package name must always be specified in this case.
For example, if the source tree contains both the package my/app and the
package my/app/testdata (each of these two directories has its own
BUILD file), the latter package contains a file named testdepot.zip. Here
are two ways (one wrong, one correct) to refer to this file within
//my/app:BUILD:
Wrong — testdata is a different package, so you can't use a relative path
testdata/testdepot.zip
Correct — refer to testdata with its full path
//my/app/testdata:testdepot.zipLabels starting with @@// are references to the main
repository, which will still work even from external repositories.
Therefore @@//a/b/c is different from
//a/b/c when referenced from an external repository.
The former refers back to the main repository, while the latter
looks for //a/b/c in the external repository itself.
This is especially relevant when writing rules in the main
repository that refer to targets in the main repository, and will be
used from external repositories.
For information about the different ways you can refer to targets, see target patterns.
Lexical specification of a label
Label syntax discourages use of metacharacters that have special meaning to the shell. This helps to avoid inadvertent quoting problems, and makes it easier to construct tools and scripts that manipulate labels, such as the Bazel Query Language.
The precise details of allowed target names are below.
Target names — package-name:target-name
target-name is the name of the target within the package. The name of a rule
is the value of the name attribute in the rule's declaration in a BUILD
file; the name of a file is its pathname relative to the directory containing
the BUILD file.
Target names must be composed entirely of characters drawn from the set a–z,
A–Z, 0–9, and the punctuation symbols !%-@^_"#$&'()*-+,;<=>?[]{|}~/..
Filenames must be relative pathnames in normal form, which means they must
neither start nor end with a slash (for example, /foo and foo/ are
forbidden) nor contain multiple consecutive slashes as path separators
(for example, foo//bar). Similarly, up-level references (..) and
current-directory references (./) are forbidden.
Wrong — Do not use .. to refer to files in other packages
Correct — Use
//package-name:filename
While it is common to use / in the name of a file target, avoid the use of
/ in the names of rules. Especially when the shorthand form of a label is
used, it may confuse the reader. The label //foo/bar/wiz is always a shorthand
for //foo/bar/wiz:wiz, even if there is no such package foo/bar/wiz; it
never refers to //foo:bar/wiz, even if that target exists.
However, there are some situations where use of a slash is convenient, or sometimes even necessary. For example, the name of certain rules must match their principal source file, which may reside in a subdirectory of the package.
Package names — //package-name:target-name
The name of a package is the name of the directory containing its BUILD file,
relative to the top-level directory of the containing repository.
For example: my/app.
On a technical level, Bazel enforces the following:
- Allowed characters in package names are the lowercase letters
athroughz, the uppercase lettersAthroughZ, the digits0through9, the characters! \"#$%&'()*+,-.;<=>?@[]^_`{|}(yes, there's a space character in there!), and of course forward slash/(since it's the directory separator). - Package names may not start or end with a forward slash character
/. - Package names may not contain the substring
//. This wouldn't make sense---what would the corresponding directory path be? - Package names may not contain the substring
/./or/../or/.../etc. This enforcement is done to avoid confusion when translating between a logical package name and a physical directory name, given the semantic meaning of the dot character in path strings.
On a practical level:
- For a language with a directory structure that is significant to its module system (for example, Java), it's important to choose directory names that are valid identifiers in the language. For example, don't start with a leading digit and avoid special characters, especially underscores and hyphens.
- Although Bazel supports targets in the workspace's root package (for example,
//:foo), it's best to leave that package empty so all meaningful packages have descriptive names.
Rules
A rule specifies the relationship between inputs and outputs, and the steps to build the outputs. Rules can be of one of many different kinds (sometimes called the rule class), which produce compiled executables and libraries, test executables and other supported outputs as described in the Build Encyclopedia.
BUILD files declare targets by invoking rules.
In the example below, we see the declaration of the target my_app
using the cc_binary rule.
cc_binary(
name = "my_app",
srcs = ["my_app.cc"],
deps = [
"//absl/base",
"//absl/strings",
],
)
Every rule invocation has a name attribute (which must be a valid
target name), that declares a target within the package
of the BUILD file.
Every rule has a set of attributes; the applicable attributes for a given rule, and the significance and semantics of each attribute are a function of the rule's kind; see the Build Encyclopedia for a list of rules and their corresponding attributes. Each attribute has a name and a type. Some of the common types an attribute can have are integer, label, list of labels, string, list of strings, output label, list of output labels. Not all attributes need to be specified in every rule. Attributes thus form a dictionary from keys (names) to optional, typed values.
The srcs attribute present in many rules has type "list of labels"; its
value, if present, is a list of labels, each being the name of a target that is
an input to this rule.
In some cases, the name of the rule kind is somewhat arbitrary, and more interesting are the names of the files generated by the rule, and this is true of genrules. For more information, see General Rules: genrule.
In other cases, the name is significant: for *_binary and *_test rules,
for example, the rule name determines the name of the executable produced by
the build.
This directed acyclic graph over targets is called the target graph or build dependency graph, and is the domain over which the Bazel Query tool operates.
| Targets | BUILD files |