package

This function declares metadata that applies to every subsequent rule in the package.

The package function is used at most once within a build package (BUILD file). It is recommended that the package function is called at the top of the file, before any rule.

Arguments

Examples

The declaration below declares that the rules in this package are visible only to members of package group //foo:target. Individual visibility declarations on a rule, if present, override this specification.
package(default_visibility = ["//foo:target"])

package_group

package_group(name, packages, includes)

This function defines a set of build packages. Package groups are used for visibility control. You can grant access to a rule to one or more package groups, every rule, or only to rules declared in the same package. For more detailed description of the visibility system, see the visibility attribute.

Arguments

Examples

The following 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"],
)

Description

# Description: ...

Each BUILD file should contain a Description comment.

Description comments may contain references to other documentation. A string that starts with "http" will become a link. HTML markup is allowed in description comments, but please keep the BUILD files readable. We encourage you to list the URLs of relevant design docs and howtos in these description comments.

distribs

distribs(distrib_methods)

distribs() specifies the default distribution method (or methods) of the build rules in a BUILD file. The distribs() 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 distribution methods.

Arguments

The argument, distrib_methods, is a list of distribution-method strings.

exports_files

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

Arguments

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.

glob

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 build package that:

If the exclude_directories argument is enabled (1), files of type directory will be omitted from the results (default 1).

There are several important limitations and caveats:

  1. Globs only match files in your source tree, never generated files. If you are building a target that requires both source and generated files, create an explicit list of generated files, and use + to add it to the result of the glob() call.
  2. Globs may match files in subdirectories. And subdirectory names may be wildcarded. However...
  3. Labels are not allowed to cross the package boundary and glob does not match files in subpackages. For example, the glob expression **/*.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.
  4. The restriction above applies to all glob expressions, no matter which wildcards they use.

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.

Glob Examples

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

java_test(
    name = "myprog",
    srcs = ["myprog.java"],
    data = glob(
        ["testdata/*.txt"],
        exclude = ["testdata/experimental.txt"],
    ),
)

Recursive Glob Examples

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

java_test(
    name = "mytest",
    srcs = ["mytest.java"],
    data = glob(["testdata/**/*.txt"]),
)

licenses

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.

Arguments

The argument, license_types, is a list of license-type strings.

include

include(name)

include() incorporates build language definitions from an external file into the evaluation of the current BUILD file.