Google Git
Sign in
bazel / bazel / d08b27fa9701fecfdb69e1b0d1ac2459efc2129b / . / docs / historical / build-encyclopedia.html
blob: 53215fc1c04dba60bdf621349f87173c3e7d483f [file] [log] [blame]
<!DOCTYPE html>
<html>
<head>
<title>Bazel BUILD Encyclopedia of Functions</title>
<style type="text/css" id="internalStyle">
body {
background-color: #ffffff;
color: black;
margin-right: 10%;
margin-left: 10%;
}
h1, h2, h3, h4, h5, h6 {
color: #dd7755;
font-family: sans-serif;
}
@media print {
/* Darker version for printing */
h1, h2, h3, h4, h5, h6 {
color: #008000;
font-family: helvetica, sans-serif;
}
}
h1 {
text-align: center;
}
h2 {
margin-left: -0.5in;
}
h3 {
margin-left: -0.25in;
}
h4 {
margin-left: -0.125in;
}
hr {
margin-left: -1in;
}
address {
text-align: right;
}
/* A compact unordered list */
ul.tight > li {
margin-bottom: 0;
}
/* Use the <code> tag for bits of code and <var> for variable and object names. */
code,pre,samp,var {
color: #006000;
}
/* Use the <file> tag for file and directory paths and names. */
file {
color: #905050;
font-family: monospace;
}
/* Use the <kbd> tag for stuff the user should type. */
kbd {
color: #600000;
}
div.note p {
float: right;
width: 3in;
margin-right: 0%;
padding: 1px;
border: 2px solid #60a060;
background-color: #fffff0;
}
table.grid {
background-color: #ffffee;
border: 1px solid black;
border-collapse: collapse;
margin-left: 2mm;
margin-right: 2mm;
}
table.grid th,
table.grid td {
border: 1px solid black;
padding: 0 2mm 0 2mm;
}
/* Use pre.code for code listings.
Use pre.interaction for "Here's what you see when you run a.out.".
(Within pre.interaction, use <kbd> things the user types)
*/
pre.code {
background-color: #FFFFEE;
border: 1px solid black;
color: #004000;
font-size: 10pt;
margin-left: 2mm;
margin-right: 2mm;
padding: 2mm;
-moz-border-radius: 12px 0px 0px 0px;
}
pre.interaction {
background-color: #EEFFEE;
color: #004000;
padding: 2mm;
}
pre.interaction kbd {
font-weight: bold;
color: #000000;
}
/* legacy style */
pre.interaction b.astyped {
color: #000000;
}
h1 { margin-bottom: 5px; }
.toc { margin: 0px; }
ul li { margin-bottom: 1em; }
ul.toc li { margin-bottom: 0px; }
em.harmful { color: red; }
.deprecated { text-decoration: line-through; }
.discouraged { text-decoration: line-through; }
#rules { width: 980px; border-collapse: collapse; }
#rules td { border-top: 1px solid gray; padding: 4px; vertical-align: top; }
#rules th { text-align: left; padding: 4px; }
table.layout { width: 980px; }
table.layout td { vertical-align: top; }
#maintainer { text-align: right; }
dt {
font-weight: bold;
margin-top: 0.5em;
margin-bottom: 0.5em;
}
dd dt {
font-weight: normal;
text-decoration: underline;
color: gray;
}
</style>
<style type="text/css">
.rule-signature {
color: #006000;
font-family: monospace;
}
</style>
</head>
<body>
<h1>Bazel BUILD Encyclopedia of Functions</h1>
<h2>Contents</h2>
<h3>Concepts and terminology</h3>
<table class="layout"><tr><td>
<ul class="toc">
<li><a href="#common-definitions">Common definitions</a>:
<ul>
<li><a href="#sh-tokenization">Bourne shell tokenization</a></li>
<li><a href="#label-expansion">Label expansion</a></li>
<li><a href="#common-attributes">Common attributes</a></li>
<li><a href="#common-attributes-tests">Common attributes for tests</a></li>
<li><a href="#common-attributes-binaries">Common attributes for binaries</a></li>
<li><a href="#implicit-outputs">Implicit output targets</a></li>
</ul>
</li>
</ul>
</td><td>
<ul class="toc">
<li><a href="#make_variables">"Make" variables</a>
<ul class="toc">
<li><a href="#make-var-substitution">"Make" variable substitution</a></li>
<li><a href="#predefined_variables">Predefined variables</a></li>
<li><a href="#define_your_own_make_vars">Defining your own variables</a>
<ul>
<li><a href="#vardef">vardef</a></li>
<li><a href="#varref">varref</a></li>
</ul>
</li>
</ul>
<li><a href="#predefined-python-variables">Predefined Python Variables</a></li>
</ul>
</td><td>
<ul class="toc">
<li><a href="#include">include</a></li>
<li><a href="#package">package</a></li>
<li><a href="#package_group">package_group</a></li>
<li><a href="#description">Description</a></li>
<li><a href="#distribs">distribs</a></li>
<li><a href="#licenses">licenses</a></li>
<li><a href="#exports_files">exports_files</a></li>
<li><a href="#glob">glob</a></li>
</ul>
</td></tr></table>
<h3>Rules</h3>
<table id="rules" summary="Table of rules sorted by language">
<colgroup span="5" width="20%"></colgroup>
<tr><th>Language</th><th>Binary rules</th><th>Library rules</th><th>Test rules</th><th>Other rules</th><th></th></tr>
<tr>
<td class="lang">Android</td>
<td><a href="#android_binary">android_binary</a></td>
<td><a href="#android_library">android_library</a></td>
<td><a href="#android_test">android_test</a></td>
<td><a href="#android_device">android_device</a></td>
<td><a href="#android_manifest_merge">android_manifest_merge</a><br/><a href="#android_resources">android_resources</a></td>
<tr>
<td class="lang">Java</td>
<td><a href="#java_binary">java_binary</a></td>
<td><a href="#java_import">java_import</a><br/><a href="#java_library">java_library</a></td>
<td><a href="#java_test">java_test</a></td>
<td><a href="#java_plugin">java_plugin</a><br/><a href="#java_wrap_cc">java_wrap_cc</a><br/></td>
<td></td>
<tr>
<td class="lang">Shell</td>
<td><a href="#sh_binary">sh_binary</a></td>
<td><a href="#sh_library">sh_library</a></td>
<td><a href="#sh_test">sh_test</a></td>
<td></td>
<td></td>
<tr><th>&nbsp;</th></tr><tr><th colspan="5">Rules that do not apply to a specific programming language</th></tr> <tr>
<td class="lang">General</td>
<td><a href="#filegroup">filegroup</a></td>
<td><a href="#test_suite">test_suite</a></td>
<td><a href="#genrule">genrule</a></td>
</table>
<h2 id="common-definitions">Common definitions</h2>
<p>This section defines various terms and concepts that are common to
many functions or build rules below.
</p>
<!-- we haven't defined 'rules' or 'attributes' yet. -->
<h3 id='sh-tokenization'>Bourne shell tokenization</h3>
<p>
Certain string attributes of some rules are split into multiple
words according to the tokenization rules of the Bourne shell:
unquoted spaces delimit separate words, and single- and
double-quotes characters and backslashes are used to prevent
tokenization.
</p>
<p>
Those attributes that are subject to this tokenization are
explicitly indicated as such in their definitions in this document.
</p>
<p>
Attributes subject to "Make" variable expansion and Bourne shell
tokenization are typically used for passing arbitrary options to
compilers and other tools, such as the <code>copts</code> attribute
of <code>cc_library</code>, or the <code>javacopts</code> attribute of
<code>java_library</code>. Together these substitutions allow a
single string variable to expand into a configuration-specific list
of option words.
</p>
<h3 id='label-expansion'>Label expansion</h3>
<p>
Some string attributes of a very few rules are subject to label
expansion: if those strings contain a valid build label as a
substring, such as <code>//mypkg:target</code>, and that label is a
declared prerequisite of the current rule, it is expanded into the
pathname of the file represented by the target <code>//mypkg:target</code>.
</p>
<p>
Example attributes include the <code>cmd</code> attribute of
genrule, and the <code>linkopts</code> attribute
of <code>cc_library</code>. The details may vary significantly in
each case, over such issues as: whether relative labels are
expanded; how labels that expand to multiple files are
treated, etc. Consult the rule attribute documentation for
specifics.
</p>
<h3 id="common-attributes">Attributes common to all build rules</h3>
<p>This section describes attributes that are common to all build rules.<br/>
Please note that it is an error to list the same label twice in a list of
labels attribute.
</p>
<ul>
<li id="common.deps"><code>deps</code>:
A list of dependencies of this rule.
<i>(List of <a href="build-ref.html#labels">labels</a>; optional)</i><br/>
The precise semantics of what it means for this rule to depend on
another using <code>deps</code> are specific to the kind of this rule,
and the rule-specific documentation below goes into more detail.
At a minimum, though, the targets named via <code>deps</code> will
appear in the <code>*.runfiles</code> area of this rule, if it has
one.
<p>Most often, a <code>deps</code> dependency is used to allow one
module to use symbols defined in another module written in the
same programming language and separately compiled. Cross-language
dependencies are also permitted in many cases: for example,
a <code>java_library</code> rule may depend on C++ code in
a <code>cc_library</code> rule, by declaring the latter in
the <code>deps</code> attribute. See the definition
of <a href="build-ref.html#deps">dependencies</a> for more
information.</p>
<p>Almost all rules permit a <code>deps</code> attribute, but where
this attribute is not allowed, this fact is documented under the
specific rule.</p></li>
<li id="common.data"><code>data</code>:
The list of files needed by this rule at runtime.
<i>(List of <a href="build-ref.html#labels">labels</a>; optional)</i><br/>
Targets named in the <code>data</code> attribute will appear in
the <code>*.runfiles</code> area of this rule, if it has one. This
may include data files needed by a binary or library, or other
programs needed by it. See the
<a href="build-ref.html#data">data dependencies</a> section for more
information about how to depend on and use data files.
<p>Almost all rules permit a <code>data</code> attribute, but where
this attribute is not allowed, this fact is documented under the
specific rule.</p></li>
<li id="common.deprecation"><code>deprecation</code>:
<i>(String; optional)</i><br/>
An explanatory warning message associated with this rule.
Typically this is used to notify users that a rule has become obsolete,
or has become superseded by another rule, is private to a package, or is
perhaps "considered harmful" for some reason. It is a good idea to include
some reference (like a webpage, a bug number or example migration CLs) so
that one can easily find out what changes are required to avoid the message.
If there is a new target that can be used as a drop in replacement, it is a good idea
to just migrate all users of the old target.
<p>
This attribute has no effect on the way things are built, but it
may affect a build tool's diagnostic output. The build tool issues a
warning when a rule with a <code>deprecation</code> attribute is
depended upon by another rule.</p>
<p>
Intra-package dependencies are exempt from this warning, so that,
for example, building the tests of a deprecated rule does not
encounter a warning.</p>
<p>
If a deprecated rule depends on another deprecated rule, no warning
message is issued.</p>
<p>
Once people have stopped using it, the package can be removed or marked as
<a href="#common.obsolete"><code>obsolete</code></a>.</p></li>
<li id="common.distribs"><code>distribs</code>:
<i>(List of strings; optional)</i><br/>
A list of distribution-method strings to be used for this particular build rule.
Overrides the <code>BUILD</code>-file scope defaults defined by the
<a href="#distribs"><code>distribs()</code></a> directive.</li>
<li id="common.licenses"><code>licenses</code>:
<i>(List of strings; optional)</i><br/>
A list of license-type strings to be used for this particular build rule.
Overrides the <code>BUILD</code>-file scope defaults defined by the
<a href="#licenses"><code>licenses()</code></a> directive.</li>
<li id="common.obsolete"><code>obsolete</code>:
<i>(Boolean; optional; default 0)</i><br/>
If 1, only obsolete targets can depend on this target. It is an error when
a non-obsolete target depends on an obsolete target.
<p>
As a transition, one can first mark a package as in
<a href="#common.deprecation"><code>deprecation</code></a>.</p>
<p>
This attribute is useful when you want to prevent a target from
being used but are yet not ready to delete the sources.</p></li>
<li id="common.tags"><code>tags</code>:
List of arbitrary text tags. Tags may be any valid string; default is the
empty list.<br/>
<i>Tags</i> can be used on any rule; but <i>tags</i> are most useful
on test and <code>test_suite</code> rules. Tags on non-test rules
are only useful to humans and/or external programs.
<i>Tags</i> are generally used to annotate a test's role in your debug
and release process. The use of tags and size elements
gives flexibility in assembling suites of tests based around codebase
check-in policy.
<p>
A few tags have special meaning to the build tool; consult
the <a href='bazel-user-manual.html#tags_keywords'>Bazel
documentation</a> for details.
</p></li>
<li id="common.testonly"><code>testonly</code>:
<i>(Boolean; optional; default 0 except as noted)</i><br />
If 1, only testonly targets (such as tests) can depend on this target.
<p>Equivalently, a rule that is not <code>testonly</code> is not allowed to
depend on any rule that is <code>testonly</code>.</p>
<p>Tests (<code>*_test</code> rules)
and test suites (<a href="#test_suite">test_suite</a> rules)
are <code>testonly</code> by default.</p>
<p>By virtue of
<a href="#package.default_testonly"><code>default_testonly</code></a>,
targets under <code>javatests</code> are <code>testonly</code> by default.</p>
<p>This attribute is intended to mean that the target should not be
contained in binaries that are released to production.</p>
<p>Because testonly is enforced at build time, not run time, and propagates
virally through the dependency tree, it should be applied judiciously. For
example, stubs and fakes that
are useful for unit tests may also be useful for integration tests
involving the same binaries that will be released to production, and
therefore should probably not be marked testonly. Conversely, rules that
are dangerous to even link in, perhaps because they unconditionally
override normal behavior, should definitely be marked testonly.</p></li>
<li id="common.visibility"><code>visibility</code>:
<i>(List of <a href="build-ref.html#labels">labels</a>; optional; default private)</i><br/>
<p>The <code>visibility</code> attribute on a rule controls whether
the rule can be used by other packages. Rules are always visible to
other rules declared in the same package.</p>
<p>There are five forms (and one temporary form) a visibility label can take:
<ul>
<li><code>['//visibility:public']</code>: Anyone can use this rule.</li>
<li><code>['//visibility:private']</code>: Only rules in this package
can use this rule. Rules in <code>javatests/foo/bar</code>
can always use rules in <code>java/foo/bar</code>.
</li>
<li><code>['//some/package:__pkg__', '//other/package:__pkg__']</code>:
Only rules in <code>some/package</code> and <code>other/package</code>
(defined in <code>some/package/BUILD</code> and
<code>other/package/BUILD</code>) have access to this rule. Note that
sub-packages do not have access to the rule; for example,
<code>//some/package/foo:bar</code> or
<code>//other/package/testing:bla</code> wouldn't have access.
<code>__pkg__</code> is a special target and must be used verbatim.
It represents all of the rules in the package.
</li>
<li><code>['//project:__subpackages__', '//other:__subpackages__']</code>:
Only rules in packages <code>project</code> or <code>other</code> or
in one of their sub-packages have access to this rule. For example,
<code>//project:rule</code>, <code>//project/library:lib</code> or
<code>//other/testing/internal:munge</code> are allowed to depend on
this rule (but not <code>//independent:evil</code>)
</li>
<li><code>['//some/package:my_package_group']</code>:
A <a href="#package_group">package group</a> is
a named set of package names. Package groups can also grant access rights
to entire subtrees, e.g.<code>//myproj/...</code>.
</li>
</ul>
<p>The visibility specifications of <code>//visibility:public</code>,
<code>//visibility:private</code> and
<code>//visibility:legacy_public</code>
can not be combined with any other visibility specifications.
A visibility specification may contain a combination of package labels
(i.e. //foo:__pkg__) and package_groups.</p>
<p>If a rule does not specify the visibility attribute,
the <code><a href="#package">default_visibility</a></code>
attribute of the <code><a href="#package">package</a></code>
statement in the BUILD file containing the rule is used
(except <a href="#exports_files">exports_files</a> and
<a href="#cc_public_library">cc_public_library</a>, which always default to
public).</p>
<p><b>Example</b>:</p>
<p>
File <code>//frobber/bin/BUILD</code>:
</p>
<pre class="code">
# This rule is visible to everyone
java_binary(
name = "executable",
visibility = ["//visibility:public"],
deps = [":library"],
)
# This rule is visible only to rules declared in the same package
java_library(
name = "library",
visibility = ["//visibility:private"],
)
# This rule is visible to rules in package //object and //noun
java_library(
name = "subject",
visibility = [
"//noun:__pkg__",
"//object:__pkg__",
],
)
# See package group //frobber:friends (below) for who can access this rule.
java_library(
name = "thingy",
visibility = ["//frobber:friends"],
)
</pre>
<p>
File <code>//frobber/BUILD</code>:
</p>
<pre class="code">
# This is the package group declaration to which rule //frobber/bin:thingy refers.
#
# Our friends are packages //frobber, //fribber and any subpackage of //fribber.
package_group(
name = "friends",
packages = [
"//fribber/...",
"//frobber",
],
)
</pre></li>
</ul>
<h3 id="common-attributes-tests">Attributes common to all test rules (*_test)</h3>
<p>This section describes attributes that are common to all test rules.</p>
<ul>
<li id="test.args"><code>args</code>:
Add these arguments to the <code>--test_arg</code>
when executed by <code>bazel test</code>.
<i>(List of strings; optional; subject to
<a href="#make_variables">"Make variable"</a> substitution and
<a href="#sh-tokenization">Bourne shell tokenization</a>)</i><br/>
These arguments are passed before the <code>--test_arg</code> values
specified on the <code>bazel test</code> command line.</li>
<li id="test.flaky"><code>flaky</code>:
Marks test as flaky. <i>(Boolean; optional)</i><br/>
If set, executes the test up to 3 times before being declared as failed.
By default this attribute is set to 0 and test is considered to be stable.
Note, that use of this attribute is generally discouraged - we do prefer
all tests to be stable.</li>
<li id="test.local"><code>local</code>:
Forces the test to be run locally. <i>(Boolean; optional)</i><br/>
By default this attribute is set to 0 and the default testing strategy is
used. This is equivalent to providing 'local' as a tag
(<code>tags=["local"]</code>).</li>
<li id="test.shard_count"><code>shard_count</code>:
Specifies the number of parallel shards
to use to run the test. <i>(Non-negative integer less than or equal to 50;
optional)</i><br/>
This value will override any heuristics used to determine the number of
parallel shards with which to run the test.</li>
<li id="test.size"><code>size</code>:
How "heavy" the test is
<i>(String "enormous", "large" "medium" or "small",
default is "medium")</i><br/>
A classification of the test's "heaviness": how much time/resources
it needs to run. This is useful when deciding which tests to run.
Before checking in a change, you might run the small tests.
Before a big release, you might run the large tests.
</li>
<li id="test.timeout"><code>timeout</code>:
How long the test is
normally expected to run before returning.
<i>(String "eternal", "long", "moderate", or "short"
with the default derived from a test's size attribute)</i><br/>
While a test's size attribute controls resource estimation, a test's
timeout may be set independently. If not explicitly specified, the
timeout is based on the test's size (with "small" &rArr; "short",
"medium" &rArr; "moderate", etc...). While size and runtime are generally
heavily correlated, they are not strictly causal, hence the ability to set
them independently.</li>
</ul>
<h3 id="common-attributes-binaries">Attributes common to all binary rules (*_binary)</h3>
<p>This section describes attributes that are common to all binary rules.</p>
<ul>
<li id="binary.args"><code>args</code>:
Add these arguments to the target when executed by
<code>bazel run</code>.
<i>(List of strings; optional; subject to
<a href="#make_variables">"Make variable"</a> substitution and
<a href="#sh-tokenization">Bourne shell tokenization</a>)</i><br/>
These arguments are passed to the target before the target options
specified on the <code>bazel run</code> command line.
<p>Most binary rules permit an <code>args</code> attribute, but where
this attribute is not allowed, this fact is documented under the
specific rule.</p></li>
<li id="binary.output_licenses"><code>output_licenses</code>:
The licenses of the output files that this binary generates.
<i>(List of strings; optional)</i><br/>
Describes the licenses of the output of the binary generated by
the rule. When a binary is referenced in a host attribute (for
example, the <code>tools</code> attribute of
a <code>genrule</code>), this license declaration is used rather
than the union of the licenses of its transitive closure. This
argument is useful when a binary is used as a tool during the
build of a rule, and it is not desirable for its license to leak
into the license of that rule. If this attribute is missing, the
license computation proceeds as if the host dependency was a
regular dependency.
<p><em class="harmful">WARNING: in some cases (specifically, in
genrules) the build tool cannot guarantee that the binary
referenced by this attribute is actually used as a tool, and is
not, for example, copied to the output. In these cases, it is the
responsibility of the user to make sure that this is
true.</em></p></li>
</ul>
<h3 id="implicit-outputs">Implicit output targets</h3>
<p>When you define a build rule in a BUILD file, you are explicitly
declaring a new, named rule target in a package. Many build rule
functions also <i>implicitly</i> entail one or more output file
targets, whose contents and meaning are rule-specific.
For example, when you explicitly declare a
<code>java_binary(name='foo', ...)</code> rule, you are also
<i>implicitly</i> declaring an output file
target <code>foo_deploy.jar</code> as a member of the same package.
(This particular target is a self-contained Java archive suitable
for deployment.)
</p>
<p>
Implicit output targets are first-class members of the build
target graph. Just like other targets, they are built on demand,
either when specified in the top-level built command, or when they
are necessary prerequisites for other build targets. They can be
referenced as dependencies in BUILD files, and can be observed in
the output of analysis tools such as <code>bazel query</code>.
</p>
<p>
For each kind of build rule, the rule's documentation contains a
special section detailing the names and contents of any implicit
outputs entailed by a declaration of that kind of rule.
</p>
<p>
Please note an important but somewhat subtle distinction between the
two namespaces used by the build system. Build
<a href="build-ref.html#labels">labels</a> identify <em>targets</em>,
which may be rules or files, and file targets may be divided into
either source (or input) file targets and derived (or output) file
targets. These are the things you can mention in BUILD files,
build from the command-line, or examine using <code>bazel query</code>;
this is the <em>target namespace</em>. Each file target corresponds
to one actual file on disk (the "file system namespace"); each rule
target may correspond to zero, one or more actual files on disk.
There may be files on disk that have no corresponding target; for
example, <code>.o</code> object files produced during C++ compilation
cannot be referenced from within BUILD files or from the command line.
In this way, the build tool may hide certain implementation details of
how it does its job. This is explained more fully in
the <a href="build-ref.html">BUILD Concept Reference</a>.
</p>
<!-- ============================================
binary
============================================
-->
<h2 id="binary">*_binary</h2>
<p>A <code>*_binary</code> rule compiles an application. This might be
an executable, a <code>.jar</code> file, and/or a collection of scripts.</p>
<h3 id="android_binary">android_binary</h3>
<p class="rule-signature">
android_binary(<a href="#android_binary.name">name</a>,
<a href="#android_binary.deps">deps</a>,
<a href="#android_binary.srcs">srcs</a>,
<a href="#android_binary.resources">resources</a>,
<a href="#android_binary.aaptopts">aaptopts</a>,
<a href="#android_binary.debug_key">debug_key</a>,
<a href="#common.deprecation">deprecation</a>,
<a href="#android_binary.dexopts">dexopts</a>,
<a href="#common.distribs">distribs</a>,
<a href="#common.licenses">licenses</a>,
<a href="#common.obsolete">obsolete</a>,
<a href="#android_binary.proguard_generate_mapping">proguard_generate_mapping</a>,
<a href="#android_binary.proguard_specs">proguard_specs</a>,
<a href="#android_binary.strict_android_deps">strict_android_deps</a>,
<a href="#common.tags">tags</a>,
<a href="#common.testonly">testonly</a>,
<a href="#common.visibility">visibility</a>)
</p>
<p>
Produces Android application package files (.apk).
</p>
<h4 id="android_binary_implicit_outputs">Implicit output targets</h4>
<ul>
<li><code><var>name</var>.apk</code>: An Android application
package file signed with debug keys and
<a href="http://developer.android.com/guide/developing/tools/zipalign.html">
zipaligned</a>, it could be used to develop and debug your application.
You cannot release your application when signed with the debug keys.</li>
<li><code><var>name</var>_unsigned.apk</code>: An unsigned version of the
above file that could be signed with the release keys before release to
the public.
</li>
<li><code><var>name</var>_deploy.jar</code>: A Java archive containing the
transitive closure of this target.
<p>The deploy jar contains all the classes that would be found by a
classloader that searched the runtime classpath of this target
from beginning to end.</p>
</li>
<li><code><var>name</var>_proguard.jar</code>: A Java archive containing
the result of running ProGuard on the
<code><var>name</var>_deploy.jar</code>.
This output is only produced if
<a href="#android_binary.proguard_specs">proguard_specs</a> attribute is
specified.
</li>
<li><code><var>name</var>_proguard.map</code>: A mapping file result of
running ProGuard on the <code><var>name</var>_deploy.jar</code>.
This output is only produced if
<a href="#android_binary.proguard_specs">proguard_specs</a> attribute is
specified and
<a href="#android_binary.proguard_generate_mapping">proguard_generate_mapping</a>
is set.
</li>
</ul>
<h4 id="android_binary">Arguments</h4>
<ul>
<li id="android_binary.name"><code>name</code>: A unique name for this rule. <i>(<a href="build-ref.html#name">Name</a>; required)</i></li>
<li id="android_binary.deps"><code>deps</code>:
The list of other libraries to be linked in to the binary target.
<i>(List of <a href="build-ref.html#labels">labels</a>; optional)</i><br/>
Permitted library types are: <code>android_library</code>,
<code>android_idl</code>, <code>java_library</code> with
<code>android</code> constraint and <code>cc_library</code> wrapping or
producing <code>.so</code> native libraries for the Android target platform.
</li>
<li id="android_binary.srcs"><code>srcs</code>:
The list of source files that are processed to create the target.
<i>(List of <a href="build-ref.html#labels">labels</a>; optional)</i>
<p><code>srcs</code> files of type <code>.java</code> are compiled.
<em>For readability's sake</em>, it is not good to put the name of a
generated <code>.java</code> source file into the <code>srcs</code>.
Instead, put the depended-on rule name in the <code>srcs</code>, as
described below.
</p>
<p><code>srcs</code> files of type <code>.srcjar</code> are unpacked and
compiled. (This is useful if you need to generate a set of .java files with
a genrule or build extension.)
</p>
<p>This rule currently forces source and class compatibility with Java 6.
</p>
<p><code>srcs</code> files of type <code>.jar</code> are linked in.
(This is useful if you have third-party <code>.jar</code> files
with no source.)
</p>
</li>
<li id="android_binary.resources"><code>resources</code>:
The <code>android_resources</code> target corresponding to this binary.
<i>(<a href="build-ref.html#labels">Label</a>; required)</i><br/>
The target describing the manifest, resources and assets used by this
binary.
</li>
<li id="android_binary.aaptopts"><code>aaptopts</code>:
Additional command-line flags for the aapt tool when generating apk. This
is only used if this rule uses other android_library project with resources.
<i>(List of strings; optional; subject to
<a href="#make_variables">"Make variable"</a> substitution and
<a href="#sh-tokenization">Bourne shell tokenization</a>)</i>
</li>
<li id="android_binary.debug_key"><code>debug_key</code>:
File containing debug keystore to be used to sign debug apk.
<i>(<a href="build-ref.html#labels">Label</a>; optional)</i>.
Points to a location of debug keystore file that is different than default
debug key. Usually you do not want to use key other than default key, so
this attribute should be omitted.
</li>
<li id="android_binary.dexopts"><code>dexopts</code>:
Additional command-line flags for the dx tool when generating classes.dex.
<i>(List of strings; optional; subject to
<a href="#make_variables">"Make variable"</a> substitution and
<a href="#sh-tokenization">Bourne shell tokenization</a>)</i><br/>
</li>
<li id="android_binary.proguard_generate_mapping"><code>proguard_generate_mapping</code>:
Whether to generate Proguard mapping file.
<i>(Boolean; optional, default is 0)</i><br/>
The mapping file will be generated only if <code>proguard_specs</code> is
specified. This file will list the mapping between the original and
obfuscated class, method, and field names.
<p><em class="harmful">WARNING: If you use this attribute, your Proguard specification
should contain neither <code>-dontobfuscate</code> nor <code>-printmapping</code>.
</em>.</p>
</li>
<li id="android_binary.proguard_specs"><code>proguard_specs</code>:
Files to be used as Proguard specification.
<i>(List of <a href="build-ref.html#labels">labels</a>; optional)</i><br/>
This file will describe the set of specifications to be used by Proguard.
</li>
<li id="android_binary.strict_android_deps"><code>strict_android_deps</code>:
<i>(Integer; optional; default is -1 (inherited))</i><br/>
<p>By default, javac will perform checks when compiling the java sources
in this library to verify that all explicitly mentioned classes were loaded
from directly specified <code>deps</code> (rather than from the transitive
closure of all <code>deps</code>), the transitive closure of
<del><code>srcs</code>-less libraries</del>, and the transitive closure of
<code>exports</code>. This default can be overridden when set to 0.</p>
</li>
</ul>
<h3 id="java_binary">java_binary</h3>
<p class="rule-signature">
java_binary(<a href="#java_binary.name">name</a>,
<a href="#java_binary.deps">deps</a>,
<a href="#java_binary.srcs">srcs</a>,
<a href="#common.data">data</a>,
<a href="#java_binary.resources">resources</a>,
<a href="#binary.args">args</a>,
<a href="#java_binary.classpath_resources">classpath_resources</a>,
<a href="#java_binary.create_executable">create_executable</a>,
<a href="#java_binary.deploy_env">deploy_env</a>,
<a href="#java_binary.deploy_manifest_lines">deploy_manifest_lines</a>,
<a href="#common.deprecation">deprecation</a>,
<a href="#common.distribs">distribs</a>,
<a href="#java_binary.javacopts">javacopts</a>,
<a href="#java_binary.jvm_flags">jvm_flags</a>,
<a href="#java_binary.launcher">launcher</a>,
<a href="#common.licenses">licenses</a>,
<a href="#java_binary.main_class">main_class</a>,
<a href="#common.obsolete">obsolete</a>,
<a href="#binary.output_licenses">output_licenses</a>,
<a href="#java_binary.plugins">plugins</a>,
<a href="#java_binary.runtime_deps">runtime_deps</a>,
<a href="#java_binary.stamp">stamp</a>,
<a href="#java_binary.swigdeps">swigdeps</a>,
<a href="#common.tags">tags</a>,
<a href="#common.testonly">testonly</a>,
<a href="#java_binary.use_testrunner">use_testrunner</a>,
<a href="#common.visibility">visibility</a>)
</p>
<p>
Builds a Java archive ("jar file"), plus a wrapper shell script with the same
name as the rule. The wrapper shell script uses a classpath that
includes, among other things, a jar file for each library on
which the binary depends.
</p>
<h4 id="java_binary_implicit_outputs">Implicit output targets</h4>
<ul>
<li><code><var>name</var>.jar</code>: A Java archive, containing the
class files and other resources corresponding to the binary's
direct dependencies.
</li>
<li><code><var>name</var>-src.jar</code>: An archive containing the sources ("source jar").</li>
<li><code><var>name</var>_deploy.jar</code>: A Java archive suitable
for deployment (only built if explicitly requested).
<p>Building the <code>&lt;java_binary_name&gt;_deploy.jar</code>
target for your rule creates a self-contained
<code>&lt;java_binary_name&gt;_deploy.jar</code> file with a manifest that
allows it to be run with the <code>java -jar</code> command or with the
wrapper script's <code>--singlejar</code> option. Using the wrapper script
is preferred, as it also passes the <a href="#java_binary.jvm_flags">JVM
flags</a> and the options to load SWIG libraries.</p>
<p>The deploy jar contains all the classes that would be found by a
classloader that searched the classpath from the binary's wrapper script
from beginning to end. It also contains the native libraries needed for SWIG
dependencies; these are automatically unpacked and loaded into the JVM at
runtime.</p>
</li>
<li><code><var>name</var>_deploy-src.jar</code>: An archive containing the sources collected from
the transitive closure of the target. These will matches the classes in the
<code>deploy.jar</code>, except for cases where jars have no matching source jar.</li>
</ul>
<h4 id="java_binary">Arguments</h4>
<ul>
<li id="java_binary.name"><code>name</code>: A unique name for this rule. <i>(<a href="build-ref.html#name">Name</a>; required)</i> <br/>This should be the same as the name of the source file that is the main
entry point of the application (minus the extension). For example, if
your entry point is called <code>Main.java</code>, then your name should
be <code>Main</code>.
</li>
<li id="java_binary.deps"><code>deps</code>:
The list of other libraries to be linked in to the target.
<i>(List of <a href="build-ref.html#labels">labels</a>; optional)</i><br/>
See general comments about <code>deps</code>
at <a href="#common-attributes">Attributes common to all build
rules</a>.
<p>These can be
<a href="#java_library"><code>java_library</code></a>,
<a href="#cc_library"><code>cc_library</code></a>, or
<a href="#java_wrap_cc"><code>java_wrap_cc</code></a> rules.</p>
<p>
If this rule has no <code>srcs</code>, then it should have
only one <code>deps</code>, the <code>java_library</code>
containing the <code>.java</code> file suggested by this
rule's <code>name</code>.
</p>
<p>
The following code snippet illustrates a common mistake:
</p>
<pre class="code">
java_binary(
name = "DontDoThis",
srcs = [
<var>...</var>,
<code class="deprecated">"GeneratedJavaFile.java"</code>, # a generated .java file
],
deps = [<code class="deprecated">":generating_rule",</code>], # rule that generates that file
)
</pre>
<p>This is better:</p>
<pre class="code">
java_binary(
name = "DoThisInstead",
srcs = [
<var>...</var>,
":generating_rule",
],
)
</pre>
<p>More <a href="#java_binary_examples">examples</a> are below.</p>
<p>
Why list the generating rule instead of file names in <code>srcs</code>?
Because it is more resilient to future changes: if the generating rule
generates different files in the future, you only need to fix one
place--the <code>outs</code> of the generating rule. Why not list the
generating rule in <code>deps</code>? Because it is a no-op.
</p>
</li>
<li id="java_binary.srcs"><code>srcs</code>:
The list of source files that are processed to create the target.
<i>(List of <a href="build-ref.html#labels">labels</a>; required excepting
special cases described below)</i>
<p><code>srcs</code> files of type <code>.java</code> are compiled.
<em>For readability's sake</em>, it is not good to put the name of a
generated <code>.java</code> source file into the <code>srcs</code>.
Instead, put the depended-on rule name in the <code>srcs</code>, as
described below.
</p>
<p><code>srcs</code> files of type <code>.srcjar</code> are unpacked and
compiled. (This is useful if you need to generate a set of .java files with
a genrule or build extension.)
</p>
<p><code>srcs</code> files of type <code>.jar</code> are linked in.
(This is useful if you have third-party <code>.jar</code> files
with no source.)
</p>
<p><code>srcs</code> files of type <code>.properties</code> are treated as
resources.</p>
<p style="margin-bottom:0.25em; ">
This argument is required, excepting special cases:</p>
<ul>
<li style="margin-bottom: 0.25em; ">
a <a href="#java_binary.main_class"><code>main_class</code></a>
attribute specifies a class on the runtime classpath; or</li>
<li style="margin-bottom: 1.0em; ">
you specify the <code>use_testrunner</code> argument</li>
</ul>
</li>
<li id="java_binary.resources"><code>resources</code>:
A list of data files to include in a Java jar.
<i>(List of <a href="build-ref.html#labels">labels</a>; optional)</i><br/>
If resources are specified, they will be bundled in the jar along with
the usual <code>.class</code> files produced by compilation. All
resources will be
placed in the jar in a directory corresponding to the build package
name, regardless of their original location on the filesystem. Resources
may be source files or derived files.
</li>
<li id="java_binary.classpath_resources"><code>classpath_resources</code>:
<i>(optional)</i>
A list of resources that must be located at the root of the java
tree. This was introduced because some third party libraries required
that their resources be found on the classpath as exactly "myconfig.xml".
It is only allowed on binaries and not libraries, due to the danger of
namespace conflicts.
</li>
<li id="java_binary.create_executable"><code>create_executable</code>:
Whether to build the executable wrapper script or not.
<i>(Boolean; optional; default is 1)</i><br/>
If this option is present, no executable wrapper script is built
around the .jar file. Incompatible with <code>main_class</code>
attribute.
</li>
<li id="java_binary.deploy_env"><code>deploy_env</code>:
A list of other <code>java_binary</code> targets which represent the deployment
environment for this binary. Set this attribute when building a plugin
which will be loaded by another <code>java_binary</code>.<br />
Setting this attribute excludes all dependencies from the runtime classpath
(and the deploy jar) of this binary that are shared between this binary and
the targets specified in <code>deploy_env</code>.
</li>
<li id="java_binary.deploy_manifest_lines"><code>deploy_manifest_lines</code>:
A list of lines to add to the meta-inf/manifest.mf file generated for the
<code>*_deploy.jar</code> target. The
contents of <code>deploy_manifest_lines</code> are not subject to
<a href="#make_variables">"Make variable"</a> substitution.
</li>
<li id="java_binary.javacopts"><code>javacopts</code>:
Extra compiler options for this library.
<i>(List of strings; optional; subject to
<a href="#make_variables">"Make variable"</a> substitution and
<a href="#sh-tokenization">Bourne shell tokenization</a>)</i>
<p>
These compiler options are passed to javac after the global compiler
options.</p>
</li>
<li id="java_binary.jvm_flags"><code>jvm_flags</code>:
A list of flags to
embed in the wrapper script generated for running this binary.
<i>(List of strings; optional; subject to
<a href="#make_variables">"Make variable"</a> substitution and
<a href="#sh-tokenization">Bourne shell tokenization</a>)</i><br/>
The wrapper script for a Java binary includes a CLASSPATH definition
(to find all the dependent jars) and invokes the right Java interpreter.
The command line generated by the wrapper script includes the name of
the main class followed by a <code>"$@"</code> so you can pass along other
arguments after the classname. However, arguments intended for parsing
by the JVM must be specified <i>before</i> the classname on the command
line. The contents of <code>jvm_flags</code> are added to the wrapper
script before the classname is listed.
</li>
<li id="java_binary.launcher"><code>launcher</code>:
<i>(Label; optional; default is empty.)</i><br/>
If specified, the target will be used to launch the Java Virtual Machine in
the wrapper shell script. The target must be a <code>cc_binary</code>.
Any <code>cc_binary</code> that implements the Java Invocation AP can be a launcher
target.
<p>The related <a href="bazel-user-manual.html#flag--java_launcher"><code>
--java_launcher</code></a> bazel flag affects only those
<code>java_binary</code> and <code>java_test</code> targets that have
<i>not</i> specified a <code>launcher</code> attribute.
<p>If you build a deploy jar and specify a launcher target through either
this <code>launcher</code> attribute or <code>--java_launcher</code> Bazel
flag, then the deploy jar will be a single file that is both (a) a .jar
file that contains the appropriate classes, and (b) the executable
specified by the launcher target.</p>
</li>
<li id="java_binary.main_class"><code>main_class</code>:
Name of class with <code>main()</code> method to use as entry point.
<i>(String)</i> <br/>
If a rule uses this option, it does not need a <code>srcs=[...]</code>
list.
Thus, with this attribute one can make an executable from a Java library
that already contains one or more <code>main()</code> methods.
The value of the
<code>main_class</code> attribute is a class name, not a source file.
The class must be available at runtime: it may be compiled by this rule
(from <code>srcs</code>) or provided by direct or transitive dependencies
(through <code>runtime_deps</code> or <code>deps</code>). If the class is
unavailable, the binary will fail at runtime; there is no build-time check.
</li>
<li id="java_binary.plugins"><code>plugins</code>:
Java compiler plugins to run at compile-time.
<i>(List of <a href="build-ref.html#labels">labels</a>;
optional)</i><br/> Every <code>java_plugin</code> specified in
the plugins attribute will be run whenever
this <code>java_library</code> is built. A library may also inherit
plugins from dependencies that use
<code><a href="#java_library.exported_plugins">exported_plugins</a></code>.
Resources generated by the plugin will be included in the result jar of
the <code>java_library</code>.
</li>
<li id="java_binary.runtime_deps"><code>runtime_deps</code>:
Libraries to make available to the final binary or test at runtime only.
<i>(List of <a href="build-ref.html#labels">labels</a>; optional)</i><br/>
Like ordinary <code>deps</code>, these will appear on the runtime
classpath, but unlike them, not on the compile-time classpath.
Dependencies needed only at runtime should be here because
dependency-management tools may remove deps not needed at compile time.
Dependency-management tools should ignore targets that appear in both
<code>runtime_deps</code> and <code>deps</code>.
</li>
<li id="java_binary.stamp"><code>stamp</code>:
Enable link stamping.
<i>(Integer; optional; default is -1)</i><br/>
Whether to encode build information into the binary. Possible values:
<ul>
<li><code>stamp = 1</code>: Stamp the build information into the
binary. Stamped binaries are only rebuilt when their dependencies
change. Use this if there are tests that depend on the build
information.</li>
<li><code>stamp = 0</code>: Always replace build information by constant
values. This gives good build result caching.</li>
<li><code>stamp = -1</code>: Embedding of build information is controlled
by the <a href="bazel-user-manual.html#flag--stamp">--[no]stamp</a> Bazel
flag.</li>
</ul>
</li>
<li id="java_binary.swigdeps"><code>swigdeps</code>:
<i>(Boolean; optional; default 1)</i><br/>
If 0, do not build and add a swigdeps.so file into the binary, even if
there are cc or swig targets in the transitive closure.
Useful if native code is loaded via a different mechanism for this binary,
such as native methods linked into a cc_binary.
</li>
<li id="java_binary.use_testrunner"><code>use_testrunner</code>:
Use the
You can use this to override the default
behavior. It is unlikely
you will want to do this. One use is for <code>AllTest</code>
rules that are invoked by another rule (to set up a database
before running the tests, for example). The <code>AllTest</code>
rule must be declared as a <code>java_binary</code>, but should
still use the test runner as its main entry point.
</li>
</ul>
<h3 id="sh_binary">sh_binary</h3>
<p class="rule-signature">
sh_binary(<a href="#sh_binary.name">name</a>,
<a href="#sh_binary.deps">deps</a>,
<a href="#sh_binary.srcs">srcs</a>,
<a href="#common.data">data</a>,
<a href="#binary.args">args</a>,
<a href="#sh_binary.bash_version">bash_version</a>,
<a href="#common.deprecation">deprecation</a>,
<a href="#common.distribs">distribs</a>,
<a href="#common.licenses">licenses</a>,
<a href="#common.obsolete">obsolete</a>,
<a href="#binary.output_licenses">output_licenses</a>,
<a href="#sh_binary.random_tmpdir">random_tmpdir</a>,
<a href="#common.tags">tags</a>,
<a href="#common.testonly">testonly</a>,
<a href="#common.visibility">visibility</a>)
</p>
<p>
The <code>sh_binary</code> rule is used to declare executable
programs in interpreted languages such as the Bourne shell, or Bash,
Perl, Ruby, etc. (<code>sh_binary</code> is a double misnomer: its
outputs aren't necessarily either shell programs or binary.) This
rule ensures that all dependencies are built, and appear in
the <code>runfiles</code> area at execution time. We recommend that you name
your <code>sh_binary()</code> rules after the name of the script
minus the extension (e.g. <code>.sh</code>); do not give the rule
and the file the same name.
</p>
<h4 id="sh_binary_implicit_outputs">Implicit output targets</h4>
<ul>
<li><code><var>name</var>.sar</code>: A self-contained binary (i.e. one that
packages all its dependencies).
</li>
</ul>
<h4 id="sh_binary">Arguments</h4>
<ul>
<li id="sh_binary.name"><code>name</code>: A unique name for this rule. <i>(<a href="build-ref.html#name">Name</a>; required)</i> <br/>If your main script is called <code>foo.sh</code>, we recommend
that you name the rule <code>foo</code>, but this is not required.
</li>
<li id="sh_binary.deps"><code>deps</code>:
The list of other "library" targets to be aggregated in to this executable program.
<i>(List of <a href="build-ref.html#labels">labels</a>; optional)</i><br/>
See general comments about <code>deps</code>
at <a href="#common-attributes">Attributes common to all build rules</a>.
You should use this attribute to list other
<code>sh_library</code> rules that provide
interpreted program source code depended on by the code in
<code>srcs</code>.
</li>
<li id="sh_binary.srcs"><code>srcs</code>:
The shell script.
<i>(A list of <a href="build-ref.html#labels">labels</a> of length 1; required)</i><br/>
This attribute must be a singleton list, whose element is the
shell script (or other script). This script must be executable,
and may be a source file or a generated file. All other files
required at runtime (whether scripts or data) belong in the
<code>data</code> attribute.
<!-- TODO: allow multiple srcs. Guess the main one based on the
rule name (quite tricky). -->
</li>
<li id="sh_binary.bash_version"><code>bash_version</code>:
The version of bash to package with this target's .sar file.
<i>(String; optional; default is "system")</i><br/>
Valid values are: <code>"3"</code>, <code>"4"</code>, and
<code>"system"</code>. The first embeds bash 3. The second embeds
bash 4. The third doesn't embed anything, so the script runs with
whatever version is installed on the executing system.
</li>
<li id="sh_binary.random_tmpdir"><code>random_tmpdir</code>:
Whether or not to extract .sar contents to a randomly chosen temp directory.
<i>(Boolean; optional; default is 1)</i><br/>
If <code>0</code>, the directory's name is computed from a hash of the
.sar file contents. This saves the need to redo extraction each time
the .sar is run, making startup time potentially much shorter. However,
it also increases the risk of failure due to the system removing files
from the temp dir.
</li>
</ul>
<h4 id="sh_binary_examples">Example</h4>
<p>For a simple shell script with no dependencies or data:
</p>
<pre class="code">
sh_binary(
name = "foo",
srcs = ["foo.sh"],
)
</pre>
<!-- ============================================
library
============================================
-->
<h2 id="library">*_library</h2>
<p>A <code>*_library()</code> rule compiles some sources into a library.
In general, a <code><var>language</var>_library</code> rule works like
the corresponding <code><var>language</var>_binary</code> rule, but
doesn't generate something executable.</p>
<h3 id="android_library">android_library</h3>
<p class="rule-signature">
android_library(<a href="#android_library.name">name</a>,
<a href="#android_library.deps">deps</a>,
<a href="#android_library.srcs">srcs</a>,
<a href="#common.data">data</a>,
<a href="#android_library.resources">resources</a>,
<a href="#common.deprecation">deprecation</a>,
<a href="#common.distribs">distribs</a>,
<a href="#android_library.idl_import_root">idl_import_root</a>,
<a href="#android_library.idl_parcelables">idl_parcelables</a>,
<a href="#android_library.idl_srcs">idl_srcs</a>,
<a href="#common.licenses">licenses</a>,
<a href="#android_library.neverlink">neverlink</a>,
<a href="#common.obsolete">obsolete</a>,
<a href="#android_library.plugins">plugins</a>,
<a href="#android_library.proguard_specs">proguard_specs</a>,
<a href="#android_library.strict_android_deps">strict_android_deps</a>,
<a href="#common.tags">tags</a>,
<a href="#common.testonly">testonly</a>,
<a href="#common.visibility">visibility</a>)
</p>
<p>This rule compiles and archives its sources into a <code>.jar</code> file.
The Android runtime library <code>android.jar</code> is implicitly put on
the compilation class path.
</p>
<h4 id="android_library_implicit_outputs">Implicit output targets</h4>
<ul>
<li><code>lib<var>name</var>.jar</code>: A Java archive.</li>
<li><code>lib<var>name</var>-src.jar</code>: An archive containing the
sources ("source jar").</li>
</ul>
<h4 id="android_library">Arguments</h4>
<ul>
<li id="android_library.name"><code>name</code>: A unique name for this rule. <i>(<a href="build-ref.html#name">Name</a>; required)</i></li>
<li id="android_library.deps"><code>deps</code>:
The list of other libraries to link against.
<i>(List of <a href="build-ref.html#labels">labels</a>; optional)</i><br/>
Permitted library types are: <code>android_library</code>,
<code>java_library</code> with <code>android</code> constraint and
<code>cc_library</code> wrapping or producing <code>.so</code> native libraries
for the Android target platform.
</li>
<li id="android_library.srcs"><code>srcs</code>:
The list of source files that are processed to create the target.
<i>(List of <a href="build-ref.html#labels">labels</a>; optional)</i>
<p><code>srcs</code> files of type <code>.java</code> are compiled.
<em>For readability's sake</em>, it is not good to put the name of a
generated <code>.java</code> source file into the <code>srcs</code>.
Instead, put the depended-on rule name in the <code>srcs</code>, as
described below.
</p>
<p><code>srcs</code> files of type <code>.srcjar</code> are unpacked and
compiled. (This is useful if you need to generate a set of .java files with
a genrule or build extension.)
</p>
<p>This rule currently forces source and class compatibility with Java 6.
</p>
<p><code>srcs</code> files of type <code>.jar</code> are linked in.
(This is useful if you have third-party <code>.jar</code> files
with no source.)
</p>
</li>
<li id="android_library.resources"><code>resources</code>:
The <code>android_resources</code> target assigned to this library.
<i>(<a href="build-ref.html#labels">Label</a>; optional)</i><br/>
If specified, the resources will be added to any <code>android_binary</code>
depending on this library.
<p>Only an <code>android_resource</code> rule with the attribute
<code>inline_constants</code> set to 0 can be used in this case.</p>
</li>
<li id="android_library.idl_import_root"><code>idl_import_root</code>:
Package-relative path to the root of the java package tree containing idl
sources included in this library.
<i>(String; optional)</i><br/>
This path will be used as the import root when processing idl sources that
depend on this library. If the import is part of the normal java
package structure, this attribute is unnecessary. (See
<a href="#android_library_examples.idl_import_root">examples</a>.)
</li>
<li id="android_library.idl_parcelables"><code>idl_parcelables</code>:
List of Android IDL definitions to supply as imports.
<i>(List of <a href="build-ref.html#labels">labels</a>; optional)</i><br/>
These files will be made available as imports for any
<code>android_library</code> target that depends on this library, directly
or via its transitive closure, but will not be translated to Java
or compiled.
<p>Only <code>.aidl</code> files that correspond directly to
<code>.java</code> sources in this library should be included (e.g., custom
implementations of Parcelable), otherwise <code>idl_srcs</code> should be
used.</p>
</li>
<li id="android_library.idl_srcs"><code>idl_srcs</code>:
List of Android IDL definitions to translate to Java interfaces.
<i>(List of <a href="build-ref.html#labels">labels</a>; optional)</i><br/>
After the Java interfaces are generated, they will be compiled together
with the contents of <code>srcs</code>.
<p>These files will be made available as imports for any
<code>android_library</code> target that depends on this library, directly
or via its transitive closure.</p>
</li>
<li id="android_library.neverlink"><code>neverlink</code>:
Only use this library for compilation and not at runtime.
<i>(Boolean; optional; default is 0)</i><br/>
The outputs of a rule marked as <code>neverlink</code> will not be used in
<code>.apk</code> creation. Useful if the library will be provided by the
runtime environment during execution.
</li>
<li id="android_library.plugins"><code>plugins</code>:
Java compiler plugins to run at compile-time.
<i>(List of <a href="build-ref.html#labels">labels</a>;
optional)</i><br/> Every <code>java_plugin</code> specified in
the plugins attribute will be run whenever
this <code>android_library</code> is built. Resources generated by
the plugin will be included in the result jar of
the <code>android_library</code>.
</li>
<li id="android_library.proguard_specs"><code>proguard_specs</code>:
Files to be used as Proguard specification.
<i>(List of <a href="build-ref.html#labels">labels</a>; optional)</i><br/>
These will describe the set of specifications to be used by Proguard. If specified,
they will be added to any <code>android_binary</code> target depending on this library.
The files included here must only have idempotent rules, namely -dontnote, -dontwarn,
assumenosideeffects, and rules that start with -keep. Other options can only appear in
<code>android_binary</code>'s proguard_specs, to ensure non-tautological merges.
</li>
<li id="android_library.strict_android_deps"><code>strict_android_deps</code>:
<i>(Integer; optional; default is -1 (inherited))</i><br/>
<p>When set to 1, javac will perform checks when compiling the java sources in
this library to verify that all explicitly mentioned classes were loaded from
directly specified <code>deps</code> (rather than from the transitive closure
of all <code>deps</code>). Set to 0 to mark target non-compliant in preparation
for future modification of default behavior, when 1 will become the default.
</p>
</li>
</ul>
<h3 id="java_import">java_import</h3>
<p class="rule-signature">
java_import(<a href="#java_import.name">name</a>,
<a href="#common.data">data</a>,
<a href="#java_import.constraints">constraints</a>,
<a href="#common.deprecation">deprecation</a>,
<a href="#common.distribs">distribs</a>,
<a href="#java_import.exports">exports</a>,
<a href="#java_import.jars">jars</a>,
<a href="#common.licenses">licenses</a>,
<a href="#java_import.neverlink">neverlink</a>,
<a href="#common.obsolete">obsolete</a>,
<a href="#java_import.srcjar">srcjar</a>,
<a href="#common.tags">tags</a>,
<a href="#common.testonly">testonly</a>,
<a href="#common.visibility">visibility</a>)
</p>
<p>This rule allows the use of precompiled JAR files as libraries for
<code><a href="#java_library">java_library</a></code> rules.</p>
<h4 id="java_import">Arguments</h4>
<ul>
<li id="java_import.name"><code>name</code>: A unique name for this rule. <i>(<a href="build-ref.html#name">Name</a>; required)</i></li>
<li id="java_import.constraints"><code>constraints</code>:
Extra constraints imposed on this rule as a Java library.
<i>(List of strings; optional)</i><br />
See <a href="#java_library.constraints">java_library.constraints</a>.
</li>
<li id="java_import.exports"><code>exports</code>:
Targets to make available to users of this rule.
<i>(List of <a href="build-ref.html#labels">labels</a>; optional)</i><br/>
See <a href="#java_library.exports">java_library.exports</a>.
</li>
<li id="java_import.jars"><code>jars</code>:
The list of JAR files provided to Java targets that depend on this target.
<i>(List of <a href="build-ref.html#labels">labels</a>; required)</i>
</li>
<li id="java_import.neverlink"><code>neverlink</code>:
Only use this library for compilation and not at runtime.
<i>(Boolean; optional; default is 0)</i><br/>
Useful if the library will be provided by the runtime environment
during execution. Examples of libraries like this are the IDE APIs
for IDE plug-ins or <code>tools.jar</code> for anything running on
a standard JDK.
</li>
<li id="java_import.srcjar"><code>srcjar</code>:
A JAR file that contains source code for the compiled JAR files.
<i>(<a href="build-ref.html#labels">Label</a>; optional)</i>
</li>
</ul>
<h3 id="java_library">java_library</h3>
<p class="rule-signature">
java_library(<a href="#java_library.name">name</a>,
<a href="#java_library.deps">deps</a>,
<a href="#java_library.srcs">srcs</a>,
<a href="#java_library.data">data</a>,
<a href="#java_binary.resources">resources</a>,
<a href="#java_library.constraints">constraints</a>,
<a href="#common.deprecation">deprecation</a>,
<a href="#common.distribs">distribs</a>,
<a href="#java_library.exported_plugins">exported_plugins</a>,
<a href="#java_library.exports">exports</a>,
<a href="#java_binary.javacopts">javacopts</a>,
<a href="#common.licenses">licenses</a>,
<a href="#java_library.neverlink">neverlink</a>,
<a href="#common.obsolete">obsolete</a>,
<a href="#java_binary.plugins">plugins</a>,
<a href="#java_binary.runtime_deps">runtime_deps</a>,
<a href="#common.tags">tags</a>,
<a href="#common.testonly">testonly</a>,
<a href="#common.visibility">visibility</a>)
</p>
<p>This rule compiles and links sources into a <code>.jar</code> file.
</p>
<h4 id="java_library_implicit_outputs">Implicit output targets</h4>
<ul>
<li><code>lib<var>name</var>.jar</code>: A Java archive containing the class files.</li>
<li><code>lib<var>name</var>-src.jar</code>: An archive containing the sources ("source jar").</li>
</ul>
<h4 id="java_library">Arguments</h4>
<ul>
<li id="java_library.name"><code>name</code>: A unique name for this rule. <i>(<a href="build-ref.html#name">Name</a>; required)</i></li>
<li id="java_library.deps"><code>deps</code>:
The list of libraries to link into this library.
<i>(List of <a href="build-ref.html#labels">labels</a>; optional)</i><br/>
See general comments about <code>deps</code>
at <a href="#common-attributes">Attributes common to all build rules</a>.
<p>For other <code>java_library</code> rules listed in <code>deps</code>,
the jars they build will be on the compile-time classpath for this rule;
also, the transitive closure of their <code>deps</code>,
<code>runtime_deps</code>, and <code>exports</code> will be on the runtime
classpath.</p>
<p>By contrast, targets in the <code>data</code> attribute are included
in the runfiles but on neither the compile-time nor runtime classpath.</p>
</li>
<li id="java_library.srcs"><code>srcs</code>:
The list of source files that are processed to create the library target.
<i>(List of <a href="build-ref.html#labels">labels</a>; optional)</i>
<p><code>srcs</code> files of type <code>.java</code> are compiled.
<em>For readability's sake</em>, it is not good to put the name of a
generated <code>.java</code> source file into the <code>srcs</code>.
Instead, put the depended-on rule name in the <code>srcs</code>, as
described below.
</p>
<p><code>srcs</code> files of type <code>.srcjar</code> are unpacked and
compiled. (This is useful if you need to generate a set of .java files with
a genrule or build extension.)
</p>
<p><code>srcs</code> files of type <code>.jar</code> are linked in.
(This is useful if you have third-party <code>.jar</code> files
with no source.)
</p>
<p><code>srcs</code> files of type <code>.properties</code> are treated as
resources.</p>
</li>
<li id="java_library.data"><code>data</code>:
The list of files needed by this library at runtime.
<i>(List of <a href="build-ref.html#labels">labels</a>; optional)</i><br/>
See general comments about <code>data</code>
at <a href="#common-attributes">Attributes common to all build rules</a>.
<p>When building a <code>java_library</code>, the build tool
doesn't put these files anywhere; if the <code>data</code> files are
generated files, the build tool generates them.
When building a test that depends upon this <code>java_library</code>,
the build tool copies or links the <code>data</code> files into the
runfiles area.
</p>
</li>
<li id="java_library.constraints"><code>constraints</code>:
Extra constraints imposed on this library.
<i>(List of strings; optional)</i>
<p>
At the moment, the following constraints are supported:
</p>
<ul>
<li><code>android</code>: Specifies that this java_library is
Android-compatible. This means that the java_library does not
use Java APIs not supported by Android. If a java_library is
Android-compatible, the build tool will check that all dependent
java_libraries are marked as Android-compatible.
If an Android-compatible library depends on a java_library that is
not Android-compatible an error will be generated.
</li>
<li><code>public</code>: Specifies that this java_library only
includes source code and resources that can be made public.
</li>
</ul>
</li>
<li id="java_library.exported_plugins"><code>exported_plugins</code>:
The list of <code><a href="#java_plugin">java_plugin</a></code>s
(e.g. annotation processors) to export to libraries that directly depend
on this library.
<i>(List of <a href="build-ref.html#labels">labels</a>; optional)</i><br />
<p>The specified list of <code>java_plugin</code>s will be applied to any
library which directly depends on this library, just as if that library had
explicitly declared these labels in
<code><a href="#java_library.plugins">plugins</a></code>.
</li>
<li id="java_library.exports"><code>exports</code>:
The closure of all rules reached via <code>exports</code> attributes are
considered direct dependencies of any rule that directly depends on the
target with <code>exports</code>.
<p><code>exports</code> are not direct deps of the rule they belong to.</p>
</li>
<li id="java_library.neverlink"><code>neverlink</code>:
Only use this library for compilation and not at runtime.
<i>(Boolean; optional; default is 0)</i><br/>
Useful if the library will be provided by the runtime environment during
execution. Examples of libraries like this are the IDE APIs for IDE
plug-ins or <code>tools.jar</code> for anything running on a standard JDK.
Note that <code>neverlink = 1</code> does not prevent the compiler from
inlining material from this library into compilation targets that depend on
it, as permitted by the Java Language Specification (e.g., <code>static
final</code> constants of <code>String</code> or primitive type). The
preferred use case is therefore when the runtime library is identical to
the compilation library. If the runtime library differs from the
compilation library, then you must ensure that it differs only in places
that the JLS forbids compilers from inlining (and that must hold for all
future versions of the JLS).
</li>
</ul>
<h3 id="sh_library">sh_library</h3>
<p class="rule-signature">
sh_library(<a href="#sh_library.name">name</a>,
<a href="#sh_library.deps">deps</a>,
<a href="#sh_library.srcs">srcs</a>,
<a href="#common.data">data</a>,
<a href="#common.deprecation">deprecation</a>,
<a href="#common.distribs">distribs</a>,
<a href="#common.licenses">licenses</a>,
<a href="#common.obsolete">obsolete</a>,
<a href="#common.tags">tags</a>,
<a href="#common.testonly">testonly</a>,
<a href="#common.visibility">visibility</a>)
</p>
<p>
The main use for this rule is to aggregate together a logical
"library" consisting of related scripts&mdash;programs in an
interpreted language that does not require compilation or linking,
such as the Bourne shell&mdash;and any data those programs need at
run-time. Such "libraries" can then be used from
the <code>data</code> attribute of one or
more <code>sh_binary</code> rules.
</p>
<p>
Historically, a second use was to aggregate a collection of data files
together, to ensure that they are available at runtime in
the <code>.runfiles</code> area of one or more <code>*_binary</code>
rules (not necessarily <code>sh_binary</code>).
However, the <a href="#filegroup"><code>filegroup()</code></a> rule
should be used now; it is intended to replace this use of
<code>sh_library</code>.
</p>
<p>
In interpreted programming languages, there's not always a clear
distinction between "code" and "data": after all, the program is
just "data" from the interpreter's point of view. For this reason
(and historical accident) this rule has three attributes which are
all essentially equivalent: <code>srcs</code>, <code>deps</code>
and <code>data</code>.
The recommended usage of each attribute is mentioned below. The
current implementation does not distinguish the elements of these lists.
All three attributes accept rules, source files and derived files.
</p>
<h4 id="sh_library">Arguments</h4>
<ul>
<li id="sh_library.name"><code>name</code>: A unique name for this rule. <i>(<a href="build-ref.html#name">Name</a>; required)</i></li>
<li id="sh_library.deps"><code>deps</code>:
The list of other targets to be aggregated in to this "library" target.
<i>(List of <a href="build-ref.html#labels">labels</a>; optional)</i><br/>
See general comments about <code>deps</code>
at <a href="#common-attributes">Attributes common to all build rules</a>.
You should use this attribute to list other
<code>sh_library</code> rules that provide
interpreted program source code depended on by the code in
<code>srcs</code>.
</li>
<li id="sh_library.srcs"><code>srcs</code>:
The list of input files.
<i>(List of <a href="build-ref.html#labels">labels</a>,
optional)</i><br/>
You should use this attribute to list interpreted program
source files that belong to this package, such as additional
files containing Bourne shell subroutines, loaded via the shell's
<code>source</code> or <code>.</code> command.
</li>
</ul>
<h4 id="sh_library_examples">Examples</h4>
<pre class="code">
sh_library(
name = "aggregator",
data = [
":aggregator_service_script", # a sh_binary with srcs
":deploy_aggregator", # another sh_binary with srcs
],
)
</pre>
<!-- ============================================
test
============================================
-->
<h2 id="test">*_test</h2>
<p>A <code>*_test</code> rule compiles a
test. See <a href="#common-attributes-tests">Common attributes for
tests</a> for an explanation of the common attributes.
<h3 id="android_test">android_test</h3>
<p class="rule-signature">
android_test(<a href="#android_test.name">name</a>,
<a href="#android_test.deps">deps</a>,
<a href="#android_binary.srcs">srcs</a>,
<a href="#android_test.data">data</a>,
<a href="#android_binary.resources">resources</a>,
<a href="#test.args">args</a>,
<a href="#android_binary.debug_key">debug_key</a>,
<a href="#common.deprecation">deprecation</a>,
<a href="#android_binary.dexopts">dexopts</a>,
<a href="#common.distribs">distribs</a>,
<a href="#test.flaky">flaky</a>,
<a href="#common.licenses">licenses</a>,
<a href="#test.local">local</a>,
<a href="#common.obsolete">obsolete</a>,
<a href="#android_binary.proguard_generate_mapping">proguard_generate_mapping</a>,
<a href="#android_test.proguard_specs">proguard_specs</a>,
<a href="#test.shard_count">shard_count</a>,
<a href="#test.size">size</a>,
<a href="#android_binary.strict_android_deps">strict_android_deps</a>,
<a href="#common.tags">tags</a>,
<a href="#android_test.target_devices">target_devices</a>,
<a href="#common.testonly">testonly</a>,
<a href="#test.timeout">timeout</a>,
<a href="#common.visibility">visibility</a>)
</p>
<p>
A <code>android_test</code> rule runs Android tests. By default, it will
start an emulator, install the application under test along with the test
binary and any other needed Android binaries and run the tests defined in the
test package. An option to run the test on an existing device is available
to <code>target_devices</code> users when running locally.
</p>
<p>
These tests require an Android device (virtual or physical) to run because
they rely on Android libraries only available on the device.
</p>
<h4 id="android_test">Arguments</h4>
<ul>
<li id="android_test.name"><code>name</code>: A unique name for this rule. <i>(<a href="build-ref.html#name">Name</a>; required)</i></li>
<li id="android_test.deps"><code>deps</code>:
The list of other libraries and binaries to be linked in to the test
target. <i>(List of <a href="build-ref.html#labels">labels</a>; optional)
</i>
<p>Permitted library types are: <code>android_library</code>,
<code>java_library</code> or <code>java_import</code>
with <code>android</code> constraint, and
<code>cc_library</code> wrapping or producing <code>.so</code> native
libraries for the Android target platform.</p>
<p><code>deps</code> of type <code>android_binary</code> are installed in
the emulator before running the tests, and the first in the list is
considered to be the proper application under test.
</p>
</li>
<li id="android_test.data"><code>data</code>:
A collection of artifacts to be pushed onto the device's external storage
before the test is executed.
<p><i>This option is only available when using <code>target_devices</code>
attribute.</i></p>
</li>
<li id="android_test.proguard_specs"><code>proguard_specs</code>:
Files to be used as Proguard specification.
<i>(List of <a href="build-ref.html#labels">labels</a>; optional)</i><br/>
This file will describe the set of specifications to be used by Proguard.
</p>
</li>
<li id="android_test.target_devices"><code>target_devices</code>:
The <a href="#android_device">android_device</a> the test should run against.
<i>(<a href="build-ref.html#labels">Label</a>: required)</i>
<p>At this time only one <a href="#android_device">android_device</a>
is allowed in the <code>target_devices</code> attribute.</p>
</li>
</ul>
<h3 id="java_test">java_test</h3>
<p class="rule-signature">
java_test(<a href="#java_test.name">name</a>,
<a href="#java_binary.deps">deps</a>,
<a href="#java_binary.srcs">srcs</a>,
<a href="#common.data">data</a>,
<a href="#java_binary.resources">resources</a>,
<a href="#test.args">args</a>,
<a href="#java_binary.classpath_resources">classpath_resources</a>,
<a href="#java_binary.create_executable">create_executable</a>,
<a href="#java_binary.deploy_manifest_lines">deploy_manifest_lines</a>,
<a href="#common.deprecation">deprecation</a>,
<a href="#common.distribs">distribs</a>,
<a href="#test.flaky">flaky</a>,
<a href="#java_binary.javacopts">javacopts</a>,
<a href="#java_binary.jvm_flags">jvm_flags</a>,
<a href="#java_binary.launcher">launcher</a>,
<a href="#common.licenses">licenses</a>,
<a href="#test.local">local</a>,
<a href="#java_binary.main_class">main_class</a>,
<a href="#common.obsolete">obsolete</a>,
<a href="#java_binary.plugins">plugins</a>,
<a href="#java_binary.runtime_deps">runtime_deps</a>,
<a href="#test.shard_count">shard_count</a>,
<a href="#test.size">size</a>,
<a href="#java_binary.stamp">stamp</a>,
<a href="#java_binary.swigdeps">swigdeps</a>,
<a href="#common.tags">tags</a>,
<a href="#java_test.test_class">test_class</a>,
<a href="#common.testonly">testonly</a>,
<a href="#test.timeout">timeout</a>,
<a href="#java_binary.use_testrunner">use_testrunner</a>,
<a href="#common.visibility">visibility</a>)
</p>
<p>
A <code>java_test()</code> rule compiles a Java test.
A test is binary wrapper around your test code.
The test runner's main method is invoked instead of
the main class being compiled.</p>
<h4 id="java_test_implicit_outputs">Implicit output targets</h4>
<ul>
<li><code><var>name</var>.jar</code>: A Java archive.</li>
<li><code><var>name</var>_deploy.jar</code>: A Java archive suitable
for deployment. (Only built if explicitly requested.)</li>
</ul>
<h4 id="java_test">Arguments</h4>
<ul>
<li id="java_test.name"><code>name</code>: A unique name for this rule. <i>(<a href="build-ref.html#name">Name</a>; required)</i></li>
<li id="java_test.test_class"><code>test_class</code>:
The Java class to be loaded by the test runner.<br/>
<i>(String, the fully qualified name of a Java class; optional)</i><br/>
<p>
This attribute specifies the name of a Java class to be run by
this test. For JUnit3, this class needs to either be a subclass of
<code>junit.framework.TestCase</code> or it needs to have a public
static <code>suite()</code> method that returns a
<code>junit.framework.Test</code> (or a subclass of <code>Test</code>).
For JUnit4, proper
annotations should be used. If this argument is omitted, the Java class
whose name corresponds to the <code>name</code> of this
<code>java_test</code> rule will be used.
</p>
<p>
This attribute allows several <code>java_test</code> rules to
share the same <code>Test</code>
(<code>TestCase</code>, <code>TestSuite</code>, ...). Typically
additional information is passed to it
(e.g. via <code>jvm_flags=['-Dkey=value']</code>) so that its
behavior differs in each case, such as running a different
subset of the tests. This attribute also enables the use of
Java tests outside the <code>javatests</code> tree.
</p>
</li>
</ul>
<p>
See the section on <a href="#java_binary_args">java_binary()</a>
arguments, with the <i>caveats</i> that
there is no <code>main_class</code> argument.
It also supports all <a href="#common-attributes-tests">attributes common to
all test rules (*_test)</a>.
<code>java_test</code> has this extra argument:</p>
<h3 id="sh_test">sh_test</h3>
<p class="rule-signature">
sh_test(<a href="#sh_test.name">name</a>,
<a href="#sh_binary.deps">deps</a>,
<a href="#sh_binary.srcs">srcs</a>,
<a href="#common.data">data</a>,
<a href="#test.args">args</a>,
<a href="#sh_test.bash_version">bash_version</a>,
<a href="#common.deprecation">deprecation</a>,
<a href="#common.distribs">distribs</a>,
<a href="#test.flaky">flaky</a>,
<a href="#common.licenses">licenses</a>,
<a href="#test.local">local</a>,
<a href="#common.obsolete">obsolete</a>,
<a href="#test.shard_count">shard_count</a>,
<a href="#test.size">size</a>,
<a href="#common.tags">tags</a>,
<a href="#common.testonly">testonly</a>,
<a href="#test.timeout">timeout</a>,
<a href="#common.visibility">visibility</a>)
</p>
<p>
A <code>sh_test()</code> rule creates a test. A test is
a wrapper around the tested code. If you're working with Perl and want to
write a unit test, then <code>sh_test()</code> is the best
approach (though Perl is not supported).</p>
<h4 id="sh_test">Arguments</h4>
<ul>
<li id="sh_test.name"><code>name</code>: A unique name for this rule. <i>(<a href="build-ref.html#name">Name</a>; required)</i>
<br/>If your main script is called <code>foo.sh</code>, we recommend
that you name the rule <code>foo</code>, but this is not required.
</li>
<li id="sh_test.bash_version"><code>bash_version</code>:
The version of bash to run this test with.
<i>(String; optional; default is "system")</i><br/>
Valid values are: <code>"3"</code>, <code>"4"</code>, and
<code>"system"</code>. The first runs bash 3. The second runs
bash 4. The third runs with the executing system's default installation.
<p>For a non-system bash, the output executable is a custom test runner
that invokes the source script with the correct bash. For a system bash,
the output executable is just the original source script.</p>
</li>
</ul>
<p>
See the section on <a href="#sh_binary_args">sh_binary()</a> for other
arguments. Also see the <a href="#common-attributes-tests">attributes common to
all test rules (*_test)</a>.</p>
<!-- ============================================
variables
============================================
-->
<h2 id="make_variables">"Make" Variables</h2>
<p>
This section describes how to use or define a special class of string
variables that are called the "Make" environment. Bazel defines a set of
standard "Make" variables, and you can also define your own.
</p>
<p>(The reason for the term "Make" is historical: the syntax and semantics of
these variables are somewhat similar to those of GNU Make, and in the
original implementation, were implemented by GNU Make. The
scare-quotes are present because newer build tools support
"Make" variables without being implemented using GNU Make; therefore
it is important to read the specification below carefully to
understand the differences.)
</p>
<p>To see the list of all common "Make" variables and their values,
run <code>bazel info --show_make_env</code>.
</p>
<p>Build rules can introduce additional rule specific variables. One example is
the <a href="#genrule.cmd"><code>cmd</code> attribute of a genrule</a>.
</p>
<h3 id='make-var-substitution'>"Make" variable substitution</h3>
<p>Variables can be referenced in attributes and other variables using either
<code>$(FOO)</code> or <code>varref('FOO')</code>, where <code>FOO</code> is
the variable name. In the attribute documentation of rules, it is mentioned
when an attribute is subject to "Make" variable substitution. For those
attributes this means that any substrings of the form <code>$(X)</code>
within those attributes will be interpreted as references to the "Make"
variable <var>X</var>, and will be replaced by the appropriate value of that
variable for the applicable build configuration. The parens may be omitted
for variables whose name is a single character.
</p>
<p>
It is an error if such attributes contain embedded strings of the
form <code>$(X)</code> where <var>X</var> is not the name of a
"Make" variable, or unclosed references such as <code>$(</code> not
matched by a corresponding <code>)</code>.
</p>
<p>
Within such attributes, literal dollar signs must be escaped
as <code>$$</code> to prevent this expansion.
</p>
<p>
Those attributes that are subject to this substitution are
explicitly indicated as such in their definitions in this document.
</p>
<h3 id="predefined_variables">Predefined "Make" Variables</h3>
<p>Bazel defines a set of "Make" variables for you.</p>
<p>The build system also provides a consistent PATH for genrules and tests which
need to execute shell commands. For genrules, you can indirect your commands
using the Make variables below. For basic Unix utilities, prefer relying on
the PATH variable to guarantee correct results. For genrules involving
compiler and platform invocation, you must use the Make variable syntax.
The same basic command set is also available during tests. Simply rely on the
PATH.</p>
<p>Bazel uses a tiny Unix distribution to guarantee consistent behavior of
build and test steps which execute shell code across all build execution
hosting environments but it does not enforce a pure chroot. As such, do
<b>not</b> use hard coded paths, such as
<code>/usr/bin/foo</code>. Binaries referenced in hardcoded paths are not
hermetic and can lead to unexpected and non-reproducible build behavior.</p>
<p><strong>Command Variables for genrules</strong></p>
<p>Note that in general, you should simply refer to many common utilities as
bare commands that the $PATH variable will correctly resolve to hermetic
versions for you.</p>
<p><strong>Path Variables</strong></p>
<ul><!-- keep alphabetically sorted -->
<li><code>BINDIR</code>: The base of the generated binary tree for the target
architecture. (Note that a different tree may be used for
programs that run during the build on the host architecture,
to support cross-compiling. If you want to run a tool from
within a genrule, the recommended way of specifying the path to
the tool is to use <code>$(location <i>toolname</i>)</code>,
where <i>toolname</i> must be listed in the <code>tools</code>
attribute for the genrule.</li>
<li><code>GENDIR</code>: The base of the generated code
tree for the target architecture.</li>
<li><code>JAVABASE</code>:
The base directory containing the Java utilities.
It will have a "bin" subdirectory.</li>
</ul>
<p><strong>Architecture Variables</strong></p>
<ul><!-- keep alphabetically sorted -->
<li><code>ABI</code>: The C++ ABI version. </li>
<li><code>ANDROID_CPU</code>: The Android target architecture's cpu. </li>
<li><code>JAVA_CPU</code>: The Java target architecture's cpu. </li>
<li> <code>TARGET_CPU</code>: The target architecture's cpu. </li>
</ul>
<p id="predefined_variables.genrule.cmd">
<strong>
Other Variables available to <a href="#genrule.cmd">the cmd attribute of a genrule</a>
</strong>
</p>
<ul><!-- keep alphabetically sorted -->
<li><code>OUTS</code>: The <code>outs</code> list. If you have only one output
file, you can also use <code>$@</code>.</li>
<li><code>SRCS</code>: The <code>srcs</code> list (or more
precisely, the pathnames of the files corresponding to
labels in the <code>srcs</code> list). If you have only one
source file, you can also use <code>$&lt;</code>.</li>
<li><code>&lt;</code>: <code>srcs</code>, if it is a single file.</li>
<li><code>@</code>: <code>outs</code>, if it is a single file.</li>
<li><code>@D</code>: The output directory. If there is only
one filename in <code>outs</code>, this expands to the
directory containing that file. If there are multiple
filenames, this variable instead expands to the package's root
directory in the <code>genfiles</code> tree, <i>even if all
the generated files belong to the same subdirectory</i>!
<!-- (as a consequence of the "middleman" implementation) -->
If the genrule needs to generate temporary intermediate files
(perhaps as a result of using some other tool like a compiler)
then it should attempt to write the temporary files to
<code>@D</code> (although <code>/tmp</code> will also be
writable), and to remove any such generated temporary files.
Especially, avoid writing to directories containing inputs -
they may be on read-only filesystems. </li>
</ul>
</ul>
<h3 id="define_your_own_make_vars">Defining Your Own Variables</h3>
<p>
You may want to use Python-style variable assignments rather than "Make"
variables, because they work in more use cases and are less surprising. "Make"
variables will work in the <a href="#genrule.cmd">cmd</a> attribute of genrules
and in the key of the <a href="#cc_library.abi_deps">abi_deps</a> attribute of
a limited number of rules, but only in very few other places.
</p>
<p>To define your "Make" own variables, first call <a
href="#vardef">vardef()</a> to define your variable, then call <a
href="#varref">varref(name)</a> to retrieve it. varref can be embedded as part
of a larger string. Custom "Make" variables differ from ordinary "Python"
variables in the BUILD language in two important ways:
</p>
<ul>
<li>Only string values are supported,</li>
<li>The "Make" environment is parameterized over the build
platform, so that variables can be conditionally defined based on
the target architecture, ABI or compiler, and</li>
<li>The values of custom "Make" variables are <i>not available</i> during
BUILD-file evaluation. To work around this, you must call <a
href="#varref">varref()</a> to retrieve the value of a variable (unlike
predefined values, which can be retrieved using <code>$(FOO)</code>.
varref defers evaluation until after BUILD file evaluation.</li>
</ul>
<h4 id="vardef">vardef()</h4>
<p><code>vardef(name, value, platform)</code></p>
<p>
Define a variable for use within this <code>BUILD</code> file only.
This variable can then be used by <a href="#varref">varref()</a>.
The value of the variable can be overridden on the command line by using the
<code class='flag'><a href='bazel-user-manual.html#flag--define'>--define</a></code>
flag.
</p>
<p id="vardef_args"><strong>Arguments</strong></p>
<ul>
<li><code>name</code>: The name of the variable.
<i>(String; required)</i><br/>
Convention is to use names consisting of ALL CAPS. This name must
be a unique identifier in this package.
</li>
<li><code>value</code>: The value to assign to this variable.
<i>(String; required)</i><br/>
The value may make use of variables you know are defined in the "Make"
environment.
</li>
<li><code>platform</code>: Conditionally define this variable for a given
platform.
<i>(String; optional)</i><br/>
<code>vardef</code> binds the <code>name</code> to <code>value</code> if we're
compiling for <code>platform</code>.
</li>
</ul>
<p id="vardef_notes"><strong>Notes</strong></p>
<p>
Because references to "Make" variables are expanded <i>after</i>
BUILD file evaluation, the relative order of <code>vardef</code>
statements and rule declarations is unimportant; it is order of
<code>vardef</code> statements relative to each other, and hence the
state of the "Make" environment at the end of evaluation that
matters.
</p>
<p>
If there are multiple matching <code>vardef</code> definitions for
the same variable, the definition that wins is
the <strong>last</strong> matching definition
<strong>that specifies a platform</strong>, unless there are no matching
definitions that specify a platform, in which case the definition
that wins is the <strong>last</strong> definition <strong>without
a platform</strong>.
</p>
<!-- =================================================================
varref()
=================================================================
-->
<h4 id="varref">varref</h4>
<p><code>varref(name)</code></p>
<p>
<code>varref("FOO")</code> is equivalent of writing "$(FOO)". It is used to
dereference variables defined with <a href="#vardef"><code>vardef</code></a>
as well as <a href="#predefined_variables">predefined variables</a>.
</p>
<p>
In rule attributes that are subject to "Make" variable
substitution, the string produced by <code>varref(<i>name</i>)</code>
will expand to the value of variable <i>name</i>.
</p>
<p><code>varref(name)</code> may not be used in rule attributes that are
not subject to "Make" variable substitution.</p>
<p id="varref_args"><strong>Arguments</strong></p>
<ul>
<li><code>name</code>: The name of the variable to dereference.
</li>
</ul>
<p id="varref_notes"><strong>Notes</strong></p>
<ul>
<li><code>varref</code> can access either local or global variables.
It prefers the local variable, if both a local and a global exist with
the same name.
</li>
</ul>
<p id="varref_examples"><strong>Examples</strong></p>
<p>See <a href="#vardef_examples">vardef()</a> examples.</p>
<!-- ============================================
other
============================================
-->
<h2 id="misc">Other Stuff</h2>
<h3 id="filegroup">filegroup</h3>
<p class="rule-signature">
filegroup(<a href="#filegroup.name">name</a>,
<a href="#filegroup.srcs">srcs</a>,
<a href="#filegroup.data">data</a>,
<a href="#common.deprecation">deprecation</a>,
<a href="#common.distribs">distribs</a>,
<a href="#common.licenses">licenses</a>,
<a href="#common.obsolete">obsolete</a>,
<a href="#binary.output_licenses">output_licenses</a>,
<a href="#filegroup.path">path</a>,
<a href="#common.tags">tags</a>,
<a href="#common.testonly">testonly</a>,
<a href="#common.visibility">visibility</a>)
</p>
<p>Use <code>filegroup</code> to give a convenient name to a
collection of targets. These can then be referenced from other
rules, e.g. the <code>srcs</code> attribute of a genrule, or
the <code>data</code> attribute of a *_binary rule.
</p>
<p>Motivation: this mechanism aims to replace the practice of referencing
directory names as data dependencies. Referencing directory names
is unsound as the build system does not have full knowledge of all
files below the directory, so it may or may not rebuild as these files
change. When combined with <a href="#glob">glob</a>, filegroup can
ensure that all files are explicitly known to the build system.
</p>
<h4 id="filegroup">Arguments</h4>
<ul>
<li id="filegroup.name"><code>name</code>: A unique name for this rule. <i>(<a href="build-ref.html#name">Name</a>; required)</i></li>
<li id="filegroup.srcs"><code>srcs</code>:
The list of targets that are members of the file group.
<i>(List of <a href="build-ref.html#labels">labels</a>; optional)</i>
<p>It is common to use the result of a <a href="#glob">glob</a>
expression for the value of the <code>srcs</code> attribute.
If a glob matches a source file with the same name as a build rule,
the rule will override the file.
</p>
</li>
<li id="filegroup.data"><code>data</code>:
The list of files needed by this rule at runtime.
<i>(List of <a href="build-ref.html#labels">labels</a>; optional)</i><br/>
Targets named in the <code>data</code> attribute will be considered
belonging to the runfiles of the filegroup rule. This means in practice
that when the filegroup is put in the <code>data</code> attribute of a
rule, the files referred to by this attribute will also be considered to be
data of the rule referring to the <code>filegroup</code>. See the
<a href="build-ref.html#data">data dependencies</a> section for more
information about how to depend on and use data files.
</li>
<li id="filegroup.path"><code>path</code>:
An optional string giving a path to the files in the group.
<i>(String; optional)</i><br/>
This attribute is used internally by Bazel to find the name of the
directory holding the files.
</li>
</ul>
<h4 id="filegroup_example">Examples</h4>
<p>
To create a filegroup consisting of two source files, do
</p>
<pre class="code">
filegroup(
name = "mygroup",
srcs = [
"a_file.txt",
"another_file.txt",
],
)
</pre>
<p>Or, use a glob to grovel a testdata directory:</p>
<pre class="code">
filegroup(
name = "exported_testdata",
srcs = glob([
"testdata/*.dat",
"testdata/logs/*.log",
]),
)
</pre>
<p>To make use of these definitions, reference the filegroup with a label
from any rule:</p>
<pre class="code">
cc_library(
name = "my_library",
srcs = ["foo.cc"],
data = [
"//my_package:exported_testdata",
"//my_package:mygroup",
],
)
</pre>
<h3 id="test_suite">test_suite</h3>
<p class="rule-signature">
test_suite(<a href="#test_suite.name">name</a>,
<a href="#common.deprecation">deprecation</a>,
<a href="#common.distribs">distribs</a>,
<a href="#common.licenses">licenses</a>,
<a href="#common.obsolete">obsolete</a>,
<a href="#test_suite.tags">tags</a>,
<a href="#common.testonly">testonly</a>,
<a href="#test_suite.tests">tests</a>,
<a href="#common.visibility">visibility</a>)
</p>
<p>
A <code>test_suite</code> defines a set of tests that are considered
"useful" to humans. This allows projects to define sets of tests,
such as "tests you must run before checkin", "our project's stress
tests" or "all small tests."
</p>
<h4 id="test_suite">Arguments</h4>
<ul>
<li id="test_suite.name"><code>name</code>: A unique name for this rule. <i>(<a href="build-ref.html#name">Name</a>; required)</i></li>
<li id="test_suite.tags"><code>tags</code>:
List of text tags such as "small" or "database" or "-flaky".
Tags may be any valid string.
<p>
Tags which begin with a "-" character are considered negative tags. The
preceding "-" character is not considered part of the tag, so a suite tag
of "-small" matches a test's "small" size. All other tags are considered
positive tags.
</p>
<p>
Optionally, to make positive tags more explicit, tags may also begin with the
"+" character, which will not be evaluated as part of the text of the tag. It
merely makes the positive and negative distinction easier to read.
</p>
<p>
Only test rules that match ALL of the positive tags and NONE of the negative
tags will be included in the test suite. Note that this does not mean that
error checking for dependencies on tests that are filtered out is skipped;
you will still need to ensure that the dependencies on skipped tests are
legal (e.g. not blocked by visibility or obsoleteness constraints)
</p>
<p>
There is one exception to this rule:
a <code>manual</code> tag keyword is used to mark the <code>test_suite</code>
target as "manual" so that will be ignored by the wildcard
expansion and automated testing facilities, not as a filter on the set
of tests in the suite. So when the <code>manual</code> tag is used on a
test_suite, test rules do not have to be tagged as <code>manual</code> to be
included in the test suite. At this point only Bazel has proper support
for the <code>manual</code> tag keyword. Other test runners will apply
it as a filter, in most cases resulting in the empty test suite.
</p>
<p>
Note that a test's <code>size</code> is considered a tag for the
purpose of filtering.
</p>
<p>
To create a suite containing tests with mutually exclusive tags,
e.g. all small and medium tests,
you need to create a <code>test_suite</code> of all small
tests, a <code>test_suite</code> of all medium tests, and then a
<code>test_suite</code> that includes the small and medium
<code>test_suite</code>s.
</p>
</li>
<li id="test_suite.tests"><code>tests</code>:
A list of test suites and test targets of any language.
<p>
You can freely mix languages and rule styles. Thus any
<code>*_test</code> will work, but not an <code>*_binary</code> that
happens to run a test. Filtering by the specified <code>tags</code> will
be applied only to the tests in this attribute, but not to test suites or
tests included from other test suites. The <code>tests</code> and
<code>suites</code> attributes can be used interchangeably.
</p>
<p>
If the <code>tests</code> and the <code>suites</code> parameters are both
unspecified or empty, the rule will default to including all test rules in
the current BUILD file that are not tagged as <code>manual</code> or
marked as <code>obsolete</code>. These rules are still subject to
<code>tag</code> filtering.
</p>
</li>
</ul>
<h3 id="android_device">android_device</h3>
<p class="rule-signature">
android_device(<a href="#android_device.name">name</a>,
<a href="#android_device.cache">cache</a>,
<a href="#android_device.default_properties">default_properties</a>,
<a href="#common.deprecation">deprecation</a>,
<a href="#common.distribs">distribs</a>,
<a href="#android_device.horizontal_resolution">horizontal_resolution</a>,
<a href="#common.licenses">licenses</a>,
<a href="#common.obsolete">obsolete</a>,
<a href="#android_device.ram">ram</a>,
<a href="#android_device.screen_density">screen_density</a>,
<a href="#android_device.system_image">system_image</a>,
<a href="#common.tags">tags</a>,
<a href="#common.testonly">testonly</a>,
<a href="#android_device.vertical_resolution">vertical_resolution</a>,
<a href="#common.visibility">visibility</a>,
<a href="#android_device.vm_heap">vm_heap</a>)
</p>
<p>This rule creates an android emulator configured with the given
specifications. This emulator may be started via a bazel run
command or by executing the generated script directly.
</p>
<h4 id="android_device_implicit_outputs">Implicit output targets</h4>
<ul>
<li><code><var>name</var>_images/userdata.dat</code>:
Contains image files and snapshots to start the emulator</li>
<li><code><var>name</var>_images/emulator-meta-data.pb</code>:
Contains serialized information necessary to pass on to the emulator to
restart it.</li>
</ul>
<h4 id="android_device">Arguments</h4>
<ul>
<li id="android_device.name"><code>name</code>: A unique name for this rule. <i>(<a href="build-ref.html#name">Name</a>; required)</i></li>
<li id="android_device.cache"><code>cache</code>:
The size in megabytes of the emulator's cache partition. The minimum value
of this is 16 megabytes.
</li>
<li id="android_device.default_properties"><code>default_properties</code>:
<code>default_properties</code>
A single properties file to be placed in /default.prop on the emulator. This
allows the rule author to further configure the emulator to appear more like
a real device (In particular controlling its UserAgent strings and other
behaviour that might cause an application or server to behave differently to
a specific device). The properties in this file will override read only
properties typically set by the emulator such as ro.product.model.
</li>
<li id="android_device.horizontal_resolution"><code>horizontal_resolution</code>:
<code>horizontal_resolution</code>:
The horizontal screen resolution in pixels to emulate. The minimum value is 240.
</li>
<li id="android_device.ram"><code>ram</code>:
The amount of ram in megabytes to emulate for the device. This is for the
entire device, not just for a particular app installed on the device. The
minimum value is 64 megabytes.
</li>
<li id="android_device.screen_density"><code>screen_density</code>:
The density of the emulated screen in pixels per inch. The minimum value of
this is 30 ppi.
</li>
<li id="android_device.system_image"><code>system_image</code>:
A filegroup containing the following files:
<ul>
<li>system.img: The system partition.</li>
<li>kernel-qemu: The Linux kernel the emliator will load</li>
<li>ramdisk.img: The initrd image to use at boot time</li>
<li>userdata.img: The initial userdata partition.</li>
<li>source.properties: A properties file containing information about the
images</li>
</ul>
These files are part of the android sdk or provided by third parties (for
example Intel provides x86 images).
</li>
<li id="android_device.vertical_resolution"><code>vertical_resolution</code>:
The vertical screen resolution in pixels to emulate. The minimum value is 240.
</li>
<li id="android_device.vm_heap"><code>vm_heap</code>:
The size in megabytes of the virtual machine heap Android will use for each
process. The minimum value is 16 megabytes.
</li>
</ul>
<h3 id="android_manifest_merge">android_manifest_merge</h3>
<p class="rule-signature">
android_manifest_merge(<a href="#android_manifest_merge.name">name</a>,
<a href="#android_manifest_merge.deps">deps</a>,
<a href="#android_manifest_merge.srcs">srcs</a>,
<a href="#common.deprecation">deprecation</a>,
<a href="#common.distribs">distribs</a>,
<a href="#android_manifest_merge.exclude_permissions">exclude_permissions</a>,
<a href="#common.licenses">licenses</a>,
<a href="#common.obsolete">obsolete</a>,
<a href="#common.tags">tags</a>,
<a href="#common.testonly">testonly</a>,
<a href="#common.visibility">visibility</a>)
</p>
<p>This rule merges an <code>AndroidManifest.xml</code> file with other android
manifests that your app depends on (mergees). Other manifests might come
from android libraries that your project depends on (e.g.: userfeedback
library), or on your test manifest used to produce test version of your app's
binary. Optionally, permissions from the mergees can be excluded.
</p>
<h4 id="android_manifest_merge_implicit_outputs">Implicit output targets</h4>
<ul>
<li><code><var>name</var>/AndroidManifest.xml</code>:
Merged android manifest file.</li>
</ul>
<h4 id="android_manifest_merge">Arguments</h4>
<ul>
<li id="android_manifest_merge.name"><code>name</code>: A unique name for this rule. <i>(<a href="build-ref.html#name">Name</a>; required)</i></li>
<li id="android_manifest_merge.deps"><code>deps</code>:
The list of AndroidManifest.xml files to be merged into the main
<code>AndroidManifest.xml</code> (merger).
<i>(List of <a href="build-ref.html#labels">labels</a>; required)</i><br/>
<p>AndroidManifest files of type <code>.xml</code>.
Other android_manifest_merge targets are allowed here.
</p>
<p>Mergee(s) will be merged into the merger. Class references from the
mergee(s) that are not in a fully qualified format.
</p>
<p>Duplicates from the mergees (that also exist in the merger) will be
omitted during the merge. (e.g.: Duplicate permissions entries)
</p>
<p>Mergees contribute following elements to the merger:<br>
From Manifest element:<br>
<code>instrumentation</code>, <code>permission</code>,
<code>uses-permission</code>, <code>uses-feature</code><br>
From Application element:<br>
<code>activity</code>, <code>provider</code>, <code>receiver</code>,
<code>service</code>, <code>uses-library</code>
</p>
</li>
<li id="android_manifest_merge.srcs"><code>srcs</code>:
The list of one manifest file to merge other manifest files (mergees) into.
<i>(<a href="build-ref.html#labels">labels</a>; required)</i>
<p>AndroidManifest file of type <code>.xml</code>.
Usually it is your main app's manifest. This is the merger manifest file -
Manifest that other manifests (mergees) would be merged into.
Your app will use merger's package name, versioning, application attributes
and permissions. This srcs list is allowed to have only one label.
</p>
</li>
<li id="android_manifest_merge.exclude_permissions"><code>exclude_permissions</code>:
<code>exclude_permissions</code>:
The permission(s) to be excluded from the mergee(s).
<i>(List of strings; optional)</i><br/>
If specified, permissions in the list will be excluded from all the mergees.
If an excluded permission is in merger, then it will remain in the resulting
merged manifest.
</li>
</ul>
<h3 id="android_resources">android_resources</h3>
<p class="rule-signature">
android_resources(<a href="#android_resources.name">name</a>,
<a href="#android_resources.resources">resources</a>,
<a href="#android_resources.assets">assets</a>,
<a href="#android_resources.assets_dir">assets_dir</a>,
<a href="#android_resources.custom_package">custom_package</a>,
<a href="#common.deprecation">deprecation</a>,
<a href="#common.distribs">distribs</a>,
<a href="#android_resources.exports_manifest">exports_manifest</a>,
<a href="#android_resources.inline_constants">inline_constants</a>,
<a href="#common.licenses">licenses</a>,
<a href="#android_resources.manifest">manifest</a>,
<a href="#common.obsolete">obsolete</a>,
<a href="#android_resources.rename_manifest_package">rename_manifest_package</a>,
<a href="#common.tags">tags</a>,
<a href="#common.testonly">testonly</a>,
<a href="#common.visibility">visibility</a>)
</p>
<p>
Generates <code><var>name</var>.srcjar</code> which contains R.java,
Manifest.java and any other java resources generated by aapt.
</p>
<h4 id="android_resources_implicit_outputs">Implicit output targets</h4>
<ul>
<li><code><var>name</var>.srcjar</code>: A <code>.srcjar</code> file
containing all java generated sources.</li>
<li><code><var>name</var>.ap_</code>: An Android application package file
containing the manifest, all resources and assets.</li>
</ul>
<h4 id="android_resources">Arguments</h4>
<ul>
<li id="android_resources.name"><code>name</code>: A unique name for this rule. <i>(<a href="build-ref.html#name">Name</a>; required)</i></li>
<li id="android_resources.resources"><code>resources</code>:
The list of resources to be packaged.
<i>(List of <a href="build-ref.html#labels">labels</a>; optional)</i><br/><br/>
This is typically a <code>glob</code> of all files under the
<code>res</code> directory.
If you depend on resources in other packages, you should reference their
rules or exported files here. This enables bazel to resolve any conflicts
with file names or attribute names.<br/>
The only restriction is that the outputs must be under the
same directory in the corresponding package.
</li>
<li id="android_resources.assets"><code>assets</code>:
The list of assets to be packaged.
<i>(List of <a href="build-ref.html#labels">labels</a>; optional)</i><br/>
This is typically a <code>glob</code> of all files under the
<code>assets</code> directory. You can also reference other rules or
exported files in the other packages, as long as all their outputs are
under the <code>assets_dir</code> directory in the corresponding package.
</li>
<li id="android_resources.assets_dir"><code>assets_dir</code>:
The string giving the path to the files in <code>assets</code>.
<i>(String; optional)</i><br/>
The pair <code>assets</code> and <code>assets_dir</code> describe packaged
assets and either both attributes should be provided or none of them.
</li>
<li id="android_resources.custom_package"><code>custom_package</code>:
Java package for which java sources will be generated.
<i>(String; optional)</i><br/>
By default the package is inferred from the directory where the BUILD file
containing the rule is. You can specify a different package but this is
highly discouraged since it can introduce classpath conflicts with other
libraries that will only be detected at runtime.
</li>
<li id="android_resources.exports_manifest"><code>exports_manifest</code>:
Whether to export manifest entries to <code>android_binary</code> targets
that depend on this target. <code>uses-permissions</code> attributes are never exported.
<i>(Boolean; optional; default is 0)</i><br/>
</li>
<li id="android_resources.inline_constants"><code>inline_constants</code>:
Let the compiler inline the constants defined in the generated java sources.
<i>(Boolean; optional; default is 1)</i><br/>
This attribute must be set to 0 for all <code>android_resources</code> rules
used directly by an <code>android_library</code> (android library project)
and for any <code>android_binary</code> that has an android library project
in its transitive closure.
</li>
<li id="android_resources.manifest"><code>manifest</code>:
The name of the Android manifest file.
Current Android toolchain expects <code>AndroidManifest.xml</code> name.
<i>(<a href="build-ref.html#labels">Label</a>; required)</i><br/>
</li>
<li id="android_resources.rename_manifest_package"><code>rename_manifest_package</code>:
Changes the app package name.
<i>(String; optional)</i><br/>
Default package name is specified in your AndroidManifest.xml under package
attribute, and that will be used if this attribute is not specified.
Passes the value to aapt flag --rename-manifest-package. Rewrite the
manifest so that its package name is the package name given here.
Relative class names (for example .Foo) will be changed to absolute names
with the old package so that the code does not need to change. This is to
be used if desired outcome is to rename the package to other than the
actual package is, without modifying the AndroidManifest.xml, class paths
or code. This allows releasing the app under different name in the
android market.
</li>
</ul>
<h4 id="android_resources_examples">Examples</h4>
<p>Please see examples under
<a href="#android_binary_examples">android_binary</a>.</p>
<p>Here is an example of combining multiple assets sources. Let
<code>//java/android/o/BUILD</code> contain</p>
<pre class="code">
exports_files(["assets/other"])
</pre>
<p>Then in the other package you can say:</p>
<pre class="code">
android_resources(
name = "r",
assets = [
"assets/source",
"//java/android/o:assets/other",
],
assets_dir = "assets",
manifest = "AndroidManifest.xml",
)
</pre>
<pre class="code">
android_resources(
name = "r",
assets = glob(["assets/**"])
assets_dir = "moreassets",
manifest = "AndroidManifest.xml",
)
</pre>
<h3 id="genrule">genrule</h3>
<p class="rule-signature">
genrule(<a href="#genrule.name">name</a>,
<a href="#genrule.srcs">srcs</a>,
<a href="#genrule.outs">outs</a>,
<a href="#genrule.cmd">cmd</a>,
<a href="#common.deprecation">deprecation</a>,
<a href="#common.distribs">distribs</a>,
<a href="#genrule.executable">executable</a>,
<a href="#genrule.heuristic_label_expansion">heuristic_label_expansion</a>,
<a href="#common.licenses">licenses</a>,
<a href="#genrule.local">local</a>,
<a href="#genrule.message">message</a>,
<a href="#common.obsolete">obsolete</a>,
<a href="#genrule.output_licenses">output_licenses</a>,
<a href="#genrule.output_to_bindir">output_to_bindir</a>,
<a href="#genrule.stamp">stamp</a>,
<a href="#common.tags">tags</a>,
<a href="#common.testonly">testonly</a>,
<a href="#genrule.tools">tools</a>,
<a href="#common.visibility">visibility</a>)
</p>
<p>A <code>genrule</code> generates one or more files, where the generation of
those files is done with custom shell commands running in bash. While this
makes them very flexible, they are also difficult to use correctly.
</p>
<h4>When not to use a genrule?</h4>
<ul>
<li>Do not use a genrule for running tests - there are special dispensations
for tests and test results, including caching policies and environment
variables. Tests generally need to be run for the target architecture,
possibly on special machines, whereas genrules are run during
the build. If you need a general purpose testing rule, use sh_test.
<li>If there is a more specific rule, use that. All the heavy
lifting has already been done for you. For example, most built-in binary rules
already have support stamping - file a bug if the existing support is
insufficient.
</ul>
<h4>Cross-compilation Considerations</h4>
<p>While genrules run during a build, their outputs are often used after the
build, for deployment or testing. The build system uses the host configuration to describe
the machines on
which the build runs, and the target configuration to describe the machines on
which the output of the build is supposed to run. It provides options to
configure each of these, and it segregates the corresponding files into
separate directories to avoid conflicts.
</p>
<p>For genrules, the build system ensures that dependencies are built
appropriately - <code>srcs</code> are built (if necessary) for the target
configuration, tools are built for the host configuration, and the output is
considered to be for the target configuration. It also provides
<a href="#make_variables">"Make" variable</a> that genrule
commands can pass to the corresponding tools.
</p>
<p>It is intentional that genrule does not have a deps attribute - other
built-in rules use language-dependent meta information passed between the
rules to automatically determine how to handle dependent rules, but this level
of automation is not possible for genrules. Genrules work purely at the file
and runfiles level.
</p>
<h4>Special Cases</h4>
<p><i>Host-host compilation</i> - in some cases, the build system needs to run
genrules such that the output can also be run during the build. In that case,
the build system automatically builds the <code>srcs</code> and
<code>outs</code> for the host configuration, and sets the variables
accordingly.
</p>
<h4>Genrule Environment</h4>
<p>Genrules are executed in a sandbox that only allows access to declared
inputs. Genrules that are run locally are currently an exception, but this may
change in the future, i.e., local genrules will also be run in a sandbox. The
declared output files from a genrule are copied out of the sandbox, whereas
all other files are dropped.
</p>
<p>Furthermore, the build system sets environment variables it sets
<code>PATH</code> to point to a set of standard utilities). At least awk, bash, echo, diff, find,
grep, gzip, m4, md5sum, patch, perl, sed, tar, and xargs are provided.
It sets <code>LANG</code> to <code>en_US</code>. No other
environment variables are set; in particular, no environment variables are
passed through from the build system invocation.
</p>
<p>The genrule command is executed in a bash shell. The bash
shell is configured to fail when a command fails (<code>set -e</code>); at
some point in the future, it will also fail when a command in a pipline fails
(<code>set -o pipefail</code>). Genrules should not access the network (except
to create connections between processes running within the same genrule on the
same machine), though this is not currently enforced in all cases.
</p>
<p>The build system automatically deletes any existing output files, but creates
any necessary parent directories before it runs a genrule. It also removes any
output files in case of a failure.
</p>
<h4>General Advice</h4>
<ul>
<li>Do ensure that tools run by a genrule are deterministic and hermetic. They
should not write timestamps to their output, use stable ordering for sets and
maps, as well as only write relative paths to output.
<li>Do use <code>$(location)</code> extensively, including for outputs and
sources. Due to the segregation of output files for different
configurations, genrules cannot rely on hard-coded paths.
<li>Do make sure that the exit code correctly indicates success or failure of
the genrule.
<li>Do refer directly to the output file or files of a genrule from other
rules, rather than to the genrule itself; the build system figures out
automatically that it has to run the genrule.
<li>Do extract the genrule command into a separate script or rewrite it as a
binary if it becomes too long. This also improves testability.
<li>Do not write informational messages to stdout or stderr. While useful for
debugging, this is generally considered noise; a successful genrule should
be silent. On the other hand, a failing genrule should emit good error
messages.
<li><code>$$</code> evaluates to a <code>$</code>, a literal dollar-sign - so,
to invoke a shell command containing dollar-signs such as
<code>ls $(dirname $x)</code>, one must escape it thus:
<code>ls $$(dirname $$x)</code>.
<li>Do not create symlinks or directories, or, if you must,
use <code>local = 1</code> at your own risk.
</ul>
<h4 id="genrule">Arguments</h4>
<ul>
<li id="genrule.name"><code>name</code>: A unique name for this rule. <i>(<a href="build-ref.html#name">Name</a>; required)</i> <br/>You may refer to this rule by name in the
<code>srcs</code> or <code>deps</code> section of other <code>BUILD</code>
rules. If the rule generates source files, you should use the
<code>srcs</code> attribute.
</li>
<li id="genrule.srcs"><code>srcs</code>:
A list of inputs for this rule.
<i>(List of <a href="build-ref.html#labels">labels</a>; optional)</i>
<p>The build system ensures these prerequisites are built before
running the genrule command; they are built using the same
configuration as the original build request. The names of the
files of these prerequisites are available to the command as a
space-separated list in <code>$(SRCS)</code>; alternatively the
path of an individual <code>srcs</code> target <code>//x:y</code>
can be obtained using <code>$(location //x:y)</code>.</p>
<p>Most rules, when used in <code>genrule.srcs</code>, behave the same way:
their outputs are made available to the <code>genrule</code>.</p>
</li>
<li id="genrule.outs"><code>outs</code>:
A list of files generated by this command.
<i>(List of <a href="build-ref.html#filename">filenames</a>; required)</i><br/>
<p>All output files must be generated into the same directory and must not
cross package boundaries.
Output filenames are interpreted as relative to the package root.</p>
<p>If the <code>executable</code> flag is set, <code>outs</code> must
contain exactly one label.</p>
</li>
<li id="genrule.cmd"><code>cmd</code>:
The command to run.
<i>(String; required; subject to
<a href="#make_variables">"Make" variable</a> substitution.)</i><br/>
<ol>
<li>
Firstly, all occurrences of <code>$(location
<i>label</i>)</code> are replaced by the path to the file
denoted by <i>label</i>. If <i>label</i> is malformed, or
not a declared dependency of this rule, or expands to a
number of files other than exactly one, an error is raised.
<i>label</i> need not be in canonical form:
<code>foo</code>, <code>:foo</code> and
<code>//thispkg:foo</code> are all equivalent. It may also
be the name of an output file from the <code>outs</code>
attribute, in which case only the unqualified
form <code>foo</code> (no <code>//</code>
or <code>:</code>) may be used.
</li>
<li>
Secondly, all occurrences of <code>$(locations
<i>label</i>)</code> are replaced by the space separated paths
to the files denoted by <i>label</i>. If <i>label</i> is malformed,
or not a declared dependency of this rule, or expands to no
files, an error is raised.
<p>This is essentially the same substitution as
<code>$(location)</code>, but without the upper limit on the
number of files.</p>
</li>
<li>
<p>Thirdly, if <code>heuristic_label_expansion</code> is enabled, a
heuristic pass is applied to the string to replace all occurrences of
the labels occurring in the <code>srcs</code>, <code>tools</code> and
<code>data</code> attributes of the rule, by their
corresponding filenames.</p>
<p>(In effect, this is the same substitution as
<code>$(location)</code>, but in some cases, the heuristic
may fail to detect certain labels, for example, when
constructing a command-line such as <code>$(JAVA) -classpath
<i>label1</i>:<i>label2</i>:<i>label3</i> foo.jar</code>.
We recommend that in all new code, the explicit
<code>$(location)</code> form is used in preference to the
heuristic.)</p>
<p>Note that <code>outs</code> are <i>not</i> included in
this substitution. Output files are
always generated into a predictable location (available via
<code>$(@D)</code>, see below).</p>
</li>
<li>
Next, <a href="#make_variables">"Make" variables</a> are expanded. Note
that predefined variables <code>$(JAVA)</code>, <code>$(JAVAC)</code> and
<code>$(JAVABASE)</code> expand under the
<i>host</i> configuration, so Java invocations that run as part of a
build step can correctly load shared libraries and other dependencies.
</li>
<li>
Finally, the resulting command is executed using the Bash
shell. If its exit-status is non-zero, the command is
considered to have failed.
</li>
</ol>
<p>
The command may refer to binaries; it should use a <a
href="build-ref.html#labels">label</a> for this. The following
variables are available within the <code>cmd</code> sublanguage:</p>
<ul>
<li>
<a href="#predefined_variables.genrule.cmd">"Make" variables</a>
</li>
<li>
Variables defined in the BUILD file (using <code>vardef</code>).
</li>
<li>
"Make" variables that are predefined by the build tools.
Please use these variables instead of hardcoded values.
See <a href="#predefined_variables">Predefined "Make" Variables</a> in
this document for a list of supported values.
</li>
</ul>
</li>
<li id="genrule.executable"><code>executable</code>:
Declare output to be executable.
<i>(Boolean; optional; default is 0)</i> <br/>
<p>Setting this flag to 1 means the output is an executable file and can be
run using the <code>bazel run</code> command. The genrule must produce
exactly one output in this case. If this attribute is set, <code>bazel
run</code> will try executing the file regardless of its file type.</p>
<p>Note that for legacy compatibility the use of this attribute is not
always necessary for <code>bazel run</code> to work. If the output is
<ul>
<li>a Shell Script (<code>.sh</code>),</li>
<li>has no extension at all,</li>
</ul>
then <code>bazel run</code> will execute the target even if this flag is
set to 0 or unset. For new targets, please explicitly specify this
attribute as needed.</p>
<p>Unfortunately there is no way to declare data dependencies yet (but it
is being worked on).</p>
</li>
<li id="genrule.heuristic_label_expansion"><code>heuristic_label_expansion</code>:
Whether to perform heuristic label expansion
<i>(Boolean; optional; default is true)</i><br/>
If disabled, bazel does not attempt to find labels in the command. Instead,
you must use the location function <code>$(location)</code> to expand
labels.
</li>
<li id="genrule.message"><code>message</code>:
A progress message
<i>(String; optional)</i><br/>
A progress message that will be printed as this build step is
executed. By default, the message is "Generating <i>output</i>"
(or something equally bland) but you may provide a more specific
one. Use this attribute instead of <code>echo</code> or other
print statements in your <code>cmd</code> command, as this allows
the build tool to control whether such progress messages are
printed or not.
</li>
<li id="genrule.output_licenses"><code>output_licenses</code>:
See <a href="#binary.output_licenses"><code>common attributes</code></a>
</li>
<li id="genrule.output_to_bindir"><code>output_to_bindir</code>:
Place output files in the <code>bin</code> directory.
<i>(Boolean; optional; default is 0)</i> <br/>
If set to 1, this option causes output files to be written into the
<code>bin</code> directory instead of the <code>genfiles</code> directory.
</li>
<li id="genrule.stamp"><code>stamp</code>:
Whether to give access to build stamp information to the genrule
<i>(Boolean; optional; default is false)</i><br/>
The possible values are:
<ul>
<li><code>stamp = 1</code>: Always make the build information available to
the genrule. Use this with caution, since this potentially affects
caching if many things depend on this genrule.</li>
<li><code>stamp = 0</code>: Never make build information available to
the genrule.</li>
</ul>
<p>The build information files are available as
<code>bazel-out/build-info.txt</code> and
<code>bazel-out/build-changelist.txt</code>.</p>
<p>Note that the handling of this attribute is different from that of every
other rule.</p>
</li>
<li id="genrule.tools"><code>tools</code>:
A list of <i>tool</i> dependencies for this rule.
<i>(List of
<a href="build-ref.html#labels">labels</a>; optional)</i><br />
See the definition of <a href="build-ref.html#deps">dependencies</a> for
more information. <br/>
The build system ensures these prerequisites are built before
running the genrule command; they are built using the <a
href='bazel-user-manual.html#configurations'><i>host</i>
configuration</a>, since they must run on your workstation during the
build itself. The path of an individual <code>tools</code>
target <code>//x:y</code> can be obtained using <code>$(location
//x:y)</code>.
Any binaries or tools to be executed by <code>cmd</code>
must appear in this list, not in <code>srcs</code>, to ensure they
are built in the correct configuration.
</li>
</ul>
<h4 id="genrule_examples">Examples</h4>
<p>The following example shows how to process
<pre class="code">
genrule(
name = "concat_all_files",
srcs = [
"//some:file",
"//other:file",
],
outs = ["concatenated.txt"],
cmd = "cat $(location //some:file) $(location //other:file) > $@"
)
</pre>
<h3 id="java_plugin">java_plugin</h3>
<p class="rule-signature">
java_plugin(<a href="#java_plugin.name">name</a>,
<a href="#java_library.deps">deps</a>,
<a href="#java_library.srcs">srcs</a>,
<a href="#java_library.data">data</a>,
<a href="#java_binary.resources">resources</a>,
<a href="#common.deprecation">deprecation</a>,
<a href="#common.distribs">distribs</a>,
<a href="#java_plugin.generates_api">generates_api</a>,
<a href="#java_binary.javacopts">javacopts</a>,
<a href="#common.licenses">licenses</a>,
<a href="#java_library.neverlink">neverlink</a>,
<a href="#common.obsolete">obsolete</a>,
<a href="#java_binary.plugins">plugins</a>,
<a href="#java_plugin.processor_class">processor_class</a>,
<a href="#common.tags">tags</a>,
<a href="#common.testonly">testonly</a>,
<a href="#common.visibility">visibility</a>)
</p>
<p>
java_plugin() defines plugins for the Java compiler run by Bazel.
At the moment, the only supported kind of plugins are annotation
processors. A <code>java_library</code> or <code>java_binary</code>
rule can run plugins by depending on them via the
<code>plugins</code> attribute. A <code>java_library</code> can also export
plugins automatically to libraries that directly depend on it using
<code><a href="#java_library.exported_plugins">exported_plugins</a></code>.
</p>
<h4 id="java_plugin_implicit_outputs">Implicit output targets</h4>
<ul>
<li><code><var>libname</var>.jar</code>: A Java archive.</li>
</ul>
<h4 id="java_plugin">Arguments</h4>
<ul>
<li id="java_plugin.name"><code>name</code>: A unique name for this rule. <i>(<a href="build-ref.html#name">Name</a>; required)</i></li>
<li id="java_plugin.generates_api"><code>generates_api</code>:
This attribute marks annotation processors that generate API code.
<i>(Boolean; optional, default is 0)</i><br/>
If a rule uses an API-generating annotation processor, other rules
depending on it can refer to the generated code only if their compilation
actions are scheduled after the generating rule, which happens with
--nouse_src_ijars. This attribute instructs Bazel to introduce scheduling
constraints when --use_src_ijars is enabled.
</li>
<li id="java_plugin.processor_class"><code>processor_class</code>:
<i>(<a href="build-ref.html#name">Name</a>; optional)</i><br/>
The processor class is the fully qualified type of the class that the Java
compiler should use as entry point to the annotation processor.
If not specified, the <code>java_plugin</code> will not contribute an
annotation processor to the Java compiler's annotation processing,
but its runtime classpath will still be included on the compiler's
annotation processor path.
</li>
</ul>
<p>Arguments are identical to <a href="#java_library">java_library()</a>,
except for the addition of the <code>processor_class</code> argument.</p>
<h3 id="java_wrap_cc">java_wrap_cc</h3>
<p class="rule-signature">
java_wrap_cc(<a href="#java_wrap_cc.name">name</a>,
<a href="#java_wrap_cc.deps">deps</a>,
<a href="#java_wrap_cc.srcs">srcs</a>,
<a href="#common.data">data</a>,
<a href="#cc_binary.copts">copts</a>,
<a href="#common.deprecation">deprecation</a>,
<a href="#common.distribs">distribs</a>,
<a href="#java_wrap_cc.javacopts">javacopts</a>,
<a href="#java_wrap_cc.legacy_override_module">legacy_override_module</a>,
<a href="#common.licenses">licenses</a>,
<a href="#common.obsolete">obsolete</a>,
<a href="#java_wrap_cc.package">package</a>,
<a href="#cc_binary.plugins">plugins</a>,
<a href="#java_wrap_cc.swig_includes">swig_includes</a>,
<a href="#java_wrap_cc.swig_top">swig_top</a>,
<a href="#common.tags">tags</a>,
<a href="#common.testonly">testonly</a>,
<a href="#common.visibility">visibility</a>)
</p>
<p>
java_wrap_cc() turns a <code>.swig</code> file and some C++ libraries into
a Java swigging. The outputs are a static archive file and a Java archive that
provides the Java interface. The archive file is linked into the swigdeps.so
shared library, or if using a <a href="#java_binary.launcher">java launcher</a>,
linked into the launcher itself.
</p>
<h4 id="java_wrap_cc_implicit_outputs">Implicit output targets</h4>
<ul><li><code>lib<var>name</var>.jar</code>: A Java archive.</li></ul>
<h4 id="java_wrap_cc">Arguments</h4>
<ul>
<li id="java_wrap_cc.name"><code>name</code>: A unique name for this rule. <i>(<a href="build-ref.html#name">Name</a>; required)</i></li>
<li id="java_wrap_cc.deps"><code>deps</code>:
The libraries to compile into the module.
<i>(List of <a href="build-ref.html#labels">labels</a>; required)</i><br/>
See general comments about <code>deps</code>
at <a href="#common-attributes">Attributes common to all build
rules</a>.
These can be C++ libraries, Java libraries, or other
<code>java_wrap_cc</code> rules. Plain files such as <code>.i</code> or
<code>.swig</code> files are currently also allowed, but should be avoided,
if possible.
</li>
<li id="java_wrap_cc.srcs"><code>srcs</code>:
A list of one <code>swig</code> source.
<i>(List of <a href="build-ref.html#labels">labels</a>; required)</i>
</li>
<li id="java_wrap_cc.javacopts"><code>javacopts</code>:
See <a href="#java_binary.javacopts"><code>java_binary</code></a>
</li>
<li id="java_wrap_cc.legacy_override_module"><code>legacy_override_module</code>:
<i>(Boolean; optional; default 1)</i><br/>
By default, the <code>-module main</code> option is passed to the swig tool,
which overrides any module declaration in the source file. This option can
be used to disable that behavior.
</li>
<li id="java_wrap_cc.package"><code>package</code>:
<i>(String; optional; default current_package.target_name)</i><br/>
The package of the generated Java classes.
</li>
<li id="java_wrap_cc.swig_includes"><code>swig_includes</code>:
<i>(Label list; optional)</i><br/>
List of files that are included by the swig file.
</li>
<li id="java_wrap_cc.swig_top"><code>swig_top</code>:
<i>(Label; optional)</i><br/>
Label of a <a href="#filegroup"><code>filegroup</code></a> containing
the file <code>swig</code>.
</li>
</ul>
<!-- =================================================================
package()
=================================================================
-->
<h3 id="package">package</h3>
<p>This function declares metadata that applies to every subsequent rule in the
package.</p>
<p>The <a href="build-ref.html#package">package</a>
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.</p>
<h4 id="package_args">Arguments</h4>
<ul>
<li id="package.default_visibility"><code>default_visibility</code>:
The default visibility of the rules in this package.
<i>(List of <a href="build-ref.html#labels">labels</a>; optional)</i><br/>
<p>Every rule in this package has the visibility specified in this
attribute, unless otherwise specified in the <code>visibility</code>
attribute of the rule. For detailed information about the syntax of this
attribute, see the documentation of the <a href="#common.visibility">visibility</a>
attribute.
</li>
<li id="package.default_obsolete"><code>default_obsolete</code>:
The default value of <a href="#common.obsolete"><code>obsolete</code></a> property
for all rules in this package. <i>(Boolean; optional; default is 0)</i>
</li>
<li id="package.default_deprecation"><code>default_deprecation</code>:
Sets the default <a href="#common.deprecation"><code>deprecation</code></a> message
for all rules in this package. <i>(String; optional)</i>
</li>
<li id="package.default_testonly"><code>default_testonly</code>:
Sets the default <a href="#common.testonly"><code>testonly</code></a> property
for all rules in this package. <i>(Boolean; optional; default is 0 except as noted)</i>
<p>In packages under <code>javatests</code> the default value is 1.</p>
</li>
</ul>
<h4 id="package_example">Examples</h4>
The declaration below declares that the rules in this package are
visible only to members of package
group <code>//foo:target</code>. Individual visibility declarations
on a rule, if present, override this specification.
<pre class="code">
package(default_visibility = ["//foo:target"])
</pre>
<!-- =================================================================
package_group()
=================================================================
-->
<h3 id="package_group">package_group</h3>
<p><code>package_group(name, packages, includes)</code></p>
<p>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 <a href="#common.visibility">visibility</a> attribute.
<h4 id="package_group_args">Arguments</h4>
<ul>
<li id="package_group.name"><code>name</code>:
A unique name for this rule.
<i>(<a href="build-ref.html#name">Name</a>; required)</i>
</li>
<li id="package_group.packages"><code>packages</code>:
A complete enumeration of packages in this group.
<i>(List of <a href="build-ref.html#s4">Package</a>; optional)</i><br/>
<p>Packages should be referred to using their full names,
starting with a double slash. For
example, <code>//foo/bar/main</code> is a valid element
of this list.</p>
<p>You can also specify wildcards: the specification
<code>//foo/...</code> specifies every package under
<code>//foo</code>, including <code>//foo</code> itself.
<p>If this attribute is missing, the package group itself will contain
no packages (but it can still include other package groups).</p>
</li>
<li id="package_group.includes"><code>includes</code>:
Other package groups that are included in this one.
<i>(List of <a href="build-ref.html#labels">labels</a>; optional)</i><br/>
<p>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 <code>a</code> contains package group <code>b</code>,
and <code>b</code> contains package group <code>c</code>, every
package in <code>c</code> will also be a member of <code>a</code>.</p>
</li>
</ul>
<h4 id="package_group_example">Examples</h4>
The following <code>package_group</code> declaration specifies a
package group called "tropical" that contains tropical fruits.
<pre class="code">
package_group(
name = "tropical",
packages = [
"//fruits/mango",
"//fruits/orange",
"//fruits/papaya/...",
],
)
</pre>
The following declarations specify the package groups of a fictional
application:
<pre class="code">
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"],
)
</pre>
<!-- =================================================================
DESCRIPTION
=================================================================
-->
<h3 id="description">Description</h3>
<p><code># Description: <var>...</var></code></p>
<p>
Each BUILD file should contain a <code>Description</code> comment.
</p>
<p>
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.
</p>
<h3 id="distribs">distribs</h3>
<p><code>distribs(distrib_methods)</code></p>
<p><code>distribs()</code> specifies the default distribution method (or
methods) of the build rules in a <code>BUILD</code> file. The <code>distribs()</code>
directive
should appear close to the beginning of the <code>BUILD</code> file,
before any build rules, as it sets the <code>BUILD</code>-file scope
default for build rule distribution methods.
</p>
<h4 id="distribs_args">Arguments</h4>
<p>The argument, <code id="distribs.distrib_methods">distrib_methods</code>,
is a list of distribution-method strings.
</p>
<!-- =================================================================
exports_files([label, ...])
=================================================================
-->
<h3 id="exports_files">exports_files</h3>
<p><code>exports_files([<i>label</i>, ...], visibility, licenses)</code></p>
<p>
<code>exports_files()</code> specifies a list of files belonging to
this package that are exported to other packages but not otherwise
mentioned in the BUILD file.
</p>
<p>
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, <code>exports_files</code> ensures that they may be referenced by
other packages. (One kind of data for which this is particularly useful are
shell and Perl scripts.)
</p>
<p>
Note: A BUILD file only consisting of <code>exports_files()</code> 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.
</p>
<h4 id="exports_files_args">Arguments</h4>
<p>
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 <code><a href="#package">package</a></code> function. The
<a href="#common.licenses">licenses</a> can also be specified.
</p>
<!-- =================================================================
glob()
=================================================================
-->
<h3 id="glob">glob</h3>
<p><code>glob(include, exclude=[], exclude_directories=1)</code>
</p>
<p>
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 <code>*</code> wildcard: as per the Unix shell, this wildcard
matches any string excluding the directory separator <code>/</code>.
In addition filename patterns can contain the recursive <code>**</code>
wildcard. This wildcard will match zero or more complete
path segments separated by the directory separator <code>/</code>.
This wildcard can only be used as a complete path segment. For example,
<code>"x/**/*.java"</code> is legal, but <code>"test**/testdata.xml"</code>
and <code>"**.java"</code> are both illegal. No other wildcards are supported.
</p>
<p>
Glob returns a list of every file in the current build package that:
</p>
<ul>
<li style="margin-bottom: 0">
Matches at least one pattern in <code>include</code>. </li>
<li>
Does not match any of the patterns in <code>exclude</code> (default []).</li>
</ul>
<p>
If the <code>exclude_directories</code> argument is enabled (1), files of
type directory will be omitted from the results (default 1).
</p>
<p>
There are several important limitations and caveats:
</p>
<ol>
<li>
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 <code>+</code> to add it to the result of the
<code>glob()</code> call.
</li>
<li>
Globs may match files in subdirectories. And subdirectory names
may be wildcarded. However...
</li>
<li>
Labels are not allowed to cross the package boundary and glob does
not match files in subpackages.
For example, the glob expression <code>**/*.cc</code> in package
<code>x</code> does not include <code>x/y/z.cc</code> if
<code>x/y</code> exists as a package (either as
<code>x/y/BUILD</code>, or somewhere else on the package-path). This
means that the result of the glob expression actually depends on the
existence of BUILD files &mdash; that is, the same glob expression would
include <code>x/y/z.cc</code> if there was no package called
<code>x/y</code>.
</li>
<li>
The restriction above applies to all glob expressions,
no matter which wildcards they use.
</li>
</ol>
<p>
In general, you should <b>try to provide an appropriate extension (e.g. *.html)
instead of using a bare '*'</b> 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.
</p>
<h4 id="glob_example">Glob Examples</h4>
<p>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 (**).</p>
<pre class="code">
java_test(
name = "myprog",
srcs = ["myprog.java"],
data = glob(
["testdata/*.txt"],
exclude = ["testdata/experimental.txt"],
),
)
</pre>
<h4 id="recursive_glob_example">Recursive Glob Examples</h4>
<p>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.
<b>This should be a very common pattern.</b>
</p>
<pre class="code">
java_library(
name = "mylib",
srcs = glob(
["**/*.java"],
exclude = ["**/testing/**"],
),
)
</pre>
<p>Make the test depend on all txt files in the testdata directory,
its subdirectories</p>
<pre class="code">
java_test(
name = "mytest",
srcs = ["mytest.java"],
data = glob(["testdata/**/*.txt"]),
)
</pre>
<!-- =================================================================
licenses()
=================================================================
-->
<h3 id="licenses">licenses</h3>
<p><code>licenses(license_types)</code></p>
<p><code>licenses()</code> specifies the default license type (or types)
of the build rules in a <code>BUILD</code> file. The <code>licenses()</code>
directive should appear close to the
beginning of the <code>BUILD</code> file, before any build rules, as it
sets the <code>BUILD</code>-file scope default for build rule license
types.</p>
<h4 id="licenses_args">Arguments</h4>
<p>The argument, <code id="licenses.licence_types">license_types</code>,
is a list of license-type strings.
</p>
<!-- =================================================================
include()
=================================================================
-->
<h3 id="include">include</h3>
<p><code>include(name)</code></p>
<p><code>include()</code> incorporates build
language definitions from an external file into the evaluation of the
current <code>BUILD</code> file.</p>
</body>
</html>