{namespace android_binary}

/***/
{template .soyweb}
  {call buck.page}
    {param title: '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}
An <code>android_binary()</code> rule is used to generate an Android APK.
{/param}

{param args}

{call buck.arg}
  {param name: 'name' /}
  {param desc}
  The name of the rule, as well as the name of the APK generated by this
  rule.
  {/param}
{/call}

{call buck.arg}
  {param name: 'manifest' /}
  {param desc}
  Relative path to the Android manifest for the APK.
  The common case is that the manifest will be in the same directory
  as the <code>android_binary()</code>, in which case this will
  simply be <code>'AndroidManifest.xml'</code>.
  {/param}
{/call}

{call buck.arg}
  {param name: 'keystore' /}
  {param desc}
  A build target that identifies a {call buck.keystore /} to use to
  sign the APK.

  See <a href="{ROOT}setup/quick_start.html">Quick Start</a> for more
  details.
  {/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 : '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 : '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 : 'deps' /}
  {param default : '[]' /}
  {param desc}
  List of build targets whose corresponding compiled Java code,
  Android resources, and native libraries will be included in the APK.
  From the transitive closure of these dependencies, the outputs of rules of the following type will be included in the APK:
  <ul>
    <li><code>android_library()</code>
    <li><code>android_resource()</code>
    <li><code>java_library()</code>
    <li><code>java_binary()</code>
    <li><code>prebuilt_jar()</code>
    <li><code>ndk_library()</code>
    <li><code>prebuilt_native_library()</code>
  </ul>
  {/param}
{/call}

{call buck.visibility_arg /}

{/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}
{/param}

{/call} // close buck.rule

    {/param}
  {/call}
{/template}