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