package(default_deprecation,
default_obsolete,
default_testonly,
default_visibility,
features)
This function declares metadata that applies to every subsequent rule in the package. It is used at most once within a package (BUILD file).
It is recommended that the package function is called at the top of the file, before any rule.
default_visibility
:
The default visibility of the rules in this package.
(List of labels; optional)Every rule in this package has the visibility specified in this
attribute, unless otherwise specified in the visibility
attribute of the rule. For detailed information about the syntax of this
attribute, see the documentation of the visibility
attribute. The package default visibility applies neither to the
exports_files function nor to the
cc_public_library rule (which are
public by default).
default_obsolete
:
The default value of obsolete
property
for all rules in this package. (Boolean; optional; default is 0)
default_deprecation
:
Sets the default deprecation
message
for all rules in this package. (String; optional)
default_testonly
:
Sets the default testonly
property
for all rules in this package. (Boolean; optional; default is 0 except as noted)
In packages under javatests
the default value is 1.
features
:
Sets various flags that affect the semantics of this BUILD file.
(List strings; optional)
This feature is mainly used by the people working on the build system to tag packages that need some kind of special handling. Do not use this unless explicitly requested by someone working on the build system.
//foo:target
. Individual visibility declarations
on a rule, if present, override this specification.
package(default_visibility = ["//foo:target"])
package_group(name, packages, includes)
This function defines a set of packages and assigns a label to the
group. The label can be referenced in visibility
attributes.
Package groups are used for visibility control. You can grant access to a rule to one or more package groups, every rule in the entire source tree, or only to rules declared in the same package. For more detailed description of the visibility system, see the visibility attribute.
name
:
A unique name for this rule.
(Name; required)
packages
:
A complete enumeration of packages in this group.
(List of Package; optional)Packages should be referred to using their full names,
starting with a double slash. For
example, //foo/bar/main
is a valid element
of this list.
You can also specify wildcards: the specification
//foo/...
specifies every package under
//foo
, including //foo
itself.
If this attribute is missing, the package group itself will contain no packages (but it can still include other package groups).
includes
:
Other package groups that are included in this one.
(List of labels; optional)The labels in this attribute must refer to other package
groups. Packages in referenced package groups are taken to be part
of this package group. This is transitive, that is, if package
group a
contains package group b
,
and b
contains package group c
, every
package in c
will also be a member of a
.
package_group
declaration specifies a
package group called "tropical" that contains tropical fruits.
package_group( name = "tropical", packages = [ "//fruits/mango", "//fruits/orange", "//fruits/papaya/...", ], )The following declarations specify the package groups of a fictional application:
package_group( name = "fooapp", includes = [ ":controller", ":model", ":view", ], ) package_group( name = "model", packages = ["//fooapp/database"], ) package_group( name = "view", packages = [ "//fooapp/swingui", "//fooapp/webui", ], ) package_group( name = "controller", packages = ["//fooapp/algorithm"], )
exports_files([label, ...], visibility, licenses)
exports_files()
specifies a list of files belonging to
this package that are exported to other packages but not otherwise
mentioned in the BUILD file.
The BUILD file for a package may only refer to files belonging to another
package if they are mentioned somewhere in the other packages's BUILD file,
whether as an input to a rule or an explicit or implicit output from a rule.
The remaining files are not associated with a specific rule but are just "data",
and for these, exports_files
ensures that they may be referenced by
other packages. (One kind of data for which this is particularly useful are
shell scripts.)
Note: A BUILD file only consisting of exports_files()
statements
is needless though, as there are no BUILD rules that could own any files.
The files listed can already be accessed through the containing package and
exported from there if needed.
The argument is a list of names of files within the current package. A
visibility declaration can also be specified; in this case, the files will be
visible to the targets specified. If no visibility is specified, the files
will be visible to every package, even if a package default visibility was
specified in the package
function. The
licenses can also be specified.
The following example exports golden.txt
, a
text file from the test_data
package, so that other
packages may use it, for example, in the data
attribute
of tests.
# from //test_data/BUILD exports_files(["golden.txt"])
glob(include, exclude=[], exclude_directories=1)
Glob is a helper function that can be used anywhere a list of filenames
is expected. It takes one or two lists of filename patterns containing
the *
wildcard: as per the Unix shell, this wildcard
matches any string excluding the directory separator /
.
In addition filename patterns can contain the recursive **
wildcard. This wildcard will match zero or more complete
path segments separated by the directory separator /
.
This wildcard can only be used as a complete path segment. For example,
"x/**/*.java"
is legal, but "test**/testdata.xml"
and "**.java"
are both illegal. No other wildcards are supported.
Glob returns a list of every file in the current package that:
include
. exclude
(default []).
If the exclude_directories
argument is enabled (set to 1), files of
type directory will be omitted from the results (default 1).
There are several important limitations and caveats:
+
to add it to the result of the
glob()
call.
**/*.cc
in package
x
does not include x/y/z.cc
if
x/y
exists as a package (either as
x/y/BUILD
, or somewhere else on the package-path). This
means that the result of the glob expression actually depends on the
existence of BUILD files — that is, the same glob expression would
include x/y/z.cc
if there was no package called
x/y
or it was marked as deleted using the
--deleted_packages
flag.
.
is matched by
both the **
and the *
wildcards.
In general, you should try to provide an appropriate extension (e.g. *.html) instead of using a bare '*' for a glob pattern. The more explicit name is both self documenting and ensures that you don't accidentally match backup files, or emacs/vi/... auto-save files.
When writing build rules you can enumerate the elements of the glob. This enables generating individual rules for every input, for example. See the expanded glob example section below.
Create a Java library built from all java files in this directory,
and all files generated by the :gen_java_srcs
rule.
java_library( name = "mylib", srcs = glob(["*.java"]) + [":localize_strings"], deps = "...", ) genrule( name = "gen_java_srcs", outs = [ "Foo.java", "Bar.java", ], ... )
Include all txt files in directory testdata except experimental.txt. Note that files in subdirectories of testdata will not be included. If you want those files to be included, use a recursive glob (**).
sh_test( name = "mytest", srcs = ["mytest.sh"], data = glob( ["testdata/*.txt"], exclude = ["testdata/experimental.txt"], ), )
Create a library built from all java files in this directory and all subdirectories except those whose path includes a directory named testing. Subdirectories containing a BUILD file are ignored. This should be a very common pattern.
java_library( name = "mylib", srcs = glob( ["**/*.java"], exclude = ["**/testing/**"], ), )
Make the test depend on all txt files in the testdata directory, its subdirectories
sh_test( name = "mytest", srcs = ["mytest.sh"], data = glob(["testdata/**/*.txt"]), )
Create an individual genrule for *_test.cc in the current directory that counts the number of lines in the file.
# Conveniently, the build language supports list comprehensions. [genrule( name = "count_lines_" + f[:-3], # strip ".cc" srcs = [f], outs = ["%s-linecount.txt" % f[:-3]], cmd = "wc -l $< >$@", ) for f in glob(["*_test.cc"])]
If the BUILD file above is in package //foo and the package contains three
matching files, a_test.cc, b_test.cc and c_test.cc then running
bazel query '//foo:all'
will list all rules that were generated:
$ bazel query '//foo:all' | sort //foo:count_lines_a_test //foo:count_lines_b_test //foo:count_lines_c_test
licenses(license_types)
licenses()
specifies the default license type (or types)
of the build rules in a BUILD
file.
The licenses()
directive should appear close to the
beginning of the BUILD
file, before any build rules, as it
sets the BUILD
-file scope default for build rule license
types.
The argument, license_types
,
is a list of license-type strings.
The following example specifies a single license type of
"notice"
. Third-party software licenses that do not require
publishing of source code changes but require some sort of copyright or
other public notice are included in this license type.
licenses(["notice"]) # MIT license exports_files(["jquery-2.1.1.js"])
load(path, symbols...)
load()
is a statement that imports definitions from a
Skylark module. For example:
load("/tools/build_rules/build_test", "build_test") build_test(name = ...)
This will execute the
Skylark
module tools/build_rules/build_test.bzl
and import the symbol
build_test
in the local environment. By using more arguments, you
can load more symbols at once.
select({conditionA: valuesA, conditionB: valuesB, ...})
select()
is the helper function that makes an
attribute for a
rule configurable. It can
replace the right-hand side of
almost
any attribute assignment so that the attribute's value depends on the
Bazel flags passed in at the command line. This can be used, for
example, to define platform-specific dependencies or to embed
different resources depending on whether a rule is built in
"developer" vs. "release" mode.
Basic usage is as follows:
sh_binary( name = "myrule", srcs = select({ ":conditionA": ["myrule_a.sh"], ":conditionB": ["myrule_b.sh"], "//conditions:default": ["myrule_default.sh"] }) )
This makes the srcs
attribute of
a sh_binary
configurable by replacing its normal label
list assignment with a select
call that maps
configuration conditions to matching values. Each condition is a label
reference to
a config_setting
instance,
which "matches" if the rule's configuration matches an expected set of
values. The value of myrule#srcs
then becomes whichever
label list matches the current invocation.
Further notes:
//conditions:default
is
considered to match if no other condition matches. If this condition
is left out, some other rule must match to avoid an error.
select
cannot currently be embedded within an
attribute assignment. In other words, srcs = ["common.sh"]
+ select({ "conditionA": ["myrule_a.sh"], ...})
does not
currently work.
select
works with most, but not all, attributes.
workspace(name = "something")
This can only be used in the WORKSPACE file.
The sets an optional name for the repository.
This name is used for the directory that runfiles are stored in. For
example, if there is a runfile foo/bar and the WORKSPACE file contains
workspace(name = "baz")
, then the runfile will be output under
mytarget.runfiles/baz/foo/bar. If no workspace name is specified, then the
runfile will be symlinked to bar.runfiles/foo/bar.
A workspace name can contain slashes if a deeper directory listing is
desired (workspace(name = "baz/qux")
will place the runfile at
bar.runfiles/baz/qux/foo/bar).