Buck: android_binary()

android_binary()

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

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 toReDex 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:

Arguments

  • name (required) #

    The name of the rule, as well as the name of the APK generated by this rule.

  • manifest (required) #

    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.

  • 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).

  • 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.

  • 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.

  • 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.

  • 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 amongst 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.

  • 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 theskip_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.

    See the ReDex overview for more on using ReDex in Buck.

  • 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.

    See the ReDex overview for more on using ReDex in Buck.

  • redex_extra_args (defaults to []) #

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

    See the ReDex overview for more on using ReDex in Buck.

  • visibility (defaults to []) #

    List of build target patterns that identify the build rules that can include this rule in its deps.

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