android—Compiling with Jack—Jack is a new Android toolchain

http://source.android.com/source/jack.html

The Jack toolchain

---

Jack is a new Android toolchain that compiles Javasource into Android dex bytecode. It replaces the previous Android toolchain,which consists of multiple tools, such as javac, ProGuard, jarjar, and dx.

The Jack toolchain provides the following advantages:

• Completely open source
  Available in AOSP; partners are welcome to contribute.
• Speeds compilation time
  Jack has specific supports to reduce compilation time: pre-dexing, incrementalcompilation and a Jack compilation server.
• Handles shrinking, obfuscation, repackaging and multidex
  Using a separate package such as ProGuard is no longer necessary.

Figure 1. Jack overview

The .jack library format

---

Jack has its own .jack file format, which contains the pre-compiled dex codefor the library, allowing for faster compilation (pre-dex).

Figure 2. Jack library file contents

Jill

---

The Jill tool translates the existing .jar libraries into the new libraryformat, as shown below.

Figure 3. Workflow to import an existing .jar library

Using Jack in your Android build

---

You don’t have to do anything differently to use Jack — just use your standardmakefile commands to compile the tree or your project. Jack is the defaultAndroid build toolchain for M.

The first time Jack is used, it launches a local Jack compilation server onyour computer:

• This server brings an intrinsic speedup, because it avoids launching a new hostJRE JVM, loading Jack code, initializing Jack and warming up the JIT at eachcompilation. It also provides very good compilation times during smallcompilations (e.g. in incremental mode).
• The server is also a short-term solution to control the number of parallel Jackcompilations, and so to avoid overloading your computer (memory or disk issue),because it limits the number of parallel compilations.

The Jack server shuts itself down after an idle time without any compilation.It uses two TCP ports on the localhost interface, and so is not availableexternally. All these parameters (number of parallel compilations, timeout,ports number, etc) can be modified by editing the $HOME/.jack file.

$HOME/.jack file

The $HOME/.jack file contains settings for Jack server variables, in a full bash syntax.

Here are the available settings, with their definitions and default values:

• SERVER=true Enable the server feature of Jack.
• SERVER_PORT_SERVICE=8072Set the TCP port number of the server for compilation purposes.
• SERVER_PORT_ADMIN=8073Set the TCP port number of the server for admin purposes.
• SERVER_COUNT=1Unused at present.
• SERVER_NB_COMPILE=4Maximum number of parallel compilations allowed.
• SERVER_TIMEOUT=60Number of idle seconds the server has to wait without any compilation beforeshutting itself down.
• SERVER_LOG=${SERVER_LOG:=$SERVER_DIR/jack-$SERVER_PORT_SERVICE.log}File where server logs are written. By default, this variable can beoverloaded by an environment variable.
• JACK_VM_COMMAND=${JACK_VM_COMMAND:=java}The default command used to launch a JVM on the host. By default, thisvariable can be overloaded by environment variable.

Jack troubleshooting

If your computer becomes unresponsive during compilation or if you experienceJack compilations failing on “Out of memory error”

You can improve the situation by reducing the number of Jack simultaneouscompilations by editing your $HOME/.jack and changing SERVER_NB_COMPILE to a lower value.

If your compilations are failing on “Cannot launch background server”

The most likely cause is TCP ports are already used on your computer. Try tochange it by editing your $HOME/.jack (SERVER_PORT_SERVICE and SERVER_PORT_ADMIN variables).

If it doesn’t solve the problem, please report and attach your compilation logand the Jack server log (see ‘Finding the Jack log’ below to know where to findthe server log file). To unblock the situation, disable jack compilation serverby editing your $HOME/.jack and changing SERVER to false. Unfortunately this will significantly slow down your compilation andmay force you to launch make -j with load control (option "-l" of make).

If your compilation gets stuck without any progress

Please report this and give us the following additional information (wherepossible):

• The command line at which you are stuck.
• The output of this command line.
• The result of executing jack-admin server-stat.
• The $HOME/.jack file.
• The content of the server log with the server state dumped. To get this —
  • Find the Jack background server process by running jack-admin list-server.
  • Send a kill -3 command to this server to dump its state into the log file.
  • To locate the server log file, see ‘Finding the Jack log’ below.
• The result of executing ls -lR $TMPDIR/jack-$USER.
• The result of running ps j -U $USER.

You should be able to unblock yourself by killing the Jack background server(use jack-admin kill-server), and then by removing its temporary directories contained in jack-$USER of your temporary directory (/tmp or $TMPDIR).

