Google Git
Sign in
bazel/bazel/a640dc240f79ef811fb4089436f1ba6d84ea6bc9/./docs/versions/6.0.0/reference/be/android.mdx
blob: f71df3a5ca746cc3461256c8c2f1ff7e7f9a1018 [file]
<html devsite>
<head>
<meta name="project_path" value="/_project.yaml">
<meta name="book_path" value="/versions/6.0.0/_book.yaml">
</head>
<body>
<!--
This document is synchronized with Bazel releases.
To edit, submit changes to the Bazel source code.
-->
<!-- Generated by //src/main/java/com/google/devtools/build/docgen:build-encyclopedia.zip -->
<html>
<body>
<h1 class="page-title">Android Rules</h1>
<h2>Rules</h2>
<ul>
<li>
<a href="#android_binary">
android_binary </a>
</li>
<li>
<a href="#aar_import">
aar_import </a>
</li>
<li>
<a href="#android_library">
android_library </a>
</li>
<li>
<a href="#android_instrumentation_test">
android_instrumentation_test </a>
</li>
<li>
<a href="#android_local_test">
android_local_test </a>
</li>
<li>
<a href="#android_device">
android_device </a>
</li>
<li>
<a href="#android_ndk_repository">
android_ndk_repository </a>
</li>
<li>
<a href="#android_sdk_repository">
android_sdk_repository </a>
</li>
</ul>
<h2 id="android_binary">
android_binary
</h2>
<pre 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.assets">assets</a>, <a href="#android_binary.assets_dir">assets_dir</a>, <a href="common-definitions.html#common.compatible_with">compatible_with</a>, <a href="#android_binary.crunch_png">crunch_png</a>, <a href="#android_binary.custom_package">custom_package</a>, <a href="#android_binary.debug_key">debug_key</a>, <a href="#android_binary.debug_signing_keys">debug_signing_keys</a>, <a href="#android_binary.debug_signing_lineage_file">debug_signing_lineage_file</a>, <a href="#android_binary.densities">densities</a>, <a href="common-definitions.html#common.deprecation">deprecation</a>, <a href="#android_binary.dex_shards">dex_shards</a>, <a href="#android_binary.dexopts">dexopts</a>, <a href="common-definitions.html#common.distribs">distribs</a>, <a href="#android_binary.enable_data_binding">enable_data_binding</a>, <a href="common-definitions.html#common.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_properties">exec_properties</a>, <a href="common-definitions.html#common.features">features</a>, <a href="#android_binary.incremental_dexing">incremental_dexing</a>, <a href="#android_binary.instruments">instruments</a>, <a href="#android_binary.javacopts">javacopts</a>, <a href="#android_binary.key_rotation_min_sdk">key_rotation_min_sdk</a>, <a href="common-definitions.html#typical.licenses">licenses</a>, <a href="#android_binary.main_dex_list">main_dex_list</a>, <a href="#android_binary.main_dex_list_opts">main_dex_list_opts</a>, <a href="#android_binary.main_dex_proguard_specs">main_dex_proguard_specs</a>, <a href="#android_binary.manifest">manifest</a>, <a href="#android_binary.manifest_values">manifest_values</a>, <a href="#android_binary.multidex">multidex</a>, <a href="#android_binary.nocompress_extensions">nocompress_extensions</a>, <a href="#android_binary.package_id">package_id</a>, <a href="#android_binary.plugins">plugins</a>, <a href="#android_binary.proguard_apply_dictionary">proguard_apply_dictionary</a>, <a href="#android_binary.proguard_apply_mapping">proguard_apply_mapping</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.resource_configuration_filters">resource_configuration_filters</a>, <a href="#android_binary.resource_files">resource_files</a>, <a href="common-definitions.html#common.restricted_to">restricted_to</a>, <a href="#android_binary.shrink_resources">shrink_resources</a>, <a href="common-definitions.html#common.tags">tags</a>, <a href="common-definitions.html#common.target_compatible_with">target_compatible_with</a>, <a href="common-definitions.html#common.testonly">testonly</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre>
<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="/versions/6.0.0/reference/be/android.html#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="/versions/6.0.0/reference/be/android.html#android_binary.proguard_specs">proguard_specs</a> attribute is
specified and
<a href="/versions/6.0.0/reference/be/android.html#android_binary.proguard_generate_mapping">proguard_generate_mapping</a>
or <a href="/versions/6.0.0/reference/be/android.html#android_binary.shrink_resources">shrink_resources</a> is set.
</li>
</ul>
<h4 id="android_binary_examples">Examples</h4>
<p>Examples of Android rules can be found in the <code>examples/android</code> directory of the
Bazel source tree.
<h3 id="android_binary_args">Arguments</h3>
<table class="table table-condensed table-bordered table-params">
<colgroup>
<col class="col-param" />
<col class="param-description" />
</colgroup>
<thead>
<tr>
<th colspan="2">Attributes</th>
</tr>
</thead>
<tbody>
<tr>
<td id="android_binary.name"><code>name</code></td>
<td>
<p><code><a href="/versions/6.0.0/concepts/labels#target-names">Name</a>; required</code></p>
<p>A unique name for this target.</p>
</td>
</tr>
<tr>
<td id="android_binary.deps">
<code>deps</code>
</td>
<td>
<p><code>List of <a href="/versions/6.0.0/concepts/labels">labels</a>; optional</code></p>
The list of other libraries to be linked in to the binary target.
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.
</td>
</tr>
<tr>
<td id="android_binary.srcs">
<code>srcs</code>
</td>
<td>
<p><code>List of <a href="/versions/6.0.0/concepts/labels">labels</a>; optional</code></p>
The list of source files that are processed to create the target.
<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>
</td>
</tr>
<tr>
<td id="android_binary.assets">
<code>assets</code>
</td>
<td>
<p><code>List of <a href="/versions/6.0.0/concepts/labels">labels</a>; optional</code></p>
The list of assets to be packaged.
This is typically a <code>glob</code> of all files under the
<code>assets</code> directory. You can also reference other rules (any rule that produces
files) or exported files in the other packages, as long as all those files are under the
<code>assets_dir</code> directory in the corresponding package.
</td>
</tr>
<tr>
<td id="android_binary.assets_dir">
<code>assets_dir</code>
</td>
<td>
<p><code>String; optional</code></p>
The string giving the path to the files in <code>assets</code>.
The pair <code>assets</code> and <code>assets_dir</code> describe packaged
assets and either both attributes should be provided or none of them.
</td>
</tr>
<tr>
<td id="android_binary.crunch_png">
<code>crunch_png</code>
</td>
<td>
<p><code>Boolean; optional; default is True</code></p>
Do PNG crunching (or not). This is independent of nine-patch processing, which is always
done. This is a deprecated workaround for an
<a href="https://code.google.com/p/android/issues/detail?id=74334">aapt bug</a> which has
been fixed in aapt2.
</td>
</tr>
<tr>
<td id="android_binary.custom_package">
<code>custom_package</code>
</td>
<td>
<p><code>String; optional</code></p>
Java package for which java sources will be generated.
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.
</td>
</tr>
<tr>
<td id="android_binary.debug_key">
<code>debug_key</code>
</td>
<td>
<p><code><a href="/versions/6.0.0/concepts/labels">Label</a>; optional; default is <code>@bazel_tools//tools/android:debug_keystore</code></code></p>
File containing the debug keystore to be used to sign the debug apk. Usually you do not
want to use a key other than the default key, so this attribute should be omitted.
<p><em class="harmful">WARNING: Do not use your production keys, they should be
strictly safeguarded and not kept in your source tree</em>.</p>
</td>
</tr>
<tr>
<td id="android_binary.debug_signing_keys">
<code>debug_signing_keys</code>
</td>
<td>
<p><code>List of <a href="/versions/6.0.0/concepts/labels">labels</a>; optional</code></p>
List of files, debug keystores to be used to sign the debug apk. Usually you do not
want to use keys other than the default key, so this attribute should be omitted.
<p><em class="harmful">WARNING: Do not use your production keys, they should be
strictly safeguarded and not kept in your source tree</em>.</p>
</td>
</tr>
<tr>
<td id="android_binary.debug_signing_lineage_file">
<code>debug_signing_lineage_file</code>
</td>
<td>
<p><code><a href="/versions/6.0.0/concepts/labels">Label</a>; optional</code></p>
File containing the signing lineage for the debug_signing_keys. Usually you do not
want to use keys other than the default key, so this attribute should be omitted.
<p><em class="harmful">WARNING: Do not use your production keys, they should be
strictly safeguarded and not kept in your source tree</em>.</p>
</td>
</tr>
<tr>
<td id="android_binary.densities">
<code>densities</code>
</td>
<td>
<p><code>List of strings; optional</code></p>
Densities to filter for when building the apk.
This will strip out raster drawable resources that would not be loaded by a device with
the specified screen densities, to reduce APK size. A corresponding compatible-screens
section will also be added to the manifest if it does not already contain a superset
listing.
</td>
</tr>
<tr>
<td id="android_binary.dex_shards">
<code>dex_shards</code>
</td>
<td>
<p><code>Integer; optional; default is 1</code></p>
Number of shards dexing should be decomposed into.
This is makes dexing much faster at the expense of app installation and startup time. The
larger the binary, the more shards should be used. 25 is a good value to start
experimenting with.
<p>
Note that each shard will result in at least one dex in the final app. For this reason,
setting this to more than 1 is not recommended for release binaries.
</td>
</tr>
<tr>
<td id="android_binary.dexopts">
<code>dexopts</code>
</td>
<td>
<p><code>List of strings; optional</code></p>
Additional command-line flags for the dx tool when generating classes.dex.
Subject to <a href="/versions/6.0.0/reference/be/make-variables">"Make variable"</a> substitution and
<a href="/versions/6.0.0/reference/be/common-definitions#sh-tokenization">Bourne shell tokenization</a>.
</td>
</tr>
<tr>
<td id="android_binary.enable_data_binding">
<code>enable_data_binding</code>
</td>
<td>
<p><code>Boolean; optional; default is False</code></p>
If true, this rule processes
<a href="https://developer.android.com/topic/libraries/data-binding/index.html">data
binding</a> expressions in layout resources included through the
<a href="/versions/6.0.0/reference/be/android.html#android_binary.resource_files">resource_files</a> attribute. Without this
setting, data binding expressions produce build failures.
<p>
To build an Android app with data binding, you must also do the following:
<ol>
<li>Set this attribute for all Android rules that transitively depend on this one.
This is because dependers inherit the rule's data binding expressions through resource
merging. So they also need to build with data binding to parse those expressions.
<li>Add a <code>deps =</code> entry for the data binding runtime library to all targets
that set this attribute. The location of this library depends on your depot setup.
</ol>
</td>
</tr>
<tr>
<td id="android_binary.incremental_dexing">
<code>incremental_dexing</code>
</td>
<td>
<p><code>Integer; optional; <a href="common-definitions.html#configurable-attributes">nonconfigurable</a>; default is -1</code></p>
Force the target to be built with or without incremental dexing, overriding defaults
and --incremental_dexing flag.
</td>
</tr>
<tr>
<td id="android_binary.instruments">
<code>instruments</code>
</td>
<td>
<p><code><a href="/versions/6.0.0/concepts/labels">Label</a>; optional</code></p>
<p>The <code>android_binary</code> target to instrument.</p>
<p>If this attribute is set, this <code>android_binary</code> will be treated as a test
application for instrumentation tests. An <code>android_instrumentation_test</code>
target can then specify this target in its
<a href="/versions/6.0.0/reference/be/android.html#android_instrumentation_test.test_app">test_app</a> attribute.
</td>
</tr>
<tr>
<td id="android_binary.javacopts">
<code>javacopts</code>
</td>
<td>
<p><code>List of strings; optional</code></p>
Extra compiler options for this target.
Subject to <a href="/versions/6.0.0/reference/be/make-variables">"Make variable"</a> substitution and
<a href="/versions/6.0.0/reference/be/common-definitions#sh-tokenization">Bourne shell tokenization</a>.
<p>
These compiler options are passed to javac after the global compiler options.</p>
</td>
</tr>
<tr>
<td id="android_binary.key_rotation_min_sdk">
<code>key_rotation_min_sdk</code>
</td>
<td>
<p><code>String; optional</code></p>
Sets the minimum Android platform version (API Level) for which an APK's rotated signing
key should be used to produce the APK's signature. The original signing key for the APK
will be used for all previous platform versions.
</td>
</tr>
<tr>
<td id="android_binary.main_dex_list">
<code>main_dex_list</code>
</td>
<td>
<p><code><a href="/versions/6.0.0/concepts/labels">Label</a>; optional</code></p>
A text file contains a list of class file names. Classes defined by those class files are
put in the primary classes.dex. e.g.:<pre class="code">
android/support/multidex/MultiDex$V19.class
android/support/multidex/MultiDex.class
android/support/multidex/MultiDexApplication.class
com/google/common/base/Objects.class
</pre>
Must be used with <code>multidex="manual_main_dex"</code>.
</td>
</tr>
<tr>
<td id="android_binary.main_dex_list_opts">
<code>main_dex_list_opts</code>
</td>
<td>
<p><code>List of strings; optional</code></p>
Command line options to pass to the main dex list builder.
Use this option to affect the classes included in the main dex list.
</td>
</tr>
<tr>
<td id="android_binary.main_dex_proguard_specs">
<code>main_dex_proguard_specs</code>
</td>
<td>
<p><code>List of <a href="/versions/6.0.0/concepts/labels">labels</a>; optional</code></p>
Files to be used as the Proguard specifications to determine classes that must be kept in
the main dex.
Only allowed if the <code>multidex</code> attribute is set to <code>legacy</code>.
</td>
</tr>
<tr>
<td id="android_binary.manifest">
<code>manifest</code>
</td>
<td>
<p><code><a href="/versions/6.0.0/concepts/labels">Label</a>; required</code></p>
The name of the Android manifest file, normally <code>AndroidManifest.xml</code>.
Must be defined if resource_files or assets are defined.
</td>
</tr>
<tr>
<td id="android_binary.manifest_values">
<code>manifest_values</code>
</td>
<td>
<p><code>Dictionary: String -> String; optional</code></p>
A dictionary of values to be overridden in the manifest. Any instance of ${name} in the
manifest will be replaced with the value corresponding to name in this dictionary.
applicationId, versionCode, versionName, minSdkVersion, targetSdkVersion and
maxSdkVersion will also override the corresponding attributes of the manifest and
uses-sdk tags. packageName will be ignored and will be set from either applicationId if
specified or the package in manifest. When manifest_merger is set to legacy, only
applicationId, versionCode and versionName will have any effect.
</td>
</tr>
<tr>
<td id="android_binary.multidex">
<code>multidex</code>
</td>
<td>
<p><code>String; optional; default is "native"</code></p>
Whether to split code into multiple dex files.<br/>
Possible values:
<ul>
<li><code>native</code>: Split code into multiple dex files when the dex 64K index limit
is exceeded. Assumes native platform support for loading multidex classes at runtime.
<em class="harmful">This works with only Android L and newer</em>.</li>
<li><code>legacy</code>: Split code into multiple dex files when the dex 64K index limit
is exceeded. Assumes multidex classes are loaded through application code (i.e. no
native platform support).</li>
<li><code>manual_main_dex</code>: Split code into multiple dex files when the dex 64K
index limit is exceeded. The content of the main dex file needs to be specified by
providing a list of classes in a text file using the
<a href="/versions/6.0.0/reference/be/android.html#android_binary.main_dex_list">main_dex_list</a> attribute.</li>
<li><code>off</code>: Compile all code to a single dex file, even if it exceeds the
index limit.</li>
</ul>
</td>
</tr>
<tr>
<td id="android_binary.nocompress_extensions">
<code>nocompress_extensions</code>
</td>
<td>
<p><code>List of strings; optional</code></p>
A list of file extension to leave uncompressed in apk.
</td>
</tr>
<tr>
<td id="android_binary.package_id">
<code>package_id</code>
</td>
<td>
<p><code>Integer; optional; default is 0</code></p>
Package ID to be assigned to resources in this binary.
<p>See AAPT2's <code>--package-id</code> argument for more information. This can (and
should) typically be left unset, resulting in the default value of 127
(<code>0x7F</code>).
</td>
</tr>
<tr>
<td id="android_binary.plugins">
<code>plugins</code>
</td>
<td>
<p><code>List of <a href="/versions/6.0.0/concepts/labels">labels</a>; optional</code></p>
Java compiler plugins to run at compile-time.
Every <code>java_plugin</code> specified in
the plugins attribute will be run whenever
this target is built. Resources generated by
the plugin will be included in the result jar of
the target.
</td>
</tr>
<tr>
<td id="android_binary.proguard_apply_dictionary">
<code>proguard_apply_dictionary</code>
</td>
<td>
<p><code><a href="/versions/6.0.0/concepts/labels">Label</a>; optional</code></p>
File to be used as a mapping for proguard.
A line separated file of "words" to pull from when renaming classes and members during
obfuscation.
</td>
</tr>
<tr>
<td id="android_binary.proguard_apply_mapping">
<code>proguard_apply_mapping</code>
</td>
<td>
<p><code><a href="/versions/6.0.0/concepts/labels">Label</a>; optional</code></p>
File to be used as a mapping for proguard.
A mapping file generated by <code>proguard_generate_mapping</code> to be
re-used to apply the same mapping to a new build.
</td>
</tr>
<tr>
<td id="android_binary.proguard_generate_mapping">
<code>proguard_generate_mapping</code>
</td>
<td>
<p><code>Boolean; optional; <a href="common-definitions.html#configurable-attributes">nonconfigurable</a>; default is False</code></p>
Whether to generate Proguard mapping file.
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 this attribute is used, the Proguard
specification should contain neither <code>-dontobfuscate</code> nor
<code>-printmapping</code>.</em></p>
</td>
</tr>
<tr>
<td id="android_binary.proguard_specs">
<code>proguard_specs</code>
</td>
<td>
<p><code>List of <a href="/versions/6.0.0/concepts/labels">labels</a>; optional</code></p>
Files to be used as Proguard specification.
This file will describe the set of specifications to be used by Proguard.
</td>
</tr>
<tr>
<td id="android_binary.resource_configuration_filters">
<code>resource_configuration_filters</code>
</td>
<td>
<p><code>List of strings; optional</code></p>
A list of resource configuration filters, such 'en' that will limit the resources in the
apk to only the ones in the 'en' configuration. To enable pseudolocalization, include the
<code>en_XA</code> and/or <code>ar_XB</code> pseudo-locales.
</td>
</tr>
<tr>
<td id="android_binary.resource_files">
<code>resource_files</code>
</td>
<td>
<p><code>List of <a href="/versions/6.0.0/concepts/labels">labels</a>; optional</code></p>
The list of resources to be packaged.
This is typically a <code>glob</code> of all files under the
<code>res</code> directory.
<br/>
Generated files (from genrules) can be referenced by
<a href="/versions/6.0.0/concepts/labels">Label</a> here as well. The only restriction is that
the generated outputs must be under the same "<code>res</code>" directory as any other
resource files that are included.
</td>
</tr>
<tr>
<td id="android_binary.shrink_resources">
<code>shrink_resources</code>
</td>
<td>
<p><code>Integer; optional; default is -1</code></p>
Whether to perform resource shrinking. Resources that are not used by the binary will be
removed from the APK. This is only supported for rules using local resources (i.e. the
<code>manifest</code> and <code>resource_files</code> attributes) and requires ProGuard.
It operates in mostly the same manner as the Gradle resource shrinker
(https://developer.android.com/studio/build/shrink-code.html#shrink-resources).
<p>Notable differences:
<ul>
<li>resources in <code>values/</code> will be removed as well as file based
resources</li>
<li>uses <code>strict mode</code> by default</li>
<li>removing unused ID resources is only supported with aapt2</li>
</ul>
If resource shrinking is enabled, <code><var>name</var>_files/resource_shrinker.log</code>
will also be generated, detailing the analysis and deletions performed.
<p>Possible values:
<ul>
<li><code>shrink_resources = 1</code>: Turns on Android resource shrinking</li>
<li><code>shrink_resources = 0</code>: Turns off Android resource shrinking</li>
<li><code>shrink_resources = -1</code>: Shrinking is controlled by the
<a href="/versions/6.0.0/docs/user-manual#flag--android_resource_shrinking">
--android_resource_shrinking</a> flag.</li>
</ul>
</td>
</tr>
</tbody>
</table>
<h2 id="aar_import">
aar_import
</h2>
<pre class="rule-signature">aar_import(<a href="#aar_import.name">name</a>, <a href="common-definitions.html#typical.deps">deps</a>, <a href="common-definitions.html#typical.data">data</a>, <a href="#aar_import.aar">aar</a>, <a href="common-definitions.html#common.compatible_with">compatible_with</a>, <a href="common-definitions.html#common.deprecation">deprecation</a>, <a href="common-definitions.html#common.distribs">distribs</a>, <a href="common-definitions.html#common.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_properties">exec_properties</a>, <a href="#aar_import.exports">exports</a>, <a href="common-definitions.html#common.features">features</a>, <a href="common-definitions.html#typical.licenses">licenses</a>, <a href="common-definitions.html#common.restricted_to">restricted_to</a>, <a href="#aar_import.srcjar">srcjar</a>, <a href="common-definitions.html#common.tags">tags</a>, <a href="common-definitions.html#common.target_compatible_with">target_compatible_with</a>, <a href="common-definitions.html#common.testonly">testonly</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre>
<p>
This rule allows the use of <code>.aar</code> files as libraries for
<code><a href="/versions/6.0.0/reference/be/android.html#android_library">android_library</a></code> and
<code><a href="/versions/6.0.0/reference/be/android.html#android_binary">android_binary</a></code> rules.
</p>
<h4 id="aar_import_examples">Examples</h4>
<pre class="code">
aar_import(
name = "google-vr-sdk",
aar = "gvr-android-sdk/libraries/sdk-common-1.10.0.aar",
)
android_binary(
name = "app",
manifest = "AndroidManifest.xml",
srcs = glob(["**.java"]),
deps = [":google-vr-sdk"],
)
</pre>
<h3 id="aar_import_args">Arguments</h3>
<table class="table table-condensed table-bordered table-params">
<colgroup>
<col class="col-param" />
<col class="param-description" />
</colgroup>
<thead>
<tr>
<th colspan="2">Attributes</th>
</tr>
</thead>
<tbody>
<tr>
<td id="aar_import.name"><code>name</code></td>
<td>
<p><code><a href="/versions/6.0.0/concepts/labels#target-names">Name</a>; required</code></p>
<p>A unique name for this target.</p>
</td>
</tr>
<tr>
<td id="aar_import.aar">
<code>aar</code>
</td>
<td>
<p><code><a href="/versions/6.0.0/concepts/labels">Label</a>; required</code></p>
The <code>.aar</code> file to provide to the Android targets that depend on this target.
</td>
</tr>
<tr>
<td id="aar_import.exports">
<code>exports</code>
</td>
<td>
<p><code>List of <a href="/versions/6.0.0/concepts/labels">labels</a>; optional</code></p>
Targets to export to rules that depend on this rule.
See <a href="/versions/6.0.0/reference/be/java.html#java_library.exports">java_library.exports.
</td>
</tr>
<tr>
<td id="aar_import.srcjar">
<code>srcjar</code>
</td>
<td>
<p><code><a href="/versions/6.0.0/concepts/labels">Label</a>; optional</code></p>
A JAR file that contains source code for the compiled JAR files in the AAR.
</td>
</tr>
</tbody>
</table>
<h2 id="android_library">
android_library
</h2>
<pre 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-definitions.html#typical.data">data</a>, <a href="#android_library.assets">assets</a>, <a href="#android_library.assets_dir">assets_dir</a>, <a href="common-definitions.html#common.compatible_with">compatible_with</a>, <a href="#android_library.custom_package">custom_package</a>, <a href="common-definitions.html#common.deprecation">deprecation</a>, <a href="common-definitions.html#common.distribs">distribs</a>, <a href="#android_library.enable_data_binding">enable_data_binding</a>, <a href="common-definitions.html#common.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_properties">exec_properties</a>, <a href="#android_library.exported_plugins">exported_plugins</a>, <a href="#android_library.exports">exports</a>, <a href="#android_library.exports_manifest">exports_manifest</a>, <a href="common-definitions.html#common.features">features</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_preprocessed">idl_preprocessed</a>, <a href="#android_library.idl_srcs">idl_srcs</a>, <a href="#android_library.javacopts">javacopts</a>, <a href="common-definitions.html#typical.licenses">licenses</a>, <a href="#android_library.manifest">manifest</a>, <a href="#android_library.neverlink">neverlink</a>, <a href="#android_library.plugins">plugins</a>, <a href="#android_library.proguard_specs">proguard_specs</a>, <a href="#android_library.resource_files">resource_files</a>, <a href="common-definitions.html#common.restricted_to">restricted_to</a>, <a href="common-definitions.html#common.tags">tags</a>, <a href="common-definitions.html#common.target_compatible_with">target_compatible_with</a>, <a href="common-definitions.html#common.testonly">testonly</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre>
<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>
<li><code><var>name</var>.aar</code>: An android 'aar' bundle containing the java archive
and resources of this target. It does not contain the transitive closure.</li>
</ul>
<h4 id="android_library_examples">Examples</h4>
<p>Examples of Android rules can be found in the <code>examples/android</code> directory of the
Bazel source tree.
<p id="android_library_examples.idl_import_root">The following example shows
how to set <code>idl_import_root</code>.
Let <code>//java/bazel/helloandroid/BUILD</code> contain:</p>
<pre class="code">
android_library(
name = "parcelable",
srcs = ["MyParcelable.java"], # bazel.helloandroid.MyParcelable
# MyParcelable.aidl will be used as import for other .aidl
# files that depend on it, but will not be compiled.
idl_parcelables = ["MyParcelable.aidl"] # bazel.helloandroid.MyParcelable
# We don't need to specify idl_import_root since the aidl file
# which declares bazel.helloandroid.MyParcelable
# is present at java/bazel/helloandroid/MyParcelable.aidl
# underneath a java root (java/).
)
android_library(
name = "foreign_parcelable",
srcs = ["src/android/helloandroid/OtherParcelable.java"], # android.helloandroid.OtherParcelable
idl_parcelables = [
"src/android/helloandroid/OtherParcelable.aidl" # android.helloandroid.OtherParcelable
],
# We need to specify idl_import_root because the aidl file which
# declares android.helloandroid.OtherParcelable is not positioned
# at android/helloandroid/OtherParcelable.aidl under a normal java root.
# Setting idl_import_root to "src" in //java/bazel/helloandroid
# adds java/bazel/helloandroid/src to the list of roots
# the aidl compiler will search for imported types.
idl_import_root = "src",
)
# Here, OtherInterface.aidl has an "import android.helloandroid.CallbackInterface;" statement.
android_library(
name = "foreign_interface",
idl_srcs = [
"src/android/helloandroid/OtherInterface.aidl" # android.helloandroid.OtherInterface
"src/android/helloandroid/CallbackInterface.aidl" # android.helloandroid.CallbackInterface
],
# As above, idl_srcs which are not correctly positioned under a java root
# must have idl_import_root set. Otherwise, OtherInterface (or any other
# interface in a library which depends on this one) will not be able
# to find CallbackInterface when it is imported.
idl_import_root = "src",
)
# MyParcelable.aidl is imported by MyInterface.aidl, so the generated
# MyInterface.java requires MyParcelable.class at compile time.
# Depending on :parcelable ensures that aidl compilation of MyInterface.aidl
# specifies the correct import roots and can access MyParcelable.aidl, and
# makes MyParcelable.class available to Java compilation of MyInterface.java
# as usual.
android_library(
name = "idl",
idl_srcs = ["MyInterface.aidl"],
deps = [":parcelable"],
)
# Here, ServiceParcelable uses and thus depends on ParcelableService,
# when it's compiled, but ParcelableService also uses ServiceParcelable,
# which creates a circular dependency.
# As a result, these files must be compiled together, in the same android_library.
android_library(
name = "circular_dependencies",
srcs = ["ServiceParcelable.java"],
idl_srcs = ["ParcelableService.aidl"],
idl_parcelables = ["ServiceParcelable.aidl"],
)
</pre>
<h3 id="android_library_args">Arguments</h3>
<table class="table table-condensed table-bordered table-params">
<colgroup>
<col class="col-param" />
<col class="param-description" />
</colgroup>
<thead>
<tr>
<th colspan="2">Attributes</th>
</tr>
</thead>
<tbody>
<tr>
<td id="android_library.name"><code>name</code></td>
<td>
<p><code><a href="/versions/6.0.0/concepts/labels#target-names">Name</a>; required</code></p>
<p>A unique name for this target.</p>
</td>
</tr>
<tr>
<td id="android_library.deps">
<code>deps</code>
</td>
<td>
<p><code>List of <a href="/versions/6.0.0/concepts/labels">labels</a>; optional</code></p>
The list of other libraries to link against.
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.
</td>
</tr>
<tr>
<td id="android_library.srcs">
<code>srcs</code>
</td>
<td>
<p><code>List of <a href="/versions/6.0.0/concepts/labels">labels</a>; optional</code></p>
The list of <code>.java</code> or <code>.srcjar</code> files that
are processed to create the target.
<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>If <code>srcs</code> is omitted, then any dependency specified in
<code>deps</code> is exported from this rule (see
<a href="/versions/6.0.0/reference/be/java.html#java_library.exports">java_library's exports</a> for more
information about exporting dependencies). However, this behavior will be
deprecated soon; try not to rely on it.
</p>
</td>
</tr>
<tr>
<td id="android_library.assets">
<code>assets</code>
</td>
<td>
<p><code>List of <a href="/versions/6.0.0/concepts/labels">labels</a>; optional</code></p>
The list of assets to be packaged.
This is typically a <code>glob</code> of all files under the
<code>assets</code> directory. You can also reference other rules (any rule that produces
files) or exported files in the other packages, as long as all those files are under the
<code>assets_dir</code> directory in the corresponding package.
</td>
</tr>
<tr>
<td id="android_library.assets_dir">
<code>assets_dir</code>
</td>
<td>
<p><code>String; optional</code></p>
The string giving the path to the files in <code>assets</code>.
The pair <code>assets</code> and <code>assets_dir</code> describe packaged
assets and either both attributes should be provided or none of them.
</td>
</tr>
<tr>
<td id="android_library.custom_package">
<code>custom_package</code>
</td>
<td>
<p><code>String; optional</code></p>
Java package for which java sources will be generated.
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.
</td>
</tr>
<tr>
<td id="android_library.enable_data_binding">
<code>enable_data_binding</code>
</td>
<td>
<p><code>Boolean; optional; default is False</code></p>
If true, this rule processes
<a href="https://developer.android.com/topic/libraries/data-binding/index.html">data
binding</a> expressions in layout resources included through the
<a href="/versions/6.0.0/reference/be/android.html#android_binary.resource_files">resource_files</a> attribute. Without this
setting, data binding expressions produce build failures.
<p>
To build an Android app with data binding, you must also do the following:
<ol>
<li>Set this attribute for all Android rules that transitively depend on this one.
This is because dependers inherit the rule's data binding expressions through resource
merging. So they also need to build with data binding to parse those expressions.
<li>Add a <code>deps =</code> entry for the data binding runtime library to all targets
that set this attribute. The location of this library depends on your depot setup.
</ol>
</td>
</tr>
<tr>
<td id="android_library.exported_plugins">
<code>exported_plugins</code>
</td>
<td>
<p><code>List of <a href="/versions/6.0.0/concepts/labels">labels</a>; optional</code></p>
The list of <code><a href="#/reference/be/java.html#java_plugin">java_plugin</a></code>s (e.g. annotation
processors) to export to libraries that directly depend on this library.
<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="/versions/6.0.0/reference/be/android.html#android_library.plugins">plugins</a></code>.
</p>
</td>
</tr>
<tr>
<td id="android_library.exports">
<code>exports</code>
</td>
<td>
<p><code>List of <a href="/versions/6.0.0/concepts/labels">labels</a>; optional</code></p>
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>The <code>exports</code> are not direct deps of the rule they belong to.</p>
</td>
</tr>
<tr>
<td id="android_library.exports_manifest">
<code>exports_manifest</code>
</td>
<td>
<p><code>Integer; optional; default is 1</code></p>
Whether to export manifest entries to <code>android_binary</code> targets
that depend on this target. <code>uses-permissions</code> attributes are never exported.
</td>
</tr>
<tr>
<td id="android_library.idl_import_root">
<code>idl_import_root</code>
</td>
<td>
<p><code>String; optional</code></p>
Package-relative path to the root of the java package tree containing idl
sources included in this library.
<p>This path will be used as the import root when processing idl sources that
depend on this library.</p>
<p>When <code>idl_import_root</code> is specified, both <code>idl_parcelables</code>
and <code>idl_srcs</code> must be at the path specified by the java package of the object
they represent under <code>idl_import_root</code>. When <code>idl_import_root</code> is
not specified, both <code>idl_parcelables</code> and <code>idl_srcs</code> must be at the
path specified by their package under a Java root.</p>
<p>See <a href="android.html#android_library_examples.idl_import_root">
examples</a>.</p>
</td>
</tr>
<tr>
<td id="android_library.idl_parcelables">
<code>idl_parcelables</code>
</td>
<td>
<p><code>List of <a href="/versions/6.0.0/concepts/labels">labels</a>; optional</code></p>
List of Android IDL definitions to supply as imports.
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>
<p>These files must be placed appropriately for the aidl compiler to find them.
See <a href="/versions/6.0.0/reference/be/android.html#android_library.idl_import_root">the description of idl_import_root</a>
for information about what this means.</p>
</td>
</tr>
<tr>
<td id="android_library.idl_preprocessed">
<code>idl_preprocessed</code>
</td>
<td>
<p><code>List of <a href="/versions/6.0.0/concepts/labels">labels</a>; optional</code></p>
List of preprocessed Android IDL definitions to supply as imports.
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 preprocessed <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 use <code>idl_srcs</code> for
Android IDL definitions that need to be translated to Java interfaces and
use <code>idl_parcelable</code>
for non-preprocessed AIDL files.
</p>
</td>
</tr>
<tr>
<td id="android_library.idl_srcs">
<code>idl_srcs</code>
</td>
<td>
<p><code>List of <a href="/versions/6.0.0/concepts/labels">labels</a>; optional</code></p>
List of Android IDL definitions to translate to Java interfaces.
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>
<p>These files must be placed appropriately for the aidl compiler to find them.
See <a href="/versions/6.0.0/reference/be/android.html#android_library.idl_import_root">the description of idl_import_root</a>
for information about what this means.</p>
</td>
</tr>
<tr>
<td id="android_library.javacopts">
<code>javacopts</code>
</td>
<td>
<p><code>List of strings; optional</code></p>
Extra compiler options for this target.
Subject to <a href="/versions/6.0.0/reference/be/make-variables">"Make variable"</a> substitution and
<a href="/versions/6.0.0/reference/be/common-definitions#sh-tokenization">Bourne shell tokenization</a>.
<p>
These compiler options are passed to javac after the global compiler options.</p>
</td>
</tr>
<tr>
<td id="android_library.manifest">
<code>manifest</code>
</td>
<td>
<p><code><a href="/versions/6.0.0/concepts/labels">Label</a>; optional</code></p>
The name of the Android manifest file, normally <code>AndroidManifest.xml</code>.
Must be defined if resource_files or assets are defined.
</td>
</tr>
<tr>
<td id="android_library.neverlink">
<code>neverlink</code>
</td>
<td>
<p><code>Boolean; optional; default is False</code></p>
Only use this library for compilation and not at runtime.
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.
</td>
</tr>
<tr>
<td id="android_library.plugins">
<code>plugins</code>
</td>
<td>
<p><code>List of <a href="/versions/6.0.0/concepts/labels">labels</a>; optional</code></p>
Java compiler plugins to run at compile-time.
Every <code>java_plugin</code> specified in
the plugins attribute will be run whenever
this target is built. Resources generated by
the plugin will be included in the result jar of
the target.
</td>
</tr>
<tr>
<td id="android_library.proguard_specs">
<code>proguard_specs</code>
</td>
<td>
<p><code>List of <a href="/versions/6.0.0/concepts/labels">labels</a>; optional</code></p>
Files to be used as Proguard specification.
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.
</td>
</tr>
<tr>
<td id="android_library.resource_files">
<code>resource_files</code>
</td>
<td>
<p><code>List of <a href="/versions/6.0.0/concepts/labels">labels</a>; optional</code></p>
The list of resources to be packaged.
This is typically a <code>glob</code> of all files under the
<code>res</code> directory.
<br/>
Generated files (from genrules) can be referenced by
<a href="/versions/6.0.0/concepts/labels">Label</a> here as well. The only restriction is that
the generated outputs must be under the same "<code>res</code>" directory as any other
resource files that are included.
</td>
</tr>
</tbody>
</table>
<h2 id="android_instrumentation_test">
android_instrumentation_test
</h2>
<pre class="rule-signature">android_instrumentation_test(<a href="#android_instrumentation_test.name">name</a>, <a href="common-definitions.html#typical.data">data</a>, <a href="common-definitions.html#test.args">args</a>, <a href="common-definitions.html#common.compatible_with">compatible_with</a>, <a href="common-definitions.html#common.deprecation">deprecation</a>, <a href="common-definitions.html#common.distribs">distribs</a>, <a href="common-definitions.html#test.env">env</a>, <a href="common-definitions.html#test.env_inherit">env_inherit</a>, <a href="common-definitions.html#common.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_properties">exec_properties</a>, <a href="common-definitions.html#common.features">features</a>, <a href="common-definitions.html#test.flaky">flaky</a>, <a href="common-definitions.html#typical.licenses">licenses</a>, <a href="common-definitions.html#test.local">local</a>, <a href="common-definitions.html#common.restricted_to">restricted_to</a>, <a href="common-definitions.html#test.shard_count">shard_count</a>, <a href="common-definitions.html#test.size">size</a>, <a href="#android_instrumentation_test.support_apks">support_apks</a>, <a href="common-definitions.html#common.tags">tags</a>, <a href="common-definitions.html#common.target_compatible_with">target_compatible_with</a>, <a href="#android_instrumentation_test.target_device">target_device</a>, <a href="#android_instrumentation_test.test_app">test_app</a>, <a href="common-definitions.html#common.testonly">testonly</a>, <a href="common-definitions.html#test.timeout">timeout</a>, <a href="common-definitions.html#common.toolchains">toolchains</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre>
<p>
An <code>android_instrumentation_test</code> rule runs Android instrumentation tests. It will
start an emulator, install the application being tested, the test application, and
any other needed applications, and run the tests defined in the test package.
</p>
<p>
The <a href="/versions/6.0.0/reference/be/android.html#android_instrumentation_test.test_app">test_app</a> attribute specifies the
<code>android_binary</code> which contains the test. This <code>android_binary</code> in turn
specifies the <code>android_binary</code> application under test through its
<a href="/versions/6.0.0/reference/be/android.html#android_binary.instruments">instruments</a> attribute.
</p>
<h4 id="android_instrumentation_test_examples">Example</h4>
<pre class="code">
# java/com/samples/hello_world/BUILD
android_library(
name = "hello_world_lib",
srcs = ["Lib.java"],
manifest = "LibraryManifest.xml",
resource_files = glob(["res/**"]),
)
# The app under test
android_binary(
name = "hello_world_app",
manifest = "AndroidManifest.xml",
deps = [":hello_world_lib"],
)
</pre>
<pre class="code">
# javatests/com/samples/hello_world/BUILD
android_library(
name = "hello_world_test_lib",
srcs = ["Tests.java"],
deps = [
"//java/com/samples/hello_world:hello_world_lib",
... # test dependencies such as Espresso and Mockito
],
)
# The test app
android_binary(
name = "hello_world_test_app",
instruments = "//java/com/samples/hello_world:hello_world_app",
manifest = "AndroidManifest.xml",
deps = [":hello_world_test_lib"],
)
android_instrumentation_test(
name = "hello_world_uiinstrumentation_tests",
target_device = ":some_target_device",
test_app = ":hello_world_test_app",
)
</pre>
<h3 id="android_instrumentation_test_args">Arguments</h3>
<table class="table table-condensed table-bordered table-params">
<colgroup>
<col class="col-param" />
<col class="param-description" />
</colgroup>
<thead>
<tr>
<th colspan="2">Attributes</th>
</tr>
</thead>
<tbody>
<tr>
<td id="android_instrumentation_test.name"><code>name</code></td>
<td>
<p><code><a href="/versions/6.0.0/concepts/labels#target-names">Name</a>; required</code></p>
<p>A unique name for this target.</p>
</td>
</tr>
<tr>
<td id="android_instrumentation_test.support_apks">
<code>support_apks</code>
</td>
<td>
<p><code>List of <a href="/versions/6.0.0/concepts/labels">labels</a>; optional</code></p>
Other APKs to install on the device before the instrumentation test starts.
</td>
</tr>
<tr>
<td id="android_instrumentation_test.target_device">
<code>target_device</code>
</td>
<td>
<p><code><a href="/versions/6.0.0/concepts/labels">Label</a>; required</code></p>
<p>The <a href="/versions/6.0.0/reference/be/android.html#android_device">android_device</a> the test should run on.</p>
<p>To run the test on an emulator that is already running or on a physical device, use
these arguments:
<code>--test_output=streamed --test_arg=--device_broker_type=LOCAL_ADB_SERVER
--test_arg=--device_serial_number=$device_identifier</code></p>
</td>
</tr>
<tr>
<td id="android_instrumentation_test.test_app">
<code>test_app</code>
</td>
<td>
<p><code><a href="/versions/6.0.0/concepts/labels">Label</a>; required</code></p>
The <a href="/versions/6.0.0/reference/be/android.html#android_binary">android_binary</a> target containing the test classes.
The <code>android_binary</code> target must specify which target it is testing through
its <a href="/versions/6.0.0/reference/be/android.html#android_binary.instruments"><code>instruments</code></a> attribute.
</td>
</tr>
</tbody>
</table>
<h2 id="android_local_test">
android_local_test
</h2>
<pre class="rule-signature">android_local_test(<a href="#android_local_test.name">name</a>, <a href="#android_local_test.deps">deps</a>, <a href="#android_local_test.srcs">srcs</a>, <a href="common-definitions.html#typical.data">data</a>, <a href="common-definitions.html#test.args">args</a>, <a href="common-definitions.html#common.compatible_with">compatible_with</a>, <a href="#android_local_test.custom_package">custom_package</a>, <a href="#android_local_test.densities">densities</a>, <a href="common-definitions.html#common.deprecation">deprecation</a>, <a href="#android_local_test.enable_data_binding">enable_data_binding</a>, <a href="common-definitions.html#test.env">env</a>, <a href="common-definitions.html#test.env_inherit">env_inherit</a>, <a href="common-definitions.html#common.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_properties">exec_properties</a>, <a href="common-definitions.html#common.features">features</a>, <a href="common-definitions.html#test.flaky">flaky</a>, <a href="#android_local_test.javacopts">javacopts</a>, <a href="#android_local_test.jvm_flags">jvm_flags</a>, <a href="common-definitions.html#typical.licenses">licenses</a>, <a href="common-definitions.html#test.local">local</a>, <a href="#android_local_test.manifest">manifest</a>, <a href="#android_local_test.manifest_values">manifest_values</a>, <a href="#android_local_test.nocompress_extensions">nocompress_extensions</a>, <a href="#android_local_test.plugins">plugins</a>, <a href="#android_local_test.resource_configuration_filters">resource_configuration_filters</a>, <a href="#android_local_test.resource_jars">resource_jars</a>, <a href="#android_local_test.resource_strip_prefix">resource_strip_prefix</a>, <a href="common-definitions.html#common.restricted_to">restricted_to</a>, <a href="#android_local_test.runtime_deps">runtime_deps</a>, <a href="common-definitions.html#test.shard_count">shard_count</a>, <a href="common-definitions.html#test.size">size</a>, <a href="#android_local_test.stamp">stamp</a>, <a href="common-definitions.html#common.tags">tags</a>, <a href="common-definitions.html#common.target_compatible_with">target_compatible_with</a>, <a href="#android_local_test.test_class">test_class</a>, <a href="common-definitions.html#common.testonly">testonly</a>, <a href="common-definitions.html#test.timeout">timeout</a>, <a href="common-definitions.html#common.toolchains">toolchains</a>, <a href="#android_local_test.use_launcher">use_launcher</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre>
<p>
This rule is for unit testing <code>android_library</code> rules locally
(as opposed to on a device).
It works with the Android Robolectric testing framework.
See the <a href="http://robolectric.org/">Android Robolectric</a> site for details about
writing Robolectric tests.
</p>
<h4 id="android_local_test_implicit_outputs">Implicit output targets</h4>
<ul>
<li><code><var>name</var>.jar</code>: A Java archive of the test.</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 deploy archive suitable
for deployment (only built if explicitly requested).</li>
</ul>
<h4 id="android_local_test_examples">Examples</h4>
<p>
To use Robolectric with <code>android_local_test</code>, add
<a href="https://github.com/robolectric/robolectric-bazel/tree/master/bazel">Robolectric's
repository</a> to your <code>WORKSPACE</code> file:
<pre class="code">
http_archive(
name = "robolectric",
urls = ["https://github.com/robolectric/robolectric/archive/&lt;COMMIT&gt;.tar.gz"],
strip_prefix = "robolectric-&lt;COMMIT&gt;",
sha256 = "&lt;HASH&gt;",
)
load("@robolectric//bazel:robolectric.bzl", "robolectric_repositories")
robolectric_repositories()
</pre>
This pulls in the <code>maven_jar</code> rules needed for Robolectric.
Then each <code>android_local_test</code> rule should depend on
<code>@robolectric//bazel:robolectric</code>. See example below.
</p>
<pre class="code">
android_local_test(
name = "SampleTest",
srcs = [
"SampleTest.java",
],
manifest = "LibManifest.xml",
deps = [
":sample_test_lib",
"@robolectric//bazel:robolectric",
],
)
android_library(
name = "sample_test_lib",
srcs = [
"Lib.java",
],
resource_files = glob(["res/**"]),
manifest = "AndroidManifest.xml",
)
</pre>
<h3 id="android_local_test_args">Arguments</h3>
<table class="table table-condensed table-bordered table-params">
<colgroup>
<col class="col-param" />
<col class="param-description" />
</colgroup>
<thead>
<tr>
<th colspan="2">Attributes</th>
</tr>
</thead>
<tbody>
<tr>
<td id="android_local_test.name"><code>name</code></td>
<td>
<p><code><a href="/versions/6.0.0/concepts/labels#target-names">Name</a>; required</code></p>
<p>A unique name for this target.</p>
</td>
</tr>
<tr>
<td id="android_local_test.deps">
<code>deps</code>
</td>
<td>
<p><code>List of <a href="/versions/6.0.0/concepts/labels">labels</a>; optional</code></p>
The list of libraries to be tested as well as additional libraries to be linked
in to the target.
All resources, assets and manifest files declared in Android rules in the transitive
closure of this attribute are made available in the test.
<p>
The list of allowed rules in <code>deps</code> are <code>android_library</code>,
<code>aar_import</code>, <code>java_import</code>, <code>java_library</code>,
and <code>java_lite_proto_library</code>.
</td>
</tr>
<tr>
<td id="android_local_test.srcs">
<code>srcs</code>
</td>
<td>
<p><code>List of <a href="/versions/6.0.0/concepts/labels">labels</a>; optional</code></p>
The list of source files that are processed to create the target.
Required except in special case described below.
<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>All other files are ignored, as long as
there is at least one file of a file type described above. Otherwise an
error is raised.
</p>
<p>
The <code>srcs</code> attribute is required and cannot be empty, unless
<code>runtime_deps</code> is specified.
</p>
</td>
</tr>
<tr>
<td id="android_local_test.custom_package">
<code>custom_package</code>
</td>
<td>
<p><code>String; optional</code></p>
Java package in which the R class will be generated. By default the package is inferred
from the directory where the BUILD file containing the rule is. If you use this attribute,
you will likely need to use <code>test_class</code> as well.
</td>
</tr>
<tr>
<td id="android_local_test.densities">
<code>densities</code>
</td>
<td>
<p><code>List of strings; optional</code></p>
Densities to filter for when building the apk. A corresponding compatible-screens
section will also be added to the manifest if it does not already contain a
superset StarlarkListing.
</td>
</tr>
<tr>
<td id="android_local_test.enable_data_binding">
<code>enable_data_binding</code>
</td>
<td>
<p><code>Boolean; optional; default is False</code></p>
If true, this rule processes
<a href="https://developer.android.com/topic/libraries/data-binding/index.html">data
binding</a> references used in data-binding enabled dependencies used by this test. Without
this setting, data-binding dependencies won't have necessary binary-level code generation,
and may produce build failures.
</td>
</tr>
<tr>
<td id="android_local_test.javacopts">
<code>javacopts</code>
</td>
<td>
<p><code>List of strings; optional</code></p>
Extra compiler options for this library.
Subject to <a href="make-variables.html">"Make variable"</a> substitution and
<a href="common-definitions.html#sh-tokenization">Bourne shell tokenization</a>.
<p>These compiler options are passed to javac after the global compiler options.</p>
</td>
</tr>
<tr>
<td id="android_local_test.jvm_flags">
<code>jvm_flags</code>
</td>
<td>
<p><code>List of strings; optional</code></p>
A list of flags to embed in the wrapper script generated for running this binary.
Subject to <a href="/versions/6.0.0/reference/be/make-variables#location">$(location)</a> and
<a href="make-variables.html">"Make variable"</a> substitution, and
<a href="common-definitions.html#sh-tokenization">Bourne shell tokenization</a>.
<p>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.</p>
<p>Note that this attribute has <em>no effect</em> on <code>*_deploy.jar</code>
outputs.</p>
</td>
</tr>
<tr>
<td id="android_local_test.manifest">
<code>manifest</code>
</td>
<td>
<p><code><a href="/versions/6.0.0/concepts/labels">Label</a>; optional</code></p>
The name of the Android manifest file, normally <code>AndroidManifest.xml</code>.
Must be defined if resource_files or assets are defined or if any of the manifests from
the libraries under test have a <code>minSdkVersion</code> tag in them.
</td>
</tr>
<tr>
<td id="android_local_test.manifest_values">
<code>manifest_values</code>
</td>
<td>
<p><code>Dictionary: String -> String; optional</code></p>
A dictionary of values to be overridden in the manifest. Any instance of ${name} in the
manifest will be replaced with the value corresponding to name in this dictionary.
<code>applicationId</code>, <code>versionCode</code>, <code>versionName</code>,
<code>minSdkVersion</code>, <code>targetSdkVersion</code> and
<code>maxSdkVersion</code> will also override the corresponding attributes
of the manifest and
uses-sdk tags. <code>packageName</code> will be ignored and will be set from either
<code>applicationId</code> if
specified or the package in the manifest.
It is not necessary to have a manifest on the rule in order to use manifest_values.
</td>
</tr>
<tr>
<td id="android_local_test.nocompress_extensions">
<code>nocompress_extensions</code>
</td>
<td>
<p><code>List of strings; optional</code></p>
A list of file extensions to leave uncompressed in the resource apk.
</td>
</tr>
<tr>
<td id="android_local_test.plugins">
<code>plugins</code>
</td>
<td>
<p><code>List of <a href="/versions/6.0.0/concepts/labels">labels</a>; optional</code></p>
Java compiler plugins to run at compile-time.
Every <code>java_plugin</code> specified in this attribute will be run whenever this rule
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 resulting jar of this rule.
</td>
</tr>
<tr>
<td id="android_local_test.resource_configuration_filters">
<code>resource_configuration_filters</code>
</td>
<td>
<p><code>List of strings; optional</code></p>
A list of resource configuration filters, such as 'en' that will limit the resources in the
apk to only the ones in the 'en' configuration.
</td>
</tr>
<tr>
<td id="android_local_test.resource_jars">
<code>resource_jars</code>
</td>
<td>
<p><code>List of <a href="/versions/6.0.0/concepts/labels">labels</a>; optional</code></p>
Deprecated: Use java_import and deps or runtime_deps instead.
</td>
</tr>
<tr>
<td id="android_local_test.resource_strip_prefix">
<code>resource_strip_prefix</code>
</td>
<td>
<p><code>String; optional</code></p>
The path prefix to strip from Java resources.
<p>
If specified, this path prefix is stripped from every file in the <code>resources</code>
attribute. It is an error for a resource file not to be under this directory. If not
specified (the default), the path of resource file is determined according to the same
logic as the Java package of source files. For example, a source file at
<code>stuff/java/foo/bar/a.txt</code> will be located at <code>foo/bar/a.txt</code>.
</p>
</td>
</tr>
<tr>
<td id="android_local_test.runtime_deps">
<code>runtime_deps</code>
</td>
<td>
<p><code>List of <a href="/versions/6.0.0/concepts/labels">labels</a>; optional</code></p>
Libraries to make available to the final binary or test at runtime only.
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
listed here. Dependency-analysis tools should ignore targets that appear in both
<code>runtime_deps</code> and <code>deps</code>.
</td>
</tr>
<tr>
<td id="android_local_test.stamp">
<code>stamp</code>
</td>
<td>
<p><code>Integer; optional; default is 0</code></p>
Whether to encode build information into the binary. Possible values:
<ul>
<li>
<code>stamp = 1</code>: Always stamp the build information into the binary, even in
<a href="/versions/6.0.0/docs/user-manual#flag--stamp"><code>--nostamp</code></a> builds. <b>This
setting should be avoided</b>, since it potentially kills remote caching for the
binary and any downstream actions that depend on it.
</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="/versions/6.0.0/docs/user-manual#flag--stamp"><code>--[no]stamp</code></a> flag.
</li>
</ul>
<p>Stamped binaries are <em>not</em> rebuilt unless their dependencies change.</p>
</td>
</tr>
<tr>
<td id="android_local_test.test_class">
<code>test_class</code>
</td>
<td>
<p><code>String; optional</code></p>
The Java class to be loaded by the test runner.<br/>
<p>
This attribute specifies the name of a Java class to be run by
this test. It is rare to need to set this. If this argument is omitted, the Java class
whose name corresponds to the <code>name</code> of this
<code>android_local_test</code> rule will be used.
The test class needs to be annotated with <code>org.junit.runner.RunWith</code>.
</p>
</td>
</tr>
<tr>
<td id="android_local_test.use_launcher">
<code>use_launcher</code>
</td>
<td>
<p><code>Boolean; optional; default is True</code></p>
Whether the binary should use a custom launcher.
<p>If this attribute is set to false, the
<a href="/versions/6.0.0/reference/be/java.html#java_binary.launcher">launcher</a> attribute and the related
<a href="/versions/6.0.0/docs/user-manual#flag--java_launcher"><code>--java_launcher</code></a> flag
will be ignored for this target.
</td>
</tr>
</tbody>
</table>
<h2 id="android_device">
android_device
</h2>
<pre class="rule-signature">android_device(<a href="#android_device.name">name</a>, <a href="#android_device.cache">cache</a>, <a href="common-definitions.html#common.compatible_with">compatible_with</a>, <a href="#android_device.default_properties">default_properties</a>, <a href="common-definitions.html#common.deprecation">deprecation</a>, <a href="common-definitions.html#common.distribs">distribs</a>, <a href="common-definitions.html#common.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_properties">exec_properties</a>, <a href="common-definitions.html#common.features">features</a>, <a href="#android_device.horizontal_resolution">horizontal_resolution</a>, <a href="common-definitions.html#typical.licenses">licenses</a>, <a href="#android_device.platform_apks">platform_apks</a>, <a href="#android_device.ram">ram</a>, <a href="common-definitions.html#common.restricted_to">restricted_to</a>, <a href="#android_device.screen_density">screen_density</a>, <a href="#android_device.system_image">system_image</a>, <a href="common-definitions.html#common.tags">tags</a>, <a href="common-definitions.html#common.target_compatible_with">target_compatible_with</a>, <a href="common-definitions.html#common.testonly">testonly</a>, <a href="#android_device.vertical_resolution">vertical_resolution</a>, <a href="common-definitions.html#common.visibility">visibility</a>, <a href="#android_device.vm_heap">vm_heap</a>)</pre>
<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. It is encouraged to depend
on existing android_device rules rather than defining your own.
</p>
<p>This rule is a suitable target for the --run_under flag to bazel test and blaze
run. It starts an emulator, copies the target being tested/run to the emulator,
and tests it or runs it as appropriate.
</p>
<p><code>android_device</code> supports creating KVM images if the underlying
<a href="/versions/6.0.0/reference/be/android.html#android_device.system_image">system_image</a> is X86 based and is
optimized for at most the I686 CPU architecture. To use KVM add
<code> tags = ['requires-kvm'] </code> to the <code>android_device</code> rule.
</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_examples">Examples</h4>
<p>The following example shows how to use android_device.
<code>//java/android/helloandroid/BUILD</code> contains</p>
<pre class="code">
android_device(
name = "nexus_s",
cache = 32,
default_properties = "nexus_s.properties",
horizontal_resolution = 480,
ram = 512,
screen_density = 233,
system_image = ":emulator_images_android_16_x86",
vertical_resolution = 800,
vm_heap = 32,
)
filegroup(
name = "emulator_images_android_16_x86",
srcs = glob(["androidsdk/system-images/android-16/**"]),
)
</pre>
<p><code>//java/android/helloandroid/nexus_s.properties</code> contains:</p>
<pre class="code">
ro.product.brand=google
ro.product.device=crespo
ro.product.manufacturer=samsung
ro.product.model=Nexus S
ro.product.name=soju
</pre>
<p>
This rule will generate images and a start script. You can start the emulator
locally by executing bazel run :nexus_s -- --action=start. The script exposes
the following flags:
</p>
<ul>
<li>--adb_port: The port to expose adb on. If you wish to issue adb
commands to the emulator this is the port you will issue adb connect
to.</li>
<li>--emulator_port: The port to expose the emulator's telnet management
console on.</li>
<li>--enable_display: Starts the emulator with a display if true (defaults
to false).</li>
<li>--action: Either start or kill.</li>
<li>--apks_to_install: a list of apks to install on the emulator.</li>
</ul>
<h3 id="android_device_args">Arguments</h3>
<table class="table table-condensed table-bordered table-params">
<colgroup>
<col class="col-param" />
<col class="param-description" />
</colgroup>
<thead>
<tr>
<th colspan="2">Attributes</th>
</tr>
</thead>
<tbody>
<tr>
<td id="android_device.name"><code>name</code></td>
<td>
<p><code><a href="/versions/6.0.0/concepts/labels#target-names">Name</a>; required</code></p>
<p>A unique name for this target.</p>
</td>
</tr>
<tr>
<td id="android_device.cache">
<code>cache</code>
</td>
<td>
<p><code>Integer; required</code></p>
The size in megabytes of the emulator's cache partition.
The minimum value of this is 16 megabytes.
</td>
</tr>
<tr>
<td id="android_device.default_properties">
<code>default_properties</code>
</td>
<td>
<p><code><a href="/versions/6.0.0/concepts/labels">Label</a>; optional</code></p>
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.
</td>
</tr>
<tr>
<td id="android_device.horizontal_resolution">
<code>horizontal_resolution</code>
</td>
<td>
<p><code>Integer; required</code></p>
The horizontal screen resolution in pixels to emulate.
The minimum value is 240.
</td>
</tr>
<tr>
<td id="android_device.platform_apks">
<code>platform_apks</code>
</td>
<td>
<p><code>List of <a href="/versions/6.0.0/concepts/labels">labels</a>; optional</code></p>
A list of apks to be installed on the device at boot time.
</td>
</tr>
<tr>
<td id="android_device.ram">
<code>ram</code>
</td>
<td>
<p><code>Integer; required</code></p>
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.
</td>
</tr>
<tr>
<td id="android_device.screen_density">
<code>screen_density</code>
</td>
<td>
<p><code>Integer; required</code></p>
The density of the emulated screen in pixels per inch.
The minimum value of this is 30 ppi.
</td>
</tr>
<tr>
<td id="android_device.system_image">
<code>system_image</code>
</td>
<td>
<p><code><a href="/versions/6.0.0/concepts/labels">Label</a>; required</code></p>
A filegroup containing the following files:
<ul>
<li>system.img: The system partition</li>
<li>kernel-qemu: The Linux kernel the emulator 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).
</td>
</tr>
<tr>
<td id="android_device.vertical_resolution">
<code>vertical_resolution</code>
</td>
<td>
<p><code>Integer; required</code></p>
The vertical screen resolution in pixels to emulate.
The minimum value is 240.
</td>
</tr>
<tr>
<td id="android_device.vm_heap">
<code>vm_heap</code>
</td>
<td>
<p><code>Integer; required</code></p>
The size in megabytes of the virtual machine heap Android will use for each process.
The minimum value is 16 megabytes.
</td>
</tr>
</tbody>
</table>
<h2 id="android_ndk_repository">
android_ndk_repository
</h2>
<pre class="rule-signature">android_ndk_repository(<a href="#android_ndk_repository.name">name</a>, <a href="#android_ndk_repository.api_level">api_level</a>, <a href="#android_ndk_repository.path">path</a>, <a href="#android_ndk_repository.repo_mapping">repo_mapping</a>)</pre>
<p>Configures Bazel to use an Android NDK to support building Android targets with native
code.
<p>Note that building for Android also requires an <code>android_sdk_repository</code> rule in your
<code>WORKSPACE</code> file.
<p>
For more information, read the <a href="https://bazel.build/versions/6.0.0/docs/android-ndk">
full documentation on using Android NDK with Bazel</a>.
</p>
<h4 id="android_ndk_repository_examples">Examples</h4>
<pre class="code">
android_ndk_repository(
name = "androidndk",
)
</pre>
<p>The above example will locate your Android NDK from <code>$ANDROID_NDK_HOME</code> and detect
the highest API level that it supports.
<pre class="code">
android_ndk_repository(
name = "androidndk",
path = "./android-ndk-r20",
api_level = 24,
)
</pre>
<p>The above example will use the Android NDK located inside your workspace in
<code>./android-ndk-r20</code>. It will use the API level 24 libraries when compiling your JNI
code.
<h4 id="android_ndk_repository_cpufeatures">cpufeatures</h4>
<p>The Android NDK contains the
<a href="https://developer.android.com/ndk/guides/cpu-features.html">cpufeatures library</a>
which can be used to detect a device's CPU at runtime. The following example demonstrates how to use
cpufeatures with Bazel.
<pre class="code">
# jni.cc
#include "ndk/sources/android/cpufeatures/cpu-features.h"
...
</pre>
<pre class="code">
# BUILD
cc_library(
name = "jni",
srcs = ["jni.cc"],
deps = ["@androidndk//:cpufeatures"],
)
</pre>
<h3 id="android_ndk_repository_args">Arguments</h3>
<table class="table table-condensed table-bordered table-params">
<colgroup>
<col class="col-param" />
<col class="param-description" />
</colgroup>
<thead>
<tr>
<th colspan="2">Attributes</th>
</tr>
</thead>
<tbody>
<tr>
<td id="android_ndk_repository.name"><code>name</code></td>
<td>
<p><code><a href="/versions/6.0.0/concepts/labels#target-names">Name</a>; required</code></p>
<p>A unique name for this target.</p>
</td>
</tr>
<tr>
<td id="android_ndk_repository.api_level">
<code>api_level</code>
</td>
<td>
<p><code>Integer; optional; <a href="common-definitions.html#configurable-attributes">nonconfigurable</a>; default is 0</code></p>
The Android API level to build against. If not specified, the highest API level installed
will be used.
</td>
</tr>
<tr>
<td id="android_ndk_repository.path">
<code>path</code>
</td>
<td>
<p><code>String; optional; <a href="common-definitions.html#configurable-attributes">nonconfigurable</a></code></p>
An absolute or relative path to an Android NDK. Either this attribute or the
<code>$ANDROID_NDK_HOME</code> environment variable must be set.
<p>The Android NDK can be downloaded from
<a href='https://developer.android.com/ndk/downloads/index.html'>the Android developer site
</a>.
</td>
</tr>
<tr>
<td id="android_ndk_repository.repo_mapping">
<code>repo_mapping</code>
</td>
<td>
<p><code>Dictionary: String -> String; optional</code></p>
A dictionary from local repository name to global repository name. This allows controls over
workspace dependency resolution for dependencies of this repository.
<p>For example, an entry <code>"@foo": "@bar"</code> declares that, for any time this
repository depends on <code>"@foo"</code> (such as a dependency on
<code>"@foo//some:target"</code>), it should actually resolve that dependency within
globally-declared <code>"@bar"</code> (<code>"@bar//some:target"</code>).
</td>
</tr>
</tbody>
</table>
<h2 id="android_sdk_repository">
android_sdk_repository
</h2>
<pre class="rule-signature">android_sdk_repository(<a href="#android_sdk_repository.name">name</a>, <a href="#android_sdk_repository.api_level">api_level</a>, <a href="#android_sdk_repository.build_tools_version">build_tools_version</a>, <a href="#android_sdk_repository.path">path</a>, <a href="#android_sdk_repository.repo_mapping">repo_mapping</a>)</pre>
<p>Configures Bazel to use a local Android SDK to support building Android targets.</p>
<h4 id="android_sdk_repository_examples">Examples</h4>
The minimum to set up an Android SDK for Bazel is to put an <code>android_sdk_repository</code> rule
named "androidsdk" in your <code>WORKSPACE</code> file and set the <code>$ANDROID_HOME</code>
environment variable to the path of your Android SDK. Bazel will use the highest Android API level
and build tools version installed in the Android SDK by default.
<pre class="code">
android_sdk_repository(
name = "androidsdk",
)
</pre>
<p>To ensure reproducible builds, the <code>path</code>, <code>api_level</code> and
<code>build_tools_version</code> attributes can be set to specific values. The build will fail if
the Android SDK does not have the specified API level or build tools version installed.
<pre class="code">
android_sdk_repository(
name = "androidsdk",
path = "./sdk",
api_level = 19,
build_tools_version = "25.0.0",
)
</pre>
<p>The above example also demonstrates using a workspace-relative path to the Android SDK. This is
useful if the Android SDK is part of your Bazel workspace (e.g. if it is checked into version
control).
<h4 id="android_sdk_repository_support_libraries">Support Libraries</h4>
<p>The Support Libraries are available in the Android SDK Manager as "Android Support Repository".
This is a versioned set of common Android libraries, such as the Support and AppCompat libraries,
that is packaged as a local Maven repository. <code>android_sdk_repository</code> generates Bazel
targets for each of these libraries that can be used in the dependencies of
<code>android_binary</code> and <code>android_library</code> targets.
<p>The names of the generated targets are derived from the Maven coordinates of the libraries in the
Android Support Repository, formatted as <code>@androidsdk//${group}:${artifact}-${version}</code>.
The following example shows how an <code>android_library</code> can depend on version 25.0.0 of the
v7 appcompat library.
<pre class="code">
android_library(
name = "lib",
srcs = glob(["*.java"]),
manifest = "AndroidManifest.xml",
resource_files = glob(["res/**"]),
deps = ["@androidsdk//com.android.support:appcompat-v7-25.0.0"],
)
</pre>
<h3 id="android_sdk_repository_args">Arguments</h3>
<table class="table table-condensed table-bordered table-params">
<colgroup>
<col class="col-param" />
<col class="param-description" />
</colgroup>
<thead>
<tr>
<th colspan="2">Attributes</th>
</tr>
</thead>
<tbody>
<tr>
<td id="android_sdk_repository.name"><code>name</code></td>
<td>
<p><code><a href="/versions/6.0.0/concepts/labels#target-names">Name</a>; required</code></p>
<p>A unique name for this target.</p>
</td>
</tr>
<tr>
<td id="android_sdk_repository.api_level">
<code>api_level</code>
</td>
<td>
<p><code>Integer; optional; <a href="common-definitions.html#configurable-attributes">nonconfigurable</a>; default is 0</code></p>
The Android API level to build against by default. If not specified, the highest API level
installed will be used.
<p>The API level used for a given build can be overridden by the <code>android_sdk</code>
flag. <code>android_sdk_repository</code> creates an <code>android_sdk</code> target for
each API level installed in the SDK with name <code>@androidsdk//:sdk-${level}</code>,
whether or not this attribute is specified. For example, to build against a non-default API
level: <code>bazel build --android_sdk=@androidsdk//:sdk-19 //java/com/example:app</code>.
<p>To view all <code>android_sdk</code> targets generated by <code>android_sdk_repository
</code>, you can run <code>bazel query "kind(android_sdk, @androidsdk//...)"</code>.
</td>
</tr>
<tr>
<td id="android_sdk_repository.build_tools_version">
<code>build_tools_version</code>
</td>
<td>
<p><code>String; optional; <a href="common-definitions.html#configurable-attributes">nonconfigurable</a></code></p>
The version of the Android build tools to use from within the Android SDK. If not specified,
the latest build tools version installed will be used.
<p>Bazel requires build tools version 30.0.0 or later.
</td>
</tr>
<tr>
<td id="android_sdk_repository.path">
<code>path</code>
</td>
<td>
<p><code>String; optional; <a href="common-definitions.html#configurable-attributes">nonconfigurable</a></code></p>
An absolute or relative path to an Android SDK. Either this attribute or the
<code>$ANDROID_HOME</code> environment variable must be set.
<p>The Android SDK can be downloaded from
<a href='https://developer.android.com'>the Android developer site</a>.
</td>
</tr>
<tr>
<td id="android_sdk_repository.repo_mapping">
<code>repo_mapping</code>
</td>
<td>
<p><code>Dictionary: String -> String; optional</code></p>
A dictionary from local repository name to global repository name. This allows controls over
workspace dependency resolution for dependencies of this repository.
<p>For example, an entry <code>"@foo": "@bar"</code> declares that, for any time this
repository depends on <code>"@foo"</code> (such as a dependency on
<code>"@foo//some:target"</code>), it should actually resolve that dependency within
globally-declared <code>"@bar"</code> (<code>"@bar//some:target"</code>).
</td>
</tr>
</tbody>
</table>
<!-- Generated footer -->
</body>
</html>