Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / jacoco / f1e55913369ebe0579d34e442b89a9f9f0ce67b4 / . / org.jacoco.doc / docroot / doc / build.html
blob: 68adcda28675d38d89cffa906bc4be2af0e99d2d [file] [log] [blame]
Marc R. Hoffmanncd59d2a2009-10-15 10:53:12 +0000[diff] [blame]1<?xml version="1.0" encoding="ISO-8859-1" ?>
2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
3<html xmlns="http://www.w3.org/1999/xhtml" lang="en">
4<head>
5 <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" />
6 <link rel="stylesheet" href=".resources/doc.css" charset="ISO-8859-1" type="text/css" />
7 <title>JaCoCo - Build</title>
8</head>
9<body>
10
11<div class="breadcrumb">
12 <a href="../index.html" class="el_session">JaCoCo</a> &gt;
13 <a href="index.html" class="el_group">Documentation</a> &gt;
14 <span class="el_source">Build</span>
15</div>
16
17<h1>Build</h1>
18
19<p>
20 The JaCoCo build is fully based on
21 <a href="http://ant.apache.org/">Apache Ant</a>. The build can be locally
22 executed on every machine with a proper <a href="environment.html">environment
23 setup</a>. Basically the specified third party libraries and a proper JDK
24 version have to be available. Total build time is typically around 1 minute.
25 Developers are encouraged to run the build frequently to ensure consistency of
26 the source tree.
27</p>
28
29
30<h2>Running the Build</h2>
31
32<p>
33 The build can be started by executing the build file
34 <code>org.jacoco.build/build.xml</code> with <code>org.jacoco.build/</code> as
35 the working directory. From Eclipse simply right-click the
36 <code>build.xml</code> file and select <i>Run As &rarr; Ant Build...</i>
37 The only mandatory property that has to be provided is
38 <code>target.plugins.dir</code>, the location of the folder that contains the
39 target bundles.
40</p>
41
42<p>
43 The following build targets can be selected:
44</p>
45
46<table class="coverage">
47 <thead>
48 <tr>
49 <td>Target</td>
50 <td>Description</td>
51 </tr>
52 </thead>
53 <tbody>
54 <tr>
55 <td><code>clean</code></td>
56 <td>Delete all build artifacts including temporary files.</td>
57 </tr>
58 <tr>
59 <td><code>compile</code></td>
60 <td>Compile all Java source files.</td>
61 </tr>
62 <tr>
63 <td><code>verify</code></td>
64 <td>Run all regression tests.</td>
65 </tr>
66 <tr>
67 <td><code>package</code></td>
68 <td>Create bundle JARs.</td>
69 </tr>
70 <tr>
71 <td><code>doc</code></td>
72 <td>Generate documentation.</td>
73 </tr>
74 <tr>
75 <td><code>build</code></td>
76 <td>Compile, verify, package and create documentation.</td>
77 </tr>
78 <tr>
79 <td><code><b>rebuild</b></code></td>
80 <td>Clean and build (default target).</td>
81 </tr>
82 <tr>
83 <td><code>deliver</code></td>
84 <td>Rebuild and create a ZIP archive with checksum.</td>
85 </tr>
86 </tbody>
87</table>
88
89<p>
90 By default the build output is created directly in the build project folder
91 with the following structure. The <code>dist</code> folder contains all files
92 of the distribution which will be packed into a ZIP archive if the deliver
93 target was called.
94</p>
95
96<pre>
97 org.jacoco.build/
98 result/
99 dist/
100 tmp/
101 jacoco-&lt;version&gt;.zip
102 jacoco-&lt;version&gt;.zip.MD5
103</pre>
104
105<p class="hint">
106 If you edit the JaCoCo build files with the Eclipse Ant editor the file
107 <code>jacocoant.jar</code> might become locked until you exit Eclipse. In this
108 case subsequent builds will always fail as they can't write this file any
109 more. The reason is the code assist function for user defined tasks. Please
110 see the
111 <a href="http://help.eclipse.org/galileo/index.jsp?topic=/org.eclipse.platform.doc.user/reference/ref-antcodeassist.htm">Eclipse reference</a>
Radek Libaad5fbc92009-10-26 13:26:53 +0000[diff] [blame]112 on how to configure the Ant Editor to avoid these locks.
Marc R. Hoffmanncd59d2a2009-10-15 10:53:12 +0000[diff] [blame]113</p>
114
115
116<h2>Customizing the Build</h2>
117
118<p>
119 The <code>build.xml</code> file defines default values for several properties
120 that can be overwritten from outside:
121</p>
122
123<table class="coverage">
124 <thead>
125 <tr>
126 <td>Property</td>
127 <td>Description</td>
128 <td>Default Value</td>
129 </tr>
130 </thead>
131 <tbody>
132 <tr>
133 <td><code>workspace.dir</code></td>
134 <td>Folder that contains the source of the JaCoCo bundles.</td>
135 <td><code>..</code></td>
136 </tr>
137 <tr>
138 <td><code>result.dir</code></td>
139 <td>Folder where all build results are written to.</td>
140 <td><code>./result</code></td>
141 </tr>
142 <tr>
143 <td><code>result.dist.dir</code></td>
144 <td>Folder where all build artifacts for distribution are written to.</td>
145 <td><code>${result.dir}/dist</code></td>
146 </tr>
147 <tr>
148 <td><code>result.tmp.dir</code></td>
149 <td>Folder for temporary build files.</td>
150 <td><code>${result.dir}/tmp</code></td>
151 </tr>
152 <tr>
153 <td><code>build.qualifier</code></td>
154 <td>Build qualifier that will be inserted into all bundle versions and documents.</td>
155 <td>Current timestamp.</td>
156 </tr>
157 <tr>
158 <td><code>jacoco.home.url</code></td>
159 <td>URL of the current home page for JaCoCo.</td>
160 <td><code>http://www.eclemma.org/jacoco</code></td>
161 </tr>
162
163 </tbody>
164</table>
165
166<p>
167 The layout of the target platform might be customized in the
168 <code>target.xml</code> file.
169</p>
170
171<p class="hint">
Radek Libaad5fbc92009-10-26 13:26:53 +0000[diff] [blame]172 The file <code>build.properties</code> is part of the Eclipse PDE
Marc R. Hoffmanncd59d2a2009-10-15 10:53:12 +0000[diff] [blame]173 declarations and not (yet) used by the JaCoCo Ant build.
174</p>
175
176
177<h2>Internal Structure of the Build</h2>
178
179<p>
Radek Libaad5fbc92009-10-26 13:26:53 +0000[diff] [blame]180 JaCoCo is built by a set of custom Ant scripts that can be easily executed
Marc R. Hoffmanncd59d2a2009-10-15 10:53:12 +0000[diff] [blame]181 on different machines. While the modularization mechanism is based on OSGi
182 bundles, the build does not (yet) use a build system like PDE build or Maven.
Marc R. Hoffmannbe9fc252009-12-21 20:21:06 +0000[diff] [blame]183 The reason is that some JaCoCo artifacts like the <code>jacocoagent.jar</code>
184 have very specific packaging requirements.
Marc R. Hoffmanncd59d2a2009-10-15 10:53:12 +0000[diff] [blame]185</p>
186
187<h3>Structure of the Build Files</h3>
188
189<p>
190 The main <code>build.xml</code> calls the <code>buildbundle.xml</code> script
191 for each bundle. The <code>target.xml</code> file is included in the main
192 build file and defines the structure of the target platform. Each bundle
193 defines its specific requirements in a local <code>buildhook.xml</code> file
194 which is included into the <code>buildbundle.xml</code> when the respective
195 bundle is build.
196</p>
197
198<div style="padding-left:2em"><code><b>org.jacoco.build/build.xml</b></code></div>
199<div style="padding-left:4em">include <code><b>org.jacoco.build/target.xml</b></code></div>
200<div style="padding-left:4em">for each bundle:</div>
201<div style="padding-left:6em">call <code><b>org.jacoco.build/buildbundle.xml</b></code>:</div>
202<div style="padding-left:8em">include <code><b>&lt;bundleid&gt;/buildhook.xml</b></code></div>
203
204<h3>Class Paths</h3>
205
206<p>
207 The class paths of all bundles are defined as <code>path</code> instances with
208 ids in the format <code>bundle-&lt;bundleid&gt;</code>. For the target
209 platform the paths are explicitly defined by the <code>target.xml</code> file.
210 For the JaCoCo bundles a respective path instance is automatically defined
211 after each bundle has been built.
212</p>
213
214<h3>Dependencies</h3>
215
216<p>
217 Dependencies are not automatically derived from declarations in the bundle
218 manifests. Instead the <code>buildhook.xml</code> files compose a new path
219 definition from the dependencies, for example:
220</p>
221
222<pre class="source">
223<span class="nr"> 1</span>&lt;path id="dependencies"&gt;
224<span class="nr"> 2</span> &lt;path refid="bundle-org.jacoco.core"/&gt;
225<span class="nr"> 3</span> &lt;path refid="bundle-org.objectweb.asm"/&gt;
226<span class="nr"> 4</span>&lt;/path>
227</pre>
228
229<p>
Marc R. Hoffmann52274cc2009-10-20 18:55:57 +0000[diff] [blame]230 In addition source items from other bundles can be referenced through the
231 property <code>source.<i>&lt;bundleid&gt;</i>.dir</code> which points
232 to the root folder of the respective bundle. A suitable build order for the
233 JaCoCo bundles is hard coded in the <code>build.xml</code> file.
Marc R. Hoffmanncd59d2a2009-10-15 10:53:12 +0000[diff] [blame]234</p>
235
236<h3>Custom Build Tasks</h3>
237
238<p>
239 The <code>org.jacoco.build</code> bundle implements a set of custom Ant tasks
240 and types that primarily help to implement specific packaging requirements:
241</p>
242
243<ul>
244 <li><b>Task <code>randomid</code>:</b> Creates a short random string which is
245 a valid Java identifier. This task is used to define unique package names
246 for all classes of the Java agent avoiding name clashes at runtime.</li>
247 <li><b>Type <code>deepclassfileset</code>:</b> Analyzes class file
248 dependencies recursively to select a subset of class files from a given
249 file set. This type is used to package small all-in JARs for the Java
Marc R. Hoffmannbe9fc252009-12-21 20:21:06 +0000[diff] [blame]250 agent and the JaCoCo Ant library.</li>
Marc R. Hoffmanncd59d2a2009-10-15 10:53:12 +0000[diff] [blame]251 <li><b>Type <code>renamedclassfileset</code>:</b> Renames class files and
252 their dependencies to other class files based on a set of mapping rules.
253 This type is used to rename the classes for the Java agent.</li>
254</ul>
255
256<div class="footer">
257 <div class="versioninfo"><a href="@HOMEURL@">JaCoCo</a> @VERSION@</div>
258 <a href="license.html">Copyright</a> &copy; 2009 Mountainminds GmbH &amp; Co. KG and Contributors
259</div>
260
261</body>
262</html>