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