Update build documentation to new Maven build.
diff --git a/org.jacoco.doc/docroot/doc/build.html b/org.jacoco.doc/docroot/doc/build.html
index da97ccf..fce6880 100644
--- a/org.jacoco.doc/docroot/doc/build.html
+++ b/org.jacoco.doc/docroot/doc/build.html
@@ -21,249 +21,105 @@
<h1>Build</h1>
<p>
- The JaCoCo build is fully based on
- <a href="http://ant.apache.org/">Apache Ant</a>. The build can be locally
- executed on every machine with a proper <a href="environment.html">environment
- setup</a>. Basically the specified third party libraries and a proper JDK
- version have to be available. Total build time is typically around 1 minute.
- Developers are encouraged to run the build frequently to ensure consistency of
- the source tree.
+ The JaCoCo build is fully based on <a href="http://maven.apache.org/">Maven</a>
+ and its extension <a href="http://www.eclipse.org/tycho/">Tycho</a> to build
+ OSGi bundles based on the declations in their <code>MANIFEST.MF</code> file
+ ("manfest-first" approach). The build can be locally executed on every machine
+ with a proper <a href="environment.html">environment setup</a>. In particular
+ you need a <a href="http://maven.apache.org/">Maven 3</a> installation.
+ Developers are encouraged to run the build before every commit to ensure
+ consistency of the source tree.
</p>
<h2>Running the Build</h2>
<p>
- The build can be started by executing the build file
- <code>org.jacoco.build/build.xml</code> with <code>org.jacoco.build/</code> as
- the working directory. From Eclipse simply right-click the
- <code>build.xml</code> file and select <i>Run As → Ant Build...</i>
- The only mandatory property that has to be provided is
- <code>target.plugins.dir</code>, the location of the folder that contains the
- target bundles.
-</p>
-
-<p>
- The following build targets can be selected:
-</p>
-
-<table class="coverage">
- <thead>
- <tr>
- <td>Target</td>
- <td>Description</td>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td><code>clean</code></td>
- <td>Delete all build artifacts including temporary files.</td>
- </tr>
- <tr>
- <td><code>compile</code></td>
- <td>Compile all Java source files.</td>
- </tr>
- <tr>
- <td><code>verify</code></td>
- <td>Run all regression tests.</td>
- </tr>
- <tr>
- <td><code>package</code></td>
- <td>Create bundle JARs.</td>
- </tr>
- <tr>
- <td><code>doc</code></td>
- <td>Generate documentation.</td>
- </tr>
- <tr>
- <td><code>legal</code></td>
- <td>Verify license information in source headers.</td>
- </tr>
- <tr>
- <td><code>build</code></td>
- <td>Compile, verify, package, verify license information and create documentation.</td>
- </tr>
- <tr>
- <td><code><b>rebuild</b></code></td>
- <td>Clean and build (default target).</td>
- </tr>
- <tr>
- <td><code>deliver</code></td>
- <td>Rebuild and create a ZIP archive with checksum.</td>
- </tr>
- </tbody>
-</table>
-
-<p>
- By default the build output is created directly in the build project folder
- with the following structure. The <code>dist</code> folder contains all files
- of the distribution which will be packed into a ZIP archive if the deliver
- target was called.
+ The build can be started by executing the following command with
+ <code>./org.jacoco.build/</code> as the working directory:
</p>
<pre>
- org.jacoco.build/
- result/
- dist/
- tmp/
- jacoco-<version>.zip
- jacoco-<version>.zip.MD5
-</pre>
-
-<p class="hint">
- If you edit the JaCoCo build files with the Eclipse Ant editor the file
- <code>jacocoant.jar</code> might become locked until you exit Eclipse. In this
- case subsequent builds will always fail as they can't write this file any
- more. The reason is the code assist function for user defined tasks. Please
- see the
- <a href="http://help.eclipse.org/galileo/index.jsp?topic=/org.eclipse.platform.doc.user/reference/ref-antcodeassist.htm">Eclipse reference</a>
- on how to configure the Ant Editor to avoid these locks.
-</p>
-
-
-<h2>Customizing the Build</h2>
-
-<p>
- The <code>build.xml</code> file defines default values for several properties
- that can be overwritten from outside:
-</p>
-
-<table class="coverage">
- <thead>
- <tr>
- <td>Property</td>
- <td>Description</td>
- <td>Default Value</td>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td><code>workspace.dir</code></td>
- <td>Folder that contains the source of the JaCoCo bundles.</td>
- <td><code>..</code></td>
- </tr>
- <tr>
- <td><code>result.dir</code></td>
- <td>Folder where all build results are written to.</td>
- <td><code>./result</code></td>
- </tr>
- <tr>
- <td><code>result.dist.dir</code></td>
- <td>Folder where all build artifacts for distribution are written to.</td>
- <td><code>${result.dir}/dist</code></td>
- </tr>
- <tr>
- <td><code>result.tmp.dir</code></td>
- <td>Folder for temporary build files.</td>
- <td><code>${result.dir}/tmp</code></td>
- </tr>
- <tr>
- <td><code>build.qualifier</code></td>
- <td>Build qualifier that will be inserted into all bundle versions and documents.</td>
- <td>Current timestamp.</td>
- </tr>
- <tr>
- <td><code>jacoco.home.url</code></td>
- <td>URL of the current home page for JaCoCo.</td>
- <td><code>http://www.eclemma.org/jacoco</code></td>
- </tr>
- <tr>
- <td><code>target.name</code></td>
- <td>Name of the target environment to run the build against.</td>
- <td><code>default</code></td>
- </tr>
- </tbody>
-</table>
-
-<p>
- The layout of the target platform might be customized in the
- <code>target.xml</code> file.
-</p>
-
-<p class="hint">
- The file <code>build.properties</code> is part of the Eclipse PDE
- declarations and not (yet) used by the JaCoCo Ant build.
-</p>
-
-
-<h2>Internal Structure of the Build</h2>
-
-<p>
- JaCoCo is built by a set of custom Ant scripts that can be easily executed
- on different machines. While the modularization mechanism is based on OSGi
- bundles, the build does not (yet) use a build system like PDE build or Maven.
- The reason is that some JaCoCo artifacts like the <code>jacocoagent.jar</code>
- have very specific packaging requirements.
-</p>
-
-<h3>Structure of the Build Files</h3>
-
-<p>
- The main <code>build.xml</code> calls the <code>buildbundle.xml</code> script
- for each bundle. A <code>target_*.xml</code> file is included in the main
- build file to define the structure of the target platform. Each bundle defines
- its specific requirements in a local <code>buildhook.xml</code> file which is
- included into the <code>buildbundle.xml</code> when the respective bundle is
- build.
-</p>
-
-<div style="padding-left:2em"><code><b>org.jacoco.build/build.xml</b></code></div>
-<div style="padding-left:4em">include <code><b>org.jacoco.build/target_${target.name}.xml</b></code></div>
-<div style="padding-left:4em">for each bundle:</div>
-<div style="padding-left:6em">call <code><b>org.jacoco.build/buildbundle.xml</b></code>:</div>
-<div style="padding-left:8em">include <code><b><bundleid>/buildhook.xml</b></code></div>
-
-<h3>Class Paths</h3>
-
-<p>
- The class paths of all bundles are defined as <code>path</code> instances with
- ids in the format <code>bundle-<bundleid></code>. For the target
- platform the paths are explicitly defined by the <code>target.xml</code> file.
- For the JaCoCo bundles a respective path instance is automatically defined
- after each bundle has been built.
-</p>
-
-<h3>Dependencies</h3>
-
-<p>
- Dependencies are not automatically derived from declarations in the bundle
- manifests. Instead the <code>buildhook.xml</code> files compose a new path
- definition from the dependencies, for example:
-</p>
-
-<pre class="source linenums">
-<path id="dependencies">
- <path refid="bundle-org.jacoco.core"/>
- <path refid="bundle-org.objectweb.asm"/>
-</path>
+ mvn clean install
</pre>
<p>
- In addition source items from other bundles can be referenced through the
- property <code>source.<i><bundleid></i>.dir</code> which points
- to the root folder of the respective bundle. A suitable build order for the
- JaCoCo bundles is hard coded in the <code>build.xml</code> file.
+ Total build time is typically around 3 minutes, however first build might take
+ more time, because Maven should download plugins and dependencies. The
+ download ZIP will be created at the following location:
</p>
-<h3>Custom Build Tasks</h3>
+<pre>
+ ./org.jacoco.doc/target/jacoco-<i>x.y.z.qualifier</i>.zip
+</pre>
+
+
+<h2>Testing with different JDKs</h2>
<p>
- The <code>org.jacoco.build</code> bundle implements a set of custom Ant tasks
- and types that primarily help to implement specific packaging requirements:
+ Target Java version for JaCoCo builds is 1.5, however for verification
+ purposes you can execute tests using other versions. In order to do so, first
+ you should create file <code>toolchains.xml</code> in <code>~/.m2/</code>
+ directory. Here is an example of such file. For more information see
+ <a href="http://maven.apache.org/guides/mini/guide-using-toolchains.html">Maven
+ Guide to Using Toolchains</a>.
</p>
-<ul>
- <li><b>Task <code>randomid</code>:</b> Creates a short random string which is
- a valid Java identifier. This task is used to define unique package names
- for all classes of the Java agent avoiding name clashes at runtime.</li>
- <li><b>Type <code>deepclassfileset</code>:</b> Analyzes class file
- dependencies recursively to select a subset of class files from a given
- file set. This type is used to package small all-in JARs for the Java
- agent and the JaCoCo Ant library.</li>
- <li><b>Type <code>renamedclassfileset</code>:</b> Renames class files and
- their dependencies to other class files based on a set of mapping rules.
- This type is used to rename the classes for the Java agent.</li>
-</ul>
+<pre class="source lang-xml linenums">
+<?xml version="1.0" encoding="UTF8"?>
+<toolchains>
+ <toolchain>
+ <type>jdk</type>
+ <provides>
+ <id>java15</id>
+ <version>1.5</version>
+ <vendor>sun</vendor>
+ </provides>
+ <configuration>
+ <jdkHome>/usr/lib/jvm/sun-jdk-1.5</jdkHome>
+ </configuration>
+ </toolchain>
+ <toolchain>
+ <type>jdk</type>
+ <provides>
+ <id>java16</id>
+ <version>1.6</version>
+ <vendor>sun</vendor>
+ </provides>
+ <configuration>
+ <jdkHome>/usr/lib/jvm/sun-jdk-1.6</jdkHome>
+ </configuration>
+ </toolchain>
+ <toolchain>
+ <type>jdk</type>
+ <provides>
+ <id>java17</id>
+ <version>1.7</version>
+ <vendor>sun</vendor>
+ </provides>
+ <configuration>
+ <jdkHome>/usr/lib/jvm/sun-jdk-1.7</jdkHome>
+ </configuration>
+ </toolchain>
+</toolchains>
+</pre>
+
+<p>
+ Now you should be able to execute maven build with specified version of JDK:
+</p>
+
+<pre>
+ mvn clean install -Djdk.version=<i>version</i>
+</pre>
+
+<p>
+ Location of <code>toolchains.xml</code> can be set via an option:
+</p>
+
+<pre>
+ mvn --toolchains <i>path</i> clean install -Djdk.version=<i>version</i>
+</pre>
+
</div>
<div class="footer">
diff --git a/org.jacoco.doc/docroot/doc/environment.html b/org.jacoco.doc/docroot/doc/environment.html
index c5c5058..2334e0e 100644
--- a/org.jacoco.doc/docroot/doc/environment.html
+++ b/org.jacoco.doc/docroot/doc/environment.html
@@ -29,7 +29,7 @@
<h3>IDE</h3>
<p>
- JaCoCo development is done with the latest Eclipse version 3.6.x. JaCoCo
+ JaCoCo development is done with the latest Eclipse version 3.7.x. JaCoCo
projects are OSGi bundles, therefore the PDE feature is required. Project
specific Eclipse settings exist for the projects
</p>
@@ -47,8 +47,14 @@
<p>
The minimum JRE version to execute JaCoCo is Java 1.5. However to guarantee
- compatibility the JaCoCo build scripts enforce the use of a 1.5 JDK for the
- <code>deliver</code> target.
+ compatibility JaCoCo builds should only be executed against a 1.5 JDK.
+</p>
+
+<h3>Build System</h3>
+
+<p>
+ The build is based on <a href="http://maven.apache.org/">Maven</a>. The
+ JaCoCo <a href="build.html">build</a> requires Maven 3.
</p>
<h3>Third Party Dependencies</h3>
@@ -60,13 +66,12 @@
<ul>
<li>Apache Ant 1.7.x</li>
<li>JUnit 4</li>
- <li>Objectweb ASM 3.2.x</li>
+ <li>Objectweb ASM 3.3.x</li>
</ul>
<p>
-
- These bundles are included with Eclipse 3.6.x and are not part of the JaCoCo
- source tree.
+ These bundles are included with the Eclipse 3.7.x PDE feature and are not
+ part of the JaCoCo source tree.
</p>
<h3>Source Control</h3>