If you have any other issues

To report bugs or request features, please use our public issue tracker,available at http://b.android.com, with the Jack tool bug report or Jack tool feature request templates. Please attach the Jack log to the bug report.

Finding the Jack log

• If you ran a make command with a dist target, the Jack log is located at $ANDROID_BUILD_TOP/out/dist/logs/jack-server.log
• Otherwise you can find it in by running jack-admin server-log

In case of reproducible Jack failures, you can get a more detailed log bysetting one variable, as follows:

$ export ANDROID_JACK_EXTRA_ARGS="--verbose debug --sanity-checks on -D
sched.runner=single-threaded"

Then use your standard makefile commands to compile the tree or your projectand attach its standard output and error.

To remove detailed build logs use:

$ unset ANDROID_JACK_EXTRA_ARGS

Jack limitations

• The Jack server is mono-user by default, so can be only used by one user on acomputer. If it is not the case, please, choose different port numbers for eachuser and adjust SERVER_NB_COMPILE accordingly. You can also disable the Jackserver by setting SERVER=false in your $HOME/.jack.
• CTS compilation is slow due to current vm-tests-tf integration.
• Bytecode manipulation tools, like JaCoCo, are not supported.

Using Jack features

---

Jack supports Java programming language 1.7 and integrates additional featuresdescribed below.

Predexing

When generating a Jack library file, the .dex of the library is generated andstored inside the .jack library file as a pre-dex. When compiling, Jack reusesthe pre-dex from each library.

All libraries are pre-dexed.

Figure 4. Jack libraries with pre-dex

Limitations

Currently, Jack does not reuse the library pre-dex ifshrinking/obfuscation/repackaging is used in the compilation.

Incremental compilation

Incremental compilation means that only components that were touched since thelast compilation, and their dependencies, are recompiled. Incrementalcompilation can be significantly faster than a full compilation when changesare limited to only a limited set of components.

Limitations

Incremental compilation is deactivated when shrinking, obfuscation, repackagingor multi-dex legacy is enabled.

Enabling incremental builds

Currently incremental compilation is not enabled by default. To enableincremental builds, add the following line to the Android.mk file of theproject that you want to build incrementally:

LOCAL_JACK_ENABLED := incremental

Note: The first time that you build your project with Jack if some dependenciesare not built, use mma to build them, and after that you can use the standard build command.

Shrinking and Obfuscation

Jack has shrinking and obfuscation support and uses proguard configurationfiles to enable shrinking and obfuscation features. Here are the supported andignored options:

Supported common options

Common options include the following:

• @
• -include
• -basedirectory
• -injars
• -outjars // only 1 output jar supported
• -libraryjars
• -keep
• -keepclassmembers
• -keepclasseswithmembers
• -keepnames
• -keepclassmembernames
• -keepclasseswithmembernames
• -printseeds

Supported shrinking options

Shrinking options include the following:

• -dontshrink

Supported obfuscation options

Obfuscation options include the following:

• -dontobfuscate
• -printmapping
• -applymapping
• -obfuscationdictionary
• -classobfuscationdictionary
• -packageobfuscationdictionary
• -useuniqueclassmembernames
• -dontusemixedcaseclassnames
• -keeppackagenames
• -flattenpackagehierarchy
• -repackageclasses
• -keepattributes
• -adaptclassstrings

Ignored options

Ignored options include the following:

• -dontoptimize // Jack does not optimize
• -dontpreverify // Jack does not preverify
• -skipnonpubliclibraryclasses
• -dontskipnonpubliclibraryclasses
• -dontskipnonpubliclibraryclassmembers
• -keepdirectories
• -target
• -forceprocessing
• -printusage
• -whyareyoukeeping
• -optimizations
• -optimizationpasses
• -assumenosideeffects
• -allowaccessmodification
• -mergeinterfacesaggressively
• -overloadaggressively
• -microedition
• -verbose
• -dontnote
• -dontwarn
• -ignorewarnings
• -printconfiguration
• -dump

Note: Other options will generate an error.

Repackaging

Jack uses jarjar configuration files to do the repackaging.

Note: 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 featurerequest with a description of how you use the feature in your app.

Multidex support

Since dex files are limited to 65K methods, apps with over 65K methods must besplit into multiple dex files. (See ‘Building Apps with Over 65K Methods’ for more information about multidex.)

Jack offers native and legacy multidex support.