Technical docs‎ > ‎

Experimental New Android Tool Chain - Jack and Jill

N Developer Preview users: Instructions to enable the Jack toolchain in the N Preview differ from the instructions below. Read the official documentation to enable Jack and the new Java 8 language features in Android N.

Jack is a new Android toolchain that comprises a compiler from Java programming language source to the Android dex file format. Jack has its own .jack library format and provides most tool chain features as part of a single tool: repackaging, shrinking, obfuscation and multidex. Jill is a tool that translates existing .jar files to the .jack library format. We have many new features for Jack under development, including incremental compilation support, so we encourage you to give it a try today.

See below for usage and support details. Jack is currently an experimental tool chain. To report bugs or request features use our issue tracker, available at http://b.android.com and use the templates Jack tool bug report or Jack tool feature request.

Overview

When the new tool chain is enabled Jill will translate any libraries you are referencing to a new Jack library file (.jack). This prepares them to be quickly merged with other .jack files. Jack and the Android Gradle plugin collect any .jack library files along with your source code and compiles them into a set of dex files. During this process Jack also handles any requested code minification (shrinking and/or obfuscation). The output is then assembled into an APK file as normal. Including support for multiple dex files if you have enabled that support.




How to use Jack using Gradle
Jack and Jill are available in Build Tools version 21.1.1, and greater, via the SDK Manager. Complementary Gradle and Android Studio support is also already available in the Android 1.0.0+ Gradle plugin.

Using Gradle, add the following to your module-level build config file:

android { ... buildToolsVersion ‘21.1.2’ defaultConfig { // Enable the experimental Jack build tools. jackOptions { enabled true } } ... }


If you want to build your app with both tool chains, ProductFlavors are a great way to do this. Your module-level build.gradle file might look something like the snippet below.

android { ... productFlavors { dev { ... } experimental {

            ... jackOptions { enabled true } } prod { ... } } ... }

Using command lines

To display the usage information for Jack and Jill use these commands. Some features may be available on the command line before they are made available through the Android Gradle plugin.
  • Jack usage
    • java -jar <SDK>/build-tools/<build-tools-version>/jack.jar --help
  • Jill usage
    • java -jar <SDK>/build-tools/<build-tools-version>/jill.jar --help

Compilation support

  • Java programming language 1.7 (1.8 available with Android N Developer Preview)
  • Repackaging, shrinking, obfuscation and multidex features are supported.
  • Annotation processing (with Android Gradle Plugin version 2.2.0-alpha1 or higher).
  • Incremental compilation (enabled by default). To disable incremental compilation with Jack, add the following to your module-level build.gradle file:

    android { ... compileOptions { incremental false } ... }

Shrinking and Obfuscation support


Proguard configuration files can be specified on the command line through the "--config-proguard" option.

Common options:


@

-include

-basedirectory

-injars

-outjars // only 1 output jar supported

-libraryjars

-dontoptimize // required: Jack does not optimize

-dontpreverify // required: Jack does not preverify

-dontskipnonpubliclibraryclasses

-dontskipnonpubliclibraryclassmembers

-forceprocessing

-keep

-keepclassmembers

-keepclasseswithmembers

-keepnames

-keepclassmembernames

-keepclasseswithmembernames

-printseeds


Shrinking options:


-dontshrink


Obfuscation options:

-dontobfuscate

-printmapping

-applymapping

-obfuscationdictionary

-classobfuscationdictionary

-packageobfuscationdictionary

-useuniqueclassmembernames

-dontusemixedcaseclassnames

-keeppackagenames

-flattenpackagehierarchy

-repackageclasses

-keepattributes

-adaptclassstrings


Repackaging support


Jack is compatible with "rule" rule types, but is not compatible with "zap" or "keep" rule types. If you need "zap" or "keep" rule types please file a feature request with a description of how you use the feature in your app. The description helps us prioritize among requests or simply suggest workarounds or best practices. Rule files can be specified on the command line through the "--config-jarjar" option.

Annotation processing

By default (with Android Gradle Plugin version 2.2.0-alpha1 or higher), annotation processors on your classpath (such as, any compile dependency) will be automatically applied. You can also specify an annotation processor in your build and pass arguments by using the following DSL in your module-level build.gradle file:


android { ... defaultConfig { ... javaCompileOptions { annotationProcessorOptions { className 'com.example.MyProcessor' // Arguments are optional. arguments = [ foo : 'bar' ] } } } ... }

If you want an annotation processor to be applied at compile time but not to be included in your APK, use the annotationProcessor dependency scope:


dependencies { compile 'com.google.dagger:dagger:2.0' annotationProcessor 'com.google.dagger:dagger-compiler:2.0' }

You can also apply annotation processors for specific build variants:

debugAnnotationProcessor 'com.google.dagger:dagger-compiler:2.0'

Passing additional parameters to Jack

You can set additional flags for Jack using the additionalParameters property. The following code snippet sets the jack.incremental parameter to true:

android { ... defaultConfig { ... jackOptions { enabled true additionalParameters("jack.incremental" : true) } } ... }


For a list of parameters you can set, run the following from the command line:

$ java -jar <SDK>/build-tools/<build-tools-version>/jack.jar --help-properties


Using Gradle

Android Gradle plugin support is under development, there are some limitations:

  • The "-applymapping" obfuscation directive is not yet supported,
  • Repackaging (similar to the jarjar tool) is not integrated,
  • Jacoco instrumentation is not supported,
  • Bytecode manipulation is not supported,
  • Some users may receive an Out Of Memory exception while building very large apps. You can resolve this by configuring the build system to use 2G of ram (or more) like so:

android {


...

dexOptions { javaMaxHeapSize "2048M" }


...

}


Release Notes


Build Tools versionGradle plugin version Release Notes
 21.1.1 1.0.0 Initial version of Jack and Jill

21.1.2  1.0.0 Minor bug fixes
Build Tools 23.0.2 or higher 2.2.0-alpha1 
Comments