Technical docs‎ > ‎

Experimental New Android Tool Chain - Jack and Jill

The Jack toolchain is deprecated, as per this announcement. You may continue to use it, or try the latest preview version of Android Studio to use improved support for Java 8 language features built into the default toolchain.

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.

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


Running in process and out of process
There are two ways to run the Jack tool chain: running in the Gradle daemon JVM (in-process), or starting a completely new JVM (out-of-process). You can control this per variant using the jackOptions.jackInProcess. By default, Android Gradle Plugin will try to run Jack in the same process if the daemon heap size is at least 1.5GiB, otherwise it will run in a separate JVM. To set the daemon heap size, edit the gradle.properties file.

# gradle.properties file, this sets the daemon heap size to 1.5GiB

org.gradle.jvmargs=-Xmx1536M


If you would like to run Jack tool chain in a separate JVM, set 
jackOptions.jackInProcess to false for that variant. In this mode, you control the heap size by specifying the dexOptions.javaMaxHeapSize option. Here is an example build.gradle demonstrating both in-process and out-of-process Jack setup.

android {

defaultConfig {

jackOptions {

enabled true // sets jackInProcess to true by default

}

}

productFlavors {


free {

jackOptions {

jackInProcess false // will run Jack out-of-process for all free variants

}

}

paid { } // paid variants will run Jack in-process

}

dexOptions {


javaMaxHeapSize "2048M" // used by the out-of-process Jack, ignored if running in-process

}

}


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,
  • 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). See Running in process and out of process section above to learn how to increase memory.

Release Notes


Build Tools version Gradle 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