src/source/jack.jd

page.title=Compiling with Jack
@jd:body

<!--
    Copyright 2015 The Android Open Source Project

    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.
    You may obtain a copy of the License at

        http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.
-->

<div id="qv-wrapper">
  <div id="qv">
    <h2>In this document</h2>
    <ol id="auto-toc">
    </ol>
  </div>
</div>

<h2 id=the_jack_toolchain>The Jack toolchain</h2>

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

<p>The Jack toolchain provides the following advantages:</p>

<ul>
  <li> <strong>Completely open source</strong><br>
Available in AOSP; users are welcome to contribute.
  <li> <strong>Speeds compilation time</strong><br>

Jack has specific supports to reduce compilation time: pre-dexing, incremental
compilation and a Jack compilation server.
  <li> <strong>Handles shrinking, obfuscation, repackaging and multidex</strong><br>
Using a separate package such as ProGuard is no longer necessary.
</ul>

<p class="note">Note that beginning in Android 7.0 (N), Jack supports code coverage with JaCoCo.
See <a href="https://android.googlesource.com/platform/prebuilts/sdk/+/master/tools/README-jack-code-coverage.md">
Code Coverage with JaCoCo</a> and <a href="https://developer.android.com/preview/j8-jack.html">
Java 8 Language Features</a> for details.</p>

<img src="{@docRoot}images/jack-overview.png" height="75%" width="75%" alt="Jack overview" />
<p class="img-caption"><strong>Figure 1. </strong>Jack overview</p>


<h2 id=the_jack_library_format>The .jack library format</h2>

<p>Jack has its own .jack file format, which contains the pre-compiled dex code
for the library, allowing for faster compilation (pre-dex).</p>

<img src="{@docRoot}images/jack-library-file.png" height="75%" width="75%" alt="Jack library file contents" />
<p class="img-caption"><strong>Figure 2. </strong>Jack library file contents</p>

<h2 id=jill>Jill</h2>

<p>The Jill tool translates the existing .jar libraries into the new library
format, as shown below.</p>

<img src="{@docRoot}images/jill.png" alt="Importing existing .jar libraries using Jill" />
<p class="img-caption"><strong>Figure 3. </strong>Workflow to import an existing .jar library</p>

<h2 id=using_jack_in_your_android_build>Using Jack in your Android build</h2>

<div class="note">For instructions on using Jack in Android 7.0 (N) and later, see the <a
href="https://android.googlesource.com/platform/prebuilts/sdk/+/master/tools/README-jack-server.md">Jack
server documentation</a>. For Android 6.0 (M), use the instructions in this section.</div>

<p>You don’t have to do anything differently to use Jack — just use your
standard makefile commands to compile the tree or your project.  Jack is the
default Android build toolchain for M.</p>

<p>The first time Jack is used, it launches a local Jack compilation server on
your computer:</p>

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

<p>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 available
externally. All these parameters (number of parallel compilations, timeout,
ports number, etc) can be modified by editing the<code> $HOME/.jack</code> file.</p>

<h3 id=$home_jack_file>$HOME/.jack file</h3>

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

<p>Here are the available settings, with their definitions and default values:</p>

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

<h3 id=jack_troubleshooting>Jack troubleshooting</h3>

<p><strong>If your computer becomes unresponsive during compilation or if you experience
Jack compilations failing on “Out of memory error”</strong></p>

<p>You can improve the situation by reducing the number of Jack simultaneous
compilations by editing your<code> $HOME/.jack</code> and changing<code> SERVER_NB_COMPILE</code> to a lower value.</p>

<p><strong>If your compilations are failing on “Cannot launch background server”</strong></p>

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

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

<p><strong>If your compilation gets stuck without any progress</strong></p>

<p>Please report this and give us the following  additional information (where
possible):</p>

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

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

<p><strong>If you have any other issues </strong></p>

<p>To report bugs or request features, please use our public issue tracker,
available at <a href="http://b.android.com">http://b.android.com</a>,  with the <a href="https://code.google.com/p/android/issues/entry?template=Jack%20bug%20report">Jack tool bug report</a> or <a href="https://code.google.com/p/android/issues/entry?template=Jack%20feature%20request">Jack tool feature request</a> templates. Please attach the Jack log to the bug report. </p>
<table>
 <tr>
    <td><strong>Finding the Jack log</strong>
<ul>
  <li> If you ran a make command with a dist target,  the Jack log is located at <code>$ANDROID_BUILD_TOP/out/dist/logs/jack-server.log</code> 
  <li> Otherwise you can find it in by running <code>jack-admin server-log</code>
</ul>
</td>
 </tr>
</table>

<p>In case of reproducible Jack failures, you can get a more detailed log by
setting one variable, as follows:</p>

