Docs: Add article on Jack.
Bug: 22639850

Change-Id: I3b2ef37932581b034cbf2bfbf53e15c8bdbc4b61
diff --git a/src/images/jack-library-file.png b/src/images/jack-library-file.png
new file mode 100644
index 0000000..b25dd85
--- /dev/null
+++ b/src/images/jack-library-file.png
Binary files differ
diff --git a/src/images/jack-overview.png b/src/images/jack-overview.png
new file mode 100644
index 0000000..74d396f
--- /dev/null
+++ b/src/images/jack-overview.png
Binary files differ
diff --git a/src/images/jill.png b/src/images/jill.png
new file mode 100644
index 0000000..0d9ba14
--- /dev/null
+++ b/src/images/jill.png
Binary files differ
diff --git a/src/images/pre-dex.png b/src/images/pre-dex.png
new file mode 100644
index 0000000..4d39700
--- /dev/null
+++ b/src/images/pre-dex.png
Binary files differ
diff --git a/src/source/jack.jd b/src/source/jack.jd
new file mode 100644
index 0000000..ecddd90
--- /dev/null
+++ b/src/source/jack.jd
@@ -0,0 +1,357 @@
+page.title=Jack (Java Android Compiler Kit)
+@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 (Java Android Compiler Kit) 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; partners 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>
+
+<img src="{@docRoot}images/jack-overview.png" height="75%" width="75%" alt="Jack overview" />
+<p class="img-caption"><strong>Figure 1. </strong>Jack (Java Android Compiler Kit)</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=jack_intermediate_library_linker_jill>Jack Intermediate Library Linker (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>
+
+<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>
+