You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
376 lines
16 KiB
376 lines
16 KiB
<html devsite> |
|
<head> |
|
<title>Compiling with Jack</title> |
|
<meta name="project_path" value="/_project.yaml" /> |
|
<meta name="book_path" value="/_book.yaml" /> |
|
</head> |
|
<body> |
|
<!-- |
|
Copyright 2017 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. |
|
--> |
|
|
|
|
|
|
|
<h2 id=the_jack_toolchain>The Jack toolchain</h2> |
|
|
|
<p class="warning"> |
|
<b>The Jack toolchain is deprecated</b>, as per |
|
<a href="https://android-developers.googleblog.com/2017/03/future-of-java-8-language-feature.html"> |
|
this announcement</a>. You may continue to use it or try the latest |
|
<a href="https://developer.android.com/studio/preview/index.html">preview version of |
|
Android Studio</a>, which provides improved support for <a href="https://developer.android.com/studio/preview/features/java8-support.html"> |
|
Java 8 language features built into the default toolchain</a>. |
|
</p> |
|
|
|
<p>Jack is an 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="/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="/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="/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="devsite-terminal devsite-click-to-copy"> |
|
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="devsite-terminal devsite-click-to-copy"> |
|
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="/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="devsite-click-to-copy"> |
|
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> |
|
|
|
|
|
</body> |
|
</html>
|
|
|