Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / jacoco / cd103aff7f21fcd7c2ae147068e50e0255956bc9 / . / org.jacoco.doc / docroot / doc / build.html
blob: fd2144c7998e8de7b8a35a7fdc0116824cdea736 [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>
Marc R. Hoffmannc5321472010-04-01 18:03:47 +0000[diff] [blame]76 <td><code>legal</code></td>
77 <td>Verify license information in source headers.</td>
78 </tr>
79 <tr>
Marc R. Hoffmanncd59d2a2009-10-15 10:53:12 +0000[diff] [blame]80 <td><code>build</code></td>
Marc R. Hoffmannc5321472010-04-01 18:03:47 +0000[diff] [blame]81 <td>Compile, verify, package, verify license information and create documentation.</td>
Marc R. Hoffmanncd59d2a2009-10-15 10:53:12 +0000[diff] [blame]82 </tr>
83 <tr>
84 <td><code><b>rebuild</b></code></td>
85 <td>Clean and build (default target).</td>
86 </tr>
87 <tr>
88 <td><code>deliver</code></td>
89 <td>Rebuild and create a ZIP archive with checksum.</td>
90 </tr>
91 </tbody>
92</table>
93
94<p>
95 By default the build output is created directly in the build project folder
96 with the following structure. The <code>dist</code> folder contains all files
97 of the distribution which will be packed into a ZIP archive if the deliver
98 target was called.
99</p>
100
101<pre>
102 org.jacoco.build/
103 result/
104 dist/
105 tmp/
106 jacoco-&lt;version&gt;.zip
107 jacoco-&lt;version&gt;.zip.MD5
108</pre>
109
110<p class="hint">
111 If you edit the JaCoCo build files with the Eclipse Ant editor the file
112 <code>jacocoant.jar</code> might become locked until you exit Eclipse. In this
113 case subsequent builds will always fail as they can't write this file any
114 more. The reason is the code assist function for user defined tasks. Please
115 see the
116 <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]117 on how to configure the Ant Editor to avoid these locks.
Marc R. Hoffmanncd59d2a2009-10-15 10:53:12 +0000[diff] [blame]118</p>
119
120
121<h2>Customizing the Build</h2>
122
123<p>
124 The <code>build.xml</code> file defines default values for several properties
125 that can be overwritten from outside:
126</p>
127
128<table class="coverage">
129 <thead>
130 <tr>
131 <td>Property</td>
132 <td>Description</td>
133 <td>Default Value</td>
134 </tr>
135 </thead>
136 <tbody>
137 <tr>
138 <td><code>workspace.dir</code></td>
139 <td>Folder that contains the source of the JaCoCo bundles.</td>
140 <td><code>..</code></td>
141 </tr>
142 <tr>
143 <td><code>result.dir</code></td>
144 <td>Folder where all build results are written to.</td>
145 <td><code>./result</code></td>
146 </tr>
147 <tr>
148 <td><code>result.dist.dir</code></td>
149 <td>Folder where all build artifacts for distribution are written to.</td>
150 <td><code>${result.dir}/dist</code></td>
151 </tr>
152 <tr>
153 <td><code>result.tmp.dir</code></td>
154 <td>Folder for temporary build files.</td>
155 <td><code>${result.dir}/tmp</code></td>
156 </tr>
157 <tr>
158 <td><code>build.qualifier</code></td>
159 <td>Build qualifier that will be inserted into all bundle versions and documents.</td>
160 <td>Current timestamp.</td>
161 </tr>
162 <tr>
163 <td><code>jacoco.home.url</code></td>
164 <td>URL of the current home page for JaCoCo.</td>
165 <td><code>http://www.eclemma.org/jacoco</code></td>
166 </tr>
Marc R. Hoffmanncd103af2010-04-07 09:33:46 +0000[diff] [blame^]167 <tr>
168 <td><code>target.name</code></td>
169 <td>Name of the target environment to run the build against.</td>
170 <td><code>default</code></td>
171 </tr>
Marc R. Hoffmanncd59d2a2009-10-15 10:53:12 +0000[diff] [blame]172 </tbody>
173</table>
174
175<p>
176 The layout of the target platform might be customized in the
177 <code>target.xml</code> file.
178</p>
179
180<p class="hint">
Radek Libaad5fbc92009-10-26 13:26:53 +0000[diff] [blame]181 The file <code>build.properties</code> is part of the Eclipse PDE
Marc R. Hoffmanncd59d2a2009-10-15 10:53:12 +0000[diff] [blame]182 declarations and not (yet) used by the JaCoCo Ant build.
183</p>
184
185
186<h2>Internal Structure of the Build</h2>
187
188<p>
Radek Libaad5fbc92009-10-26 13:26:53 +0000[diff] [blame]189 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]190 on different machines. While the modularization mechanism is based on OSGi
191 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]192 The reason is that some JaCoCo artifacts like the <code>jacocoagent.jar</code>
193 have very specific packaging requirements.
Marc R. Hoffmanncd59d2a2009-10-15 10:53:12 +0000[diff] [blame]194</p>
195
196<h3>Structure of the Build Files</h3>
197
198<p>
199 The main <code>build.xml</code> calls the <code>buildbundle.xml</code> script
Marc R. Hoffmanncd103af2010-04-07 09:33:46 +0000[diff] [blame^]200 for each bundle. A <code>target_*.xml</code> file is included in the main
201 build file to define the structure of the target platform. Each bundle defines
202 its specific requirements in a local <code>buildhook.xml</code> file which is
203 included into the <code>buildbundle.xml</code> when the respective bundle is
204 build.
Marc R. Hoffmanncd59d2a2009-10-15 10:53:12 +0000[diff] [blame]205</p>
206
207<div style="padding-left:2em"><code><b>org.jacoco.build/build.xml</b></code></div>
Marc R. Hoffmanncd103af2010-04-07 09:33:46 +0000[diff] [blame^]208<div style="padding-left:4em">include <code><b>org.jacoco.build/target_${target.name}.xml</b></code></div>
Marc R. Hoffmanncd59d2a2009-10-15 10:53:12 +0000[diff] [blame]209<div style="padding-left:4em">for each bundle:</div>
210<div style="padding-left:6em">call <code><b>org.jacoco.build/buildbundle.xml</b></code>:</div>
211<div style="padding-left:8em">include <code><b>&lt;bundleid&gt;/buildhook.xml</b></code></div>
212
213<h3>Class Paths</h3>
214
215<p>
216 The class paths of all bundles are defined as <code>path</code> instances with
217 ids in the format <code>bundle-&lt;bundleid&gt;</code>. For the target
218 platform the paths are explicitly defined by the <code>target.xml</code> file.
219 For the JaCoCo bundles a respective path instance is automatically defined
220 after each bundle has been built.
221</p>
222
223<h3>Dependencies</h3>
224
225<p>
226 Dependencies are not automatically derived from declarations in the bundle
227 manifests. Instead the <code>buildhook.xml</code> files compose a new path
228 definition from the dependencies, for example:
229</p>
230
231<pre class="source">
232<span class="nr"> 1</span>&lt;path id="dependencies"&gt;
233<span class="nr"> 2</span> &lt;path refid="bundle-org.jacoco.core"/&gt;
234<span class="nr"> 3</span> &lt;path refid="bundle-org.objectweb.asm"/&gt;
235<span class="nr"> 4</span>&lt;/path>
236</pre>
237
238<p>
Marc R. Hoffmann52274cc2009-10-20 18:55:57 +0000[diff] [blame]239 In addition source items from other bundles can be referenced through the
240 property <code>source.<i>&lt;bundleid&gt;</i>.dir</code> which points
241 to the root folder of the respective bundle. A suitable build order for the
242 JaCoCo bundles is hard coded in the <code>build.xml</code> file.
Marc R. Hoffmanncd59d2a2009-10-15 10:53:12 +0000[diff] [blame]243</p>
244
245<h3>Custom Build Tasks</h3>
246
247<p>
248 The <code>org.jacoco.build</code> bundle implements a set of custom Ant tasks
249 and types that primarily help to implement specific packaging requirements:
250</p>
251
252<ul>
253 <li><b>Task <code>randomid</code>:</b> Creates a short random string which is
254 a valid Java identifier. This task is used to define unique package names
255 for all classes of the Java agent avoiding name clashes at runtime.</li>
256 <li><b>Type <code>deepclassfileset</code>:</b> Analyzes class file
257 dependencies recursively to select a subset of class files from a given
258 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]259 agent and the JaCoCo Ant library.</li>
Marc R. Hoffmanncd59d2a2009-10-15 10:53:12 +0000[diff] [blame]260 <li><b>Type <code>renamedclassfileset</code>:</b> Renames class files and
261 their dependencies to other class files based on a set of mapping rules.
262 This type is used to rename the classes for the Java agent.</li>
263</ul>
264
Marc R. Hoffmann17be2692010-02-02 05:44:47 +0000[diff] [blame]265</div>
Marc R. Hoffmanncd59d2a2009-10-15 10:53:12 +0000[diff] [blame]266<div class="footer">
267 <div class="versioninfo"><a href="@HOMEURL@">JaCoCo</a> @VERSION@</div>
Marc R. Hoffmann889d62b2010-01-26 20:08:15 +0000[diff] [blame]268 <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]269</div>
270
271</body>
272</html>