{namespace android_binary}

/***/
{template .soyweb}
  {call buck.page}
    {param title: 'android_binary()' /}
    {param prettify: true /}
    {param content}

{call buck.rule}
{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: 'target' /}
  {param desc}
  The version of Android being targeted by this APK. In a traditional
  Android project, this would be specified in the
  {sp}<code>project.properties</code> file. This is frequently something
  like <code>'Google Inc.:Google APIs:16'</code>.
  {/param}
{/call}

{call buck.arg}
  {param name: 'keystore_properties' /}
  {param desc}
  Relative path to a <code>.properties</code> file that defines the
  following keystore properties:

{literal}<pre>
key.store=debug.keystore
key.alias=my_alias
key.store.password=android
key.alias.password=android
</pre>{/literal}

  Note that the value of <code>key.store</code> must also be a relative
  path to the keystore itself.
  <p>
  See <a href="{ROOT}setup/quickstart.html">Quick Start</a> for more
  details.
  <p>
  <strong>Note:</strong> This is unlike most rules in Buck because
  this introduces a reference on a file (the value of <code>key.store</code>)
  that is not evident from the build rule itself. This will likely be
  replaced by a special <code>keystore</code> build rule at some point to
  eliminate this irregularity.
  {/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 : '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.
  <p>
  // t2254090
  <strong>Note:</strong> This argument will be changed to accept a list
  of build targets.
  {/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',
  target = 'Google Inc.:Google APIs:16',
  keystore_properties = 'keystore.properties',
  package_type = 'release',
  proguard_config = 'proguard.cfg',
  deps = [
    ':res',
    ':src',
  ],
)
</pre>{/literal}
{/param}

{/call} // close buck.rule

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