Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / jacoco / c5321473911179f88171c1c83ee61152eb287044 / . / org.jacoco.doc / docroot / doc / build.html
blob: 9143cc70de8d998c26bd5a330b9985fd5d8805cf [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>
167
168 </tbody>
169</table>
170
171<p>
172 The layout of the target platform might be customized in the
173 <code>target.xml</code> file.
174</p>
175
176<p class="hint">
Radek Libaad5fbc92009-10-26 13:26:53 +0000[diff] [blame]177 The file <code>build.properties</code> is part of the Eclipse PDE
Marc R. Hoffmanncd59d2a2009-10-15 10:53:12 +0000[diff] [blame]178 declarations and not (yet) used by the JaCoCo Ant build.
179</p>
180
181
182<h2>Internal Structure of the Build</h2>
183
184<p>
Radek Libaad5fbc92009-10-26 13:26:53 +0000[diff] [blame]185 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]186 on different machines. While the modularization mechanism is based on OSGi
187 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]188 The reason is that some JaCoCo artifacts like the <code>jacocoagent.jar</code>
189 have very specific packaging requirements.
Marc R. Hoffmanncd59d2a2009-10-15 10:53:12 +0000[diff] [blame]190</p>
191
192<h3>Structure of the Build Files</h3>
193
194<p>
195 The main <code>build.xml</code> calls the <code>buildbundle.xml</code> script
196 for each bundle. The <code>target.xml</code> file is included in the main
197 build file and defines the structure of the target platform. Each bundle
198 defines its specific requirements in a local <code>buildhook.xml</code> file
199 which is included into the <code>buildbundle.xml</code> when the respective
200 bundle is build.
201</p>
202
203<div style="padding-left:2em"><code><b>org.jacoco.build/build.xml</b></code></div>
204<div style="padding-left:4em">include <code><b>org.jacoco.build/target.xml</b></code></div>
205<div style="padding-left:4em">for each bundle:</div>
206<div style="padding-left:6em">call <code><b>org.jacoco.build/buildbundle.xml</b></code>:</div>
207<div style="padding-left:8em">include <code><b>&lt;bundleid&gt;/buildhook.xml</b></code></div>
208
209<h3>Class Paths</h3>
210
211<p>
212 The class paths of all bundles are defined as <code>path</code> instances with
213 ids in the format <code>bundle-&lt;bundleid&gt;</code>. For the target
214 platform the paths are explicitly defined by the <code>target.xml</code> file.
215 For the JaCoCo bundles a respective path instance is automatically defined
216 after each bundle has been built.
217</p>
218
219<h3>Dependencies</h3>
220
221<p>
222 Dependencies are not automatically derived from declarations in the bundle
223 manifests. Instead the <code>buildhook.xml</code> files compose a new path
224 definition from the dependencies, for example:
225</p>
226
227<pre class="source">
228<span class="nr"> 1</span>&lt;path id="dependencies"&gt;
229<span class="nr"> 2</span> &lt;path refid="bundle-org.jacoco.core"/&gt;
230<span class="nr"> 3</span> &lt;path refid="bundle-org.objectweb.asm"/&gt;
231<span class="nr"> 4</span>&lt;/path>
232</pre>
233
234<p>
Marc R. Hoffmann52274cc2009-10-20 18:55:57 +0000[diff] [blame]235 In addition source items from other bundles can be referenced through the
236 property <code>source.<i>&lt;bundleid&gt;</i>.dir</code> which points
237 to the root folder of the respective bundle. A suitable build order for the
238 JaCoCo bundles is hard coded in the <code>build.xml</code> file.
Marc R. Hoffmanncd59d2a2009-10-15 10:53:12 +0000[diff] [blame]239</p>
240
241<h3>Custom Build Tasks</h3>
242
243<p>
244 The <code>org.jacoco.build</code> bundle implements a set of custom Ant tasks
245 and types that primarily help to implement specific packaging requirements:
246</p>
247
248<ul>
249 <li><b>Task <code>randomid</code>:</b> Creates a short random string which is
250 a valid Java identifier. This task is used to define unique package names
251 for all classes of the Java agent avoiding name clashes at runtime.</li>
252 <li><b>Type <code>deepclassfileset</code>:</b> Analyzes class file
253 dependencies recursively to select a subset of class files from a given
254 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]255 agent and the JaCoCo Ant library.</li>
Marc R. Hoffmanncd59d2a2009-10-15 10:53:12 +0000[diff] [blame]256 <li><b>Type <code>renamedclassfileset</code>:</b> Renames class files and
257 their dependencies to other class files based on a set of mapping rules.
258 This type is used to rename the classes for the Java agent.</li>
259</ul>
260
Marc R. Hoffmann17be2692010-02-02 05:44:47 +0000[diff] [blame]261</div>
Marc R. Hoffmanncd59d2a2009-10-15 10:53:12 +0000[diff] [blame]262<div class="footer">
263 <div class="versioninfo"><a href="@HOMEURL@">JaCoCo</a> @VERSION@</div>
Marc R. Hoffmann889d62b2010-01-26 20:08:15 +0000[diff] [blame]264 <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]265</div>
266
267</body>
268</html>