blob: a38498d15399b3a97005a429dbe9c9f1ed0c2dc0 [file] [log] [blame]
/*
* Copyright (c) Facebook, Inc. and its affiliates.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
{namespace android_binary}
/***/
{template .soyweb}
{call buck.page}
{param title: 'android_binary()' /}
{param navid: 'rule_android_binary' /}
{param prettify: true /}
{param description}
A rule that generates an Android APK.
{/param}
{param content}
{call buck.rule}
{param status: 'FROZEN' /}
{param overview}
<p>
An <code>android_binary()</code> rule is used to generate an Android APK.
</p>
{/param}
{param args}
{call buck.arg}
{param name: 'name' /}
{param desc}
The <em>short name</em> for this {call buck.build_target /}.
Also, the name of the APK generated from this target.
{/param}
{/call}
{call android_common.manifest_apk_arg /}
{call buck.arg}
{param name: 'keystore' /}
{param desc}
A build target that identifies a {call buck.keystore /} to use to
sign the APK.
{/param}
{/call}
{call buck.arg}
{param name : 'package_type' /}
{param default : '\'debug\'' /}
{param desc}
Determines whether ProGuard will be used when packaging the APK.
Acceptable values for <code>package_type</code> are <code>'debug'</code> and
<code>'release'</code>. The default value is <code>'debug'</code>,
which indicates that ProGuard should not be used.
<p>
// t2272739
<strong>Note:</strong> This argument will be renamed to reflect that
it determines the use of ProGuard.
{/param}
{/call}
{call buck.arg}
{param name : 'proguard_config' /}
{param default : 'None' /}
{param desc}
Relative path to a ProGuard configuration file that will be passed
via the <code>-include</code> flag when <code>package_type</code> is
{sp}<code>'release'</code>.
{/param}
{/call}
{call buck.arg}
{param name : 'android_sdk_proguard_config' /}
{param default : '\'default\'' /}
{param desc}
The type of proguard configuration to use from the Android SDK.
Options are <code>'default'</code> to use the default config,
<code>'optimized'</code> to use the config with optimizations enabled,
or <code>'none'</code> to not use any standard configuration
(you will need to supply your own version, otherwise your
app will probably not work).
{/param}
{/call}
{call buck.arg}
{param name : 'ignore_aapt_proguard_config' /}
{param default : 'False' /}
{param desc}
If true, the proguard config automatically generated by <code>aapt</code> will be ignored.
{/param}
{/call}
{call buck.arg}
{param name : 'no_dx' /}
{param default : '[]' /}
{param desc}
List of build targets that may have been included during compilation of {sp}
the transitive <code>android_library()</code> and{sp}
<code>java_library()</code> dependencies, but should not be included{sp}
in the <code>classes.dex</code> for generated for the APK.
{/param}
{/call}
{call buck.arg}
{param name : 'build_config_values' /}
{param default : '[]' /}
{param desc}
See the documentation on the <tt>values</tt> argument for {call buck.android_build_config /}.
{/param}
{/call}
{call buck.arg}
{param name : 'build_config_values_file' /}
{param default : 'None' /}
{param desc}
See the documentation on the <tt>values_file</tt> argument for {call buck.android_build_config /}.
{/param}
{/call}
{call buck.arg}
{param name : 'aapt_mode' /}
{param default : 'aapt1' /}
{param desc}
Set to <code>"aapt2"</code> to build resources for this app with aapt2.
{/param}
{/call}
{call buck.arg}
{param name : 'skip_crunch_pngs' /}
{param default : 'False' /}
{param desc}
If <code>True</code>, PNGs in the APK are not crushed by aapt.
This is equivalent to specifying
{literal}<pre class="prettyprint lang-js">
android {
aaptOptions.useAaptPngCruncher = false
}
</pre>{/literal}
in gradle, or
{literal}<pre class="prettyprint lang-xml">
&lt;target name="-crunch">
&lt;echo message="Skipping PNG optimization"/>
&lt;/target>
</pre>{/literal}
in ant.
This can be useful if the PNGs have
been optimised beforehand, as aapt would attempt to crush the optimised PNGs and end up increasing
their size instead of decreasing it.
{/param}
{/call}
{call buck.arg}
{param name : 'duplicate_resource_behavior' /}
{param default : 'allow_by_default' /}
{param desc}
If set to <code>"ban_by_default"</code>, duplicate resource definitions
with the same type and name will cause the build to fail,
unless they are excluded by <code>allowed_duplicate_resource_types</code>
or <code>duplicate_resource_whitelist</code>.
If set to <code>"allow_by_default"</code> (the default),
no duplicate resource checks will be performed.
They can still be enabled on individual types
by using <code>banned_duplicate_resource_types</code>.
{/param}
{/call}
{call buck.arg}
{param name : 'banned_duplicate_resource_types' /}
{param default : '[]' /}
{param desc}
If <code>['string']</code> is used, the build will break if multiple string resources with the same name are added in an app's Android Resources.
Resource names are name-spaced by resource type, this does not enforce unique names between multiple resource types.
AAPT does not enforce this, but you can prevent easy-to-introduce resource bugs by enabling this.
{/param}
{/call}
{call buck.arg}
{param name : 'allowed_duplicate_resource_types' /}
{param default : '[]' /}
{param desc}
Similar to <code>banned_duplicate_resource_types</code>, but lists the types
that are allowed to have duplicates.
This should only be used if <code>duplicate_resource_behavior</code> is <code>"ban_by_default"</code>.
{/param}
{/call}
{call buck.arg}
{param name : 'duplicate_resource_whitelist' /}
{param default : 'None' /}
{param desc}
Either a {call buck.build_target /} or a path to a file
containing a whitelist of resources that should be excluded from duplicate resource detection.
Format is one resource per line with the type followed by the name, separated by a space.
For example, <code>string app_name</code>.
{/param}
{/call}
{call buck.arg}
{param name : 'includes_vector_drawables' /}
{param default : 'False' /}
{param desc}
When calling AAPT during the packaging process, pass the <code>
--no-version-vectors</code> flag which ensures that any vector drawables
which make use of the Android support library are backwards compatible
with Android 4.4 and earlier.
{/param}
{/call}
{call buck.arg}
{param name : 'manifest_entries' /}
{{param default : '{}' /}}
{param desc}
Insert values into the packaged <code>AndroidManifest.xml</code> file.
Valid values are <code>min_sdk_version</code>, <code>target_sdk_version</code>,
<code>version_code</code>, <code>version_name</code>, and <code>debug_mode</code>. Example:
{literal}<pre class="prettyprint lang-py">
android_binary(
# ... other args ...
manifest_entries = {
'version_code': 12,
'version_name': '2.0',
'min_sdk_version': 16,
'target_sdk_version': 23,
'debug_mode': True,
}
)
</pre>{/literal}
This is equivalent to specifying
{literal}<pre class="prettyprint lang-js">
android {
defaultConfig {
versionCode 12
versionName "2.0"
minSdkVersion 16
targetSdkVersion 23
}
}
</pre>{/literal}
in gradle and building the debug <code>BuildType</code>.
This is especially useful when combined with
the <a href="{ROOT}function/flatten_dicts.html"><code>flatten_dicts</code></a> function. This will
allow you to share a default config across your rules, and override values as necessary.
{/param}
{/call}
{call android_common.deps_apk_arg /}
{call buck.arg}
{param name : 'cpu_filters' /}
{param default : '[]' /}
{param desc}
The CPU architecture filter applied to the final apk. Could be a subset of <code>ARM</code>,
{sp}<code>ARMV7</code>, <code>ARM64</code>, <code>X86</code>, <code>X86_64</code>, <code>MIPS</code>.
<p>
<strong>Note</strong>: If you set this parameter, you must setup your NDK, otherwise BUCK
build will fail. You can follow the Android SDK and NDK part of the
{sp}<a href="{ROOT}setup/install.html">install guide</a> to set it up.
</p>
{/param}
{/call}
{call buck.arg}
{param name : 'use_split_dex' /}
{param default : 'False' /}
{param desc}
<p>
If this argument is <code>True</code>, Buck enables <em>multidex</em> support for
the output APK. Multidex support enables your app to use multiple
Dalvik Executable (DEX) bytecode files and thereby work around the 64K
limit on the number of methods that can be referenced in a single DEX
file.
</p>
<p>
<pre>
{literal}
use_split_dex = True
{/literal}
</pre>
</p>
<p>
For more information on multidex support, go to
the <a href="https://developer.android.com/studio/build/multidex">Android Developer Documentation</a>.
</p>
{/param}
{/call}
{call buck.arg}
{param name : 'application_module_configs' /}
{param default : '[]' /}
{param desc}
<p>
A map of module names to lists of targets, where the targets should <em>seed</em> the corresponding module. The seed
targets and their exclusive dependencies are packaged into the APK in separate files to allow
them to be loaded independently.
</p>
{/param}
{/call}
{call buck.arg}
{param name : 'linear_alloc_hard_limit' /}
{param default : '4194304' /}
{param desc}
The size at which secondary dex files should be split when building an
{sp}<a href="{ROOT}article/exopackage.html">exopackage</a> in bytes.
<p>
It is set 4MB by default, because Android 2.3 has a LinearAlloc limit of 5MB and 1MB is taken up
by the framework. More recent versions of Android have a LinearAlloc limit of 8MB or 16MB, so
if the APK is only targeted for versions newer than 2.3, a 7MB limit is safe to use.
</p>
{/param}
{/call}
{call buck.arg}
{param name : 'skip_proguard' /}
{param default : 'False' /}
{param desc}
To produce a release build without running ProGuard set
the <code>skip_proguard</code> flag to <code>True</code>. This will still cause ProGuard
configuration files to be generated for use by other optimizers like Redex.
{/param}
{/call}
{call buck.arg}
{param name : 'redex' /}
{param default : 'False' /}
{param desc}
<p>
Set this to <code>True</code> to run ReDex on the APK generated by this rule.
</p>
{call .redexLink /}
{/param}
{/call}
{call buck.arg}
{param name : 'redex_config' /}
{param default : 'None' /}
{param desc}
<p>
Path to a ReDex config file. (This is passed as via the <code>--config</code> option to ReDex.)
Note this may be a generated file.
</p>
{call .redexLink /}
{/param}
{/call}
{call buck.arg}
{param name : 'redex_extra_args' /}
{param default : '[]' /}
{param desc}
<p>
A list of additional arguments to pass to the ReDex binary.
</p>
{call .redexLink /}
{/param}
{/call}
{call buck.arg}
{param name : 'native_library_merge_map' /}
{{param default : '{}' /}}
{param desc}
<p>
An advanced option for apps with many native libraries.
For more details,
see <a href="https://github.com/fbsamples/android-native-library-merging-demo">this article</a>.
</p>
{/param}
{/call}
{/param} // close args
{param examples}
Here is an example of an <code>android_binary()</code> rule that
includes Android resources from one dependency and compiled Java
code from another dependency:
{literal}<pre class="prettyprint lang-py">
android_resource(
name = 'res',
res = 'res',
assets = 'assets',
)
android_library(
name = 'src',
srcs = glob(['src/**/*.java']),
deps = [
':res',
],
)
# Building this rule will produce a file named messenger.apk.
android_binary(
name = 'messenger',
manifest = 'AndroidManifest.xml',
keystore = '//keystores:prod',
package_type = 'release',
proguard_config = 'proguard.cfg',
deps = [
':res',
':src',
],
)
</pre>{/literal}
<h2 id="redex-overview">ReDex</h2>
<p>
Buck makes it easy to run <a href="http://fbredex.com/">ReDex</a> as part
of <code>android_binary()</code>. ReDex is an Android bytecode optimizer
that can help reduce the size of your release builds.
Please refer to <a href="http://fbredex.com/">ReDex</a> for instructions
on how to create a ReDex executable.
</p>
<p>
Currently, the path to ReDex must be
specified as a path (or build target) in <code>.buckconfig</code>:
</p>
{literal}<pre class="prettyprint lang-ini">
[android]
# In this example, we assume that you have ReDex packaged as a single
# executable file named redex-bin. Read "Creating redex-bin" below on how
# to create this file. Note that the expectation is that you check
# redex-bin into your project.
redex = third-party/native/redex/redex-bin
# Alternatively, you could create a genrule(), such as
# //tools/redex:redex, that wraps ReDex. It must have
# `executable = True` to ensure the genrule() is runnable.
# In this case, you would specify the build target instead
# of the file path.
# redex = //tools/redex:redex
</pre>{/literal}
<p>
If a ReDex executable is set properly in <code>.buckconfig</code>, then it
is possible to run ReDex as part of building an <code>android_binary()</code>,
but the following conditions must hold:
</p>
<ul>
<li><code>redex = True</code> must be set on the <code>android_binary()</code>.
</ul>
<p>
Other ReDex configuration options on <code>android_binary()</code> include:
</p>
<ul>
<li><code><a href="#arg/redex_config">redex_config</a></code>
<li><code><a href="#arg/redex_json_args">redex_json_args</a></code>
</ul>
{/param}
{/call} // close buck.rule
<h2>Fast DEX merging for Android</h2>
<p>
Buck includes a customized version of the Android DEX
compiler, <code>dx</code>, which includes significant performance
improvements. It uses a faster algorithm for merging many DEX files, which is
especially effective because of Buck's support for fine-grained
libraries.
</p>
<p>
The custom version of <code>dx</code> also supports running multiple
copies of <code>dx</code> concurrently within a single
long-lived <code>buckd</code> process, which eliminates most
of <code>dx's</code> start-up time.
</p>
{/param}
{/call}
{/template}
/***/
{template .redexLink}
{/template}