<pre class=prettyprint>
$ export ANDROID_JACK_EXTRA_ARGS="--verbose debug --sanity-checks on -D
sched.runner=single-threaded"
</pre>

<p>Then use your standard makefile commands to compile the tree or your project
and attach its standard output and error.</p>

<p>To remove detailed build logs use:</p>

<pre class=prettyprint>
$ unset ANDROID_JACK_EXTRA_ARGS
</pre>

<h3 id=jack_limitations>Jack limitations</h3>

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

<h2 id=using_jack_features>Using Jack features</h2>

<p>Jack supports Java programming language 1.7 and integrates additional features
described below.</p>

<h3 id=predexing>Predexing </h3>

<p>When generating a Jack library file, the .dex of the library is generated and
stored inside the .jack library file as a pre-dex.  When compiling, Jack reuses
the pre-dex from each library.</p>

<p>All libraries are pre-dexed.</p>

<img src="{@docRoot}images/pre-dex.png" height="75%" width="75%" alt="Jack libraries with pre-dex" />
<p class="img-caption"><strong>Figure 4. </strong>Jack libraries with pre-dex</p>

<h4 id=limitations>Limitations</h4>


<p>Currently, Jack does not reuse the library pre-dex if
shrinking/obfuscation/repackaging is used in the compilation.</p>

<h3 id=incremental_compilation>Incremental compilation</h3>


<p>Incremental compilation means that only components that were touched since the
last compilation, and their dependencies, are recompiled.  Incremental
compilation can be significantly faster than a full compilation when changes
are limited to only a limited set of components.</p>

<h4 id=limitations>Limitations</h4>


<p>Incremental compilation is deactivated when shrinking, obfuscation, repackaging
or multi-dex legacy is enabled.</p>

<h4 id=enabling_incremental_builds>Enabling incremental builds</h4>


<p>Currently incremental compilation is not enabled by default.  To enable
incremental builds, add the following line to the Android.mk file of the
project that you want to build incrementally:</p>

<pre class=prettyprint>
LOCAL_JACK_ENABLED := incremental
</pre>

<p class="note"><strong>Note:</strong> The first time that you build your project with Jack if some dependencies
are not built, use <code>mma</code> to build them, and after that you can use the standard build command.</p>

<h3 id=shrinking_and_obfuscation>Shrinking and Obfuscation</h3>

<p>Jack has shrinking and obfuscation support and uses proguard configuration
files to enable shrinking and obfuscation features. Here are the supported and
ignored options:</p>

<h4 id=supported_common_options>Supported common options</h4>


<p>Common options include the following:</p>

<ul>
  <li> <code>@</code>
  <li> <code>-include</code>
  <li> <code>-basedirectory</code>
  <li> <code>-injars</code>
  <li> <code>-outjars // only 1 output jar supported</code>
  <li> <code>-libraryjars</code>
  <li> <code>-keep</code>
  <li> <code>-keepclassmembers</code>
  <li> <code>-keepclasseswithmembers</code>
  <li> <code>-keepnames</code>
  <li> <code>-keepclassmembernames</code>
  <li> <code>-keepclasseswithmembernames</code>
  <li> <code>-printseeds</code>
</ul>

<h4 id=supported_shrinking_options>Supported shrinking options</h4>


<p>Shrinking options include the following:</p>

<ul>
  <li> <code>-dontshrink</code>
</ul>

<h4 id=supported_obfuscation_options>Supported obfuscation options</h4>


<p>Obfuscation options include the following:</p>

<ul>
  <li> <code>-dontobfuscate</code>
  <li> <code>-printmapping</code>
  <li> <code>-applymapping</code>
  <li> <code>-obfuscationdictionary</code>
  <li> <code>-classobfuscationdictionary</code>
  <li> <code>-packageobfuscationdictionary</code>
  <li> <code>-useuniqueclassmembernames</code>
  <li> <code>-dontusemixedcaseclassnames</code>
  <li> <code>-keeppackagenames</code>
  <li> <code>-flattenpackagehierarchy</code>
  <li> <code>-repackageclasses</code>
  <li> <code>-keepattributes</code>
  <li> <code>-adaptclassstrings</code>
</ul>

<h4 id=ignored_options>Ignored options</h4>


<p>Ignored options include the following:</p>

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

<p class="note"><strong>Note:</strong>  Other options will generate an error.</p>

<h3 id=repackaging>Repackaging</h3>

<p>Jack uses jarjar configuration files to do the repackaging.</p>

<p class="note"><strong>Note:</strong> 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.</p>

<h3 id=multidex_support>Multidex support</h3>


<p>Since dex files are limited to 65K methods, apps with over 65K methods must be
split into multiple dex files.  (See <a href="http://developer.android.com/tools/building/multidex.html">‘Building Apps with Over 65K Methods’</a> for more information about multidex.)</p>

<p>Jack offers native  and legacy multidex support. </p>