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