Ant task for offline instrumentation.
diff --git a/org.jacoco.doc/docroot/doc/ant.html b/org.jacoco.doc/docroot/doc/ant.html
index 4da2fff..78cd89a 100644
--- a/org.jacoco.doc/docroot/doc/ant.html
+++ b/org.jacoco.doc/docroot/doc/ant.html
@@ -28,7 +28,10 @@
<a href="#agent"><code>agent</code></a>,
<a href="#dump"><code>dump</code></a> and
<a href="#merge"><code>merge</code></a>. Reports in different formats are
- creates with the <a href="#report"><code>report</code></a> task.
+ creates with the <a href="#report"><code>report</code></a> task. For
+ <a href="offline.html">offline instrumentation</a> the task
+ <a href="#instrument"><code>instrument</code></a> can be used to prepare class
+ files.
</p>
<p class="hint">
@@ -694,6 +697,43 @@
</tbody>
</table>
+
+<h2><a name="instrument">Task <code>instrument</code></a></h2>
+
+<p>
+ This task is used for <a href="offline.html">offline instrumentation</a> of
+ class files. The task takes a set of class files and writes instrumented
+ versions to a specified location.
+</p>
+
+<pre class="source lang-xml linenums">
+<jacoco:instrument destfile="target/classes-instr">
+ <fileset dir="target/classes" includes="**/*.class"/>
+</jacoco:instrument>
+</pre>
+
+<p>
+ The task definition can contain any number of resource collection types and
+ has the following mandatory attribute:
+</p>
+
+<table class="coverage">
+ <thead>
+ <tr>
+ <td>Attribute</td>
+ <td>Description</td>
+ <td>Default</td>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td><code>destdir</code></td>
+ <td>Directory location to write the instrumented class files to.</td>
+ <td><i>none (required)</i></td>
+ </tr>
+ </tbody>
+</table>
+
</div>
<div class="footer">
<span class="right"><a href="@jacoco.home.url@">JaCoCo</a> @qualified.bundle.version@</span>
diff --git a/org.jacoco.doc/docroot/doc/index.html b/org.jacoco.doc/docroot/doc/index.html
index aa3cffb..7250e24 100644
--- a/org.jacoco.doc/docroot/doc/index.html
+++ b/org.jacoco.doc/docroot/doc/index.html
@@ -38,10 +38,12 @@
<ul>
<li><a href="ant.html">Ant Tasks</a></li>
- <li><a href="examples/build/build.xml">Ant Usage Example</a></li>
+ <li><a href="examples/build/build.xml">Ant Usage Example</a> -
+ <a href="examples/build/build-offline.xml">Offline Example</a></li>
<li><a href="maven.html">Maven Plug-in</a></li>
<li><a href="examples/build/pom.xml">Maven Usage Example</a></li>
<li><a href="agent.html">Java Agent</a></li>
+ <li><a href="offline.html">Offline Instrumentation</a></li>
<li><a href="faq.html">FAQ</a></li>
<li><a href="support.html">Support and Feedback</a></li>
</ul>
diff --git a/org.jacoco.doc/docroot/doc/offline.html b/org.jacoco.doc/docroot/doc/offline.html
new file mode 100644
index 0000000..ca73750
--- /dev/null
+++ b/org.jacoco.doc/docroot/doc/offline.html
@@ -0,0 +1,97 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" lang="en">
+<head>
+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+ <link rel="stylesheet" href=".resources/doc.css" charset="UTF-8" type="text/css" />
+ <link rel="shortcut icon" href=".resources/report.gif" type="image/gif" />
+ <title>JaCoCo - Offline Instrumentation</title>
+</head>
+<body>
+
+<div class="breadcrumb">
+ <a href="../index.html" class="el_report">JaCoCo</a> >
+ <a href="index.html" class="el_group">Documentation</a> >
+ <span class="el_source">Offline Instrumentation</span>
+</div>
+<div id="content">
+
+<h1>Offline Instrumentation</h1>
+
+<p>
+ One of the main benefits of JaCoCo is the Java agent, which instruments
+ classes on-the-fly. This simplifies code coverage analysis a lot as no
+ pre-instrumentation and classpath tweaking is required. However, there can be
+ situations where on-the-fly instrumentation is not suitable, for example:
+</p>
+<ul>
+ <li>Runtime environments that do not support Java agents.</li>
+ <li>Deployments where it is not possible to configure JVM options.</li>
+ <li>Bytecode needs to be converted for another VM like the Android Dalvik VM.</li>
+ <li>Conflicts with other agents that do dynamic classfile transformation.</li>
+</ul>
+
+<p>
+ For such scenarios class files can be pre-instrumented with JaCoCo, for
+ example with the <a href="ant.html#instrument"><code>instrument</code></a>
+ Ant task. At runtime the pre-instrumented classes needs be on the classpath
+ instead of the original classes. In addition <code>jacocoagent.jar</code> must
+ be put on the classpath.
+</p>
+
+<h2>Configuration</h2>
+<p>
+ In offline mode the JaCoCo runtime can be configured with Java System
+ properties. The same set of properties as for the
+ <a href="agent.html">agent</a> is available, but prefixed with
+ "<code>jacoco.</code>". For example the location of the <code>*.exec</code>
+ file can be configured with the system property
+ "<code>jacoco.destfile</code>".
+</p>
+
+<h2>Class Loading and Initialization</h2>
+<p>
+ Unlike with on-the-fly instrumentation offline instrumented classes get a
+ direct dependency on the JaCoCo runtime. Therefore
+ <code>jacocoagent.jar</code> has to be on the classpath and accessible by the
+ instrumented classes. The proper location for <code>jacocoagent.jar</code>
+ might depend on your deployment scenario. The first instrumented class loaded
+ will trigger the initialization of the JaCoCo runtime. If no instrumented
+ class is loaded the JaCoCo runtime will not get started at all.
+</p>
+
+<h2>Using Pre-Instrumented Classes With the Java Agent</h2>
+<p>
+ It is possible to also use offline-instrumented classes with the JaCoCo Java
+ agent. In this case the configuration is taken from the agent options. The
+ agent must be configured in a way that pre-instrumented classes are excluded,
+ e.g. with <code>excludes=*</code>. Otherwise it will result in error messages
+ on the console if the agent instruments such classes again.
+</p>
+
+<h2>Execution Data Collection</h2>
+<p>
+ If <code>jacocoagent.jar</code> is used on the classpath it will collect
+ execution data the same way as used as a <a href="agent.html">Java agent</a>.
+ Depending on the <code>output</code> configuration execution data can be
+ collected via a remote connection or is written to the file system when the
+ JVM terminates. For the latter it is required that e.g. a <code>java</code>
+ task is executed with <code>fork="true"</code>.
+</p>
+
+<h2>Report Generation</h2>
+<p>
+ Based on the collected <code>*.exec</code> files reports can be created the
+ same way as for execution data collected with the Java agent. Note that for
+ report generation the original class files have to be supplied, not the
+ instrumented copies.
+</p>
+
+</div>
+<div class="footer">
+ <span class="right"><a href="@jacoco.home.url@">JaCoCo</a> @qualified.bundle.version@</span>
+ <a href="license.html">Copyright</a> © @copyright.years@ Mountainminds GmbH & Co. KG and Contributors
+</div>
+
+</body>
+</html>