android_binary()

An android_binary() rule is used to generate an Android APK.

Arguments

• name (required) #

  The short name for this build target. Also, the name of the APK generated from this target.

• manifest (defaults to None) #

  Relative path to the Android manifest for the APK. The common case is that the manifest will be in the same directory as the rule, in which case this will simply be 'AndroidManifest.xml', but it can also reference an android_manifest rule. Prefer using manifest_skeleton, which performs merging automatically. Exactly one of manifest and manifest_skeleton must be set.

• manifest_skeleton (defaults to None) #

  Relative path to the skeleton Android manifest for the APK. An android_manifest will be created automatically to merge all manifests from libraries and resources going into the app. The common case is that the manifest will be in the same directory as the rule, in which case this will simply be 'AndroidManifest.xml'. Exactly one of manifest and manifest_skeleton must be set.

• keystore (required) #

  A build target that identifies a keystore to use to sign the APK.

• package_type (defaults to 'debug') #

  Determines whether ProGuard will be used when packaging the APK. Acceptable values for package_type are 'debug' and'release'. The default value is 'debug', which indicates that ProGuard should not be used.

  Note: This argument will be renamed to reflect that it determines the use of ProGuard.

• proguard_config (defaults to None) #

  Relative path to a ProGuard configuration file that will be passed via the -include flag when package_type is 'release'.

• android_sdk_proguard_config (defaults to 'default') #

  The type of proguard configuration to use from the Android SDK. Options are 'default' to use the default config,'optimized' to use the config with optimizations enabled, or 'none' to not use any standard configuration (you will need to supply your own version, otherwise your app will probably not work).

• ignore_aapt_proguard_config (defaults to False) #

  If true, the proguard config automatically generated by aapt will be ignored.

• no_dx (defaults to []) #

  List of build targets that may have been included during compilation of the transitive android_library() and java_library() dependencies, but should not be included in the classes.dex for generated for the APK.

• build_config_values (defaults to []) #

  See the documentation on the values argument for android_build_config.

• build_config_values_file (defaults to None) #

  See the documentation on the values_file argument for android_build_config.

• aapt_mode (defaults to aapt1) #

  Set to "aapt2" to build resources for this app with aapt2.

• skip_crunch_pngs (defaults to False) #

  If True, PNGs in the APK are not crushed by aapt. This is equivalent to specifying

    android {
        aaptOptions.useAaptPngCruncher = false
    }
    

  in gradle, or

    <target name="-crunch">
        <echo message="Skipping PNG optimization"/>
    </target>
    

  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.

• duplicate_resource_behavior (defaults to allow_by_default) #

  If set to "ban_by_default", duplicate resource definitions with the same type and name will cause the build to fail, unless they are excluded by allowed_duplicate_resource_typesor duplicate_resource_whitelist. If set to "allow_by_default" (the default), no duplicate resource checks will be performed. They can still be enabled on individual types by using banned_duplicate_resource_types.

• banned_duplicate_resource_types (defaults to []) #

  If ['string'] 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.

• allowed_duplicate_resource_types (defaults to []) #

  Similar to banned_duplicate_resource_types, but lists the types that are allowed to have duplicates. This should only be used if duplicate_resource_behavior is "ban_by_default".

• duplicate_resource_whitelist (defaults to None) #

  Either a 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, string app_name.

• includes_vector_drawables (defaults to False) #

  When calling AAPT during the packaging process, pass the --no-version-vectors flag which ensures that any vector drawables which make use of the Android support library are backwards compatible with Android 4.4 and earlier.

• manifest_entries (defaults to {}) #

  Insert values into the packaged AndroidManifest.xml file. Valid values are min_sdk_version, target_sdk_version,version_code, version_name, and debug_mode. Example:

    android_binary(
      # ... other args ...
      manifest_entries = {
          'version_code': 12,
          'version_name': '2.0',
          'min_sdk_version': 16,
          'target_sdk_version': 23,
          'debug_mode': True,
      }
    )
    

  This is equivalent to specifying

    android {
        defaultConfig {
          versionCode 12
          versionName "2.0"
          minSdkVersion 16
          targetSdkVersion 23
        }
    }
    

  in gradle and building the debug BuildType. This is especially useful when combined with the flatten_dicts function. This will allow you to share a default config across your rules, and override values as necessary.

• deps (defaults to []) #

  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:

  • android_library()
  • android_resource()
  • cxx_library()
  • groovy_library()
  • java_library()
  • java_binary()
  • prebuilt_jar()
  • ndk_library()
  • prebuilt_native_library()

• cpu_filters (defaults to []) #

  The CPU architecture filter applied to the final apk. Could be a subset of ARM, ARMV7, ARM64, X86, X86_64, MIPS.

  Note: 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 install guide to set it up.

• use_split_dex (defaults to False) #

  If this argument is True, Buck enables multidex 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.

  use_split_dex = True
  

  For more information on multidex support, go to the Android Developer Documentation.

• application_module_configs (defaults to []) #

  A map of module names to lists of targets, where the targets should seed 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.

• linear_alloc_hard_limit (defaults to 4194304) #

  The size at which secondary dex files should be split when building an exopackage in bytes.

  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.

• skip_proguard (defaults to False) #

  To produce a release build without running ProGuard set the skip_proguard flag to True. This will still cause ProGuard configuration files to be generated for use by other optimizers like Redex.

• redex (defaults to False) #

  Set this to True to run ReDex on the APK generated by this rule.

• redex_config (defaults to None) #

  Path to a ReDex config file. (This is passed as via the --config option to ReDex.) Note this may be a generated file.

• redex_extra_args (defaults to []) #

  A list of additional arguments to pass to the ReDex binary.

• native_library_merge_map (defaults to {}) #

  An advanced option for apps with many native libraries. For more details, see this article.

• visibility (defaults to []) #

  List of build target patterns that identify the build rules that can include this rule as a dependency, for example, by listing it in their deps or exported_deps attributes. For more information, see visibility.

• licenses (defaults to []) #

  Set of license files for this library. To get the list of license files for a given build rule and all of its dependencies, you can use buck query.

• labels (defaults to []) #

  Set of arbitrary strings which allow you to annotate a build rule with tags that can be searched for over an entire dependency tree using buck query attrfilter().

Examples

Here is an example of an android_binary() rule that includes Android resources from one dependency and compiled Java code from another dependency:

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',
  ],
)

ReDex

Buck makes it easy to run ReDex as part of android_binary(). ReDex is an Android bytecode optimizer that can help reduce the size of your release builds. Please refer to ReDex for instructions on how to create a ReDex executable.

Currently, the path to ReDex must be specified as a path (or build target) in .buckconfig:

[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

If a ReDex executable is set properly in .buckconfig, then it is possible to run ReDex as part of building an android_binary(), but the following conditions must hold:

• redex = True must be set on the android_binary().

Other ReDex configuration options on android_binary() include:

• redex_config
• redex_json_args

Fast DEX merging for Android

Buck includes a customized version of the Android DEX compiler, dx, 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.

The custom version of dx also supports running multiple copies of dx concurrently within a single long-lived buckd process, which eliminates most of dx's start-up time.