<?xml version="1.0" encoding="ISO-8859-1" ?> | |
<!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=ISO-8859-1" /> | |
<link rel="stylesheet" href=".resources/doc.css" charset="ISO-8859-1" type="text/css" /> | |
<title>JaCoCo - Build</title> | |
</head> | |
<body> | |
<div class="breadcrumb"> | |
<a href="../index.html" class="el_session">JaCoCo</a> > | |
<a href="index.html" class="el_group">Documentation</a> > | |
<span class="el_source">Build</span> | |
</div> | |
<div id="content"> | |
<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. | |
</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. | |
</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"> | |
<span class="nr"> 1</span><path id="dependencies"> | |
<span class="nr"> 2</span> <path refid="bundle-org.jacoco.core"/> | |
<span class="nr"> 3</span> <path refid="bundle-org.objectweb.asm"/> | |
<span class="nr"> 4</span></path> | |
</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. | |
</p> | |
<h3>Custom Build Tasks</h3> | |
<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: | |
</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> | |
</div> | |
<div class="footer"> | |
<div class="versioninfo"><a href="@jacoco.home.url@">JaCoCo</a> @qualified.bundle.version@</div> | |
<a href="license.html">Copyright</a> © @copyright.years@ Mountainminds GmbH & Co. KG and Contributors | |
</div> | |
</body> | |
</html> |