Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / jacoco / 8a831fed95f0ebfe7e9c8de0d7e040ebd909d90f / . / org.jacoco.doc / docroot / doc / ant.html
blob: 3aab115fe0db85d831a130b0daf42eaea7c6d9a3 [file] [log] [blame]
Marc R. Hoffmannf7d17522009-08-07 11:21:23 +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 - Ant Tasks</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">Ant Tasks</span>
15</div>
Marc R. Hoffmann17be2692010-02-02 05:44:47 +0000[diff] [blame]16<div id="content">
Marc R. Hoffmannf7d17522009-08-07 11:21:23 +0000[diff] [blame]17
18<h1>Ant Tasks</h1>
19
20<p>
21 JaCoCo comes with Ant tasks to launch Java programs with execution recording
Marc R. Hoffmannb8a77462009-08-21 14:53:50 +0000[diff] [blame]22 and for creating coverage reports from the recorded data. The JaCoCo Ant tasks
23 require
24</p>
25
26<ul>
27 <li>Ant 1.7.0 or higher and</li>
28 <li>Java 1.5 or higher (for both, the Ant runner and the test executor).</li>
29</ul>
30
31
Marc R. Hoffmann57f9ab42009-08-24 10:52:42 +0000[diff] [blame]32<p>All tasks are defined in <code>jacocoant.jar</code> (which is part of the
33 distribution) and can be included in your Ant scripts with the usual
34 <code>taskdef</code> declaration:
Marc R. Hoffmannf7d17522009-08-07 11:21:23 +0000[diff] [blame]35</p>
36
37<pre class="source">
38<span class="nr"> 1</span>&lt;project name="Example" xmlns:jacoco="antlib:org.jacoco.ant"&gt;
39<span class="nr"> 2</span>
40<span class="nr"> 3</span> &lt;taskdef uri="antlib:org.jacoco.ant" resource="org/jacoco/ant/antlib.xml"&gt;
41<span class="nr"> 4</span> &lt;classpath&gt;
Marc R. Hoffmanndb930772009-08-20 17:17:37 +0000[diff] [blame]42<span class="nr"> 5</span> &lt;pathelement location="<i>path_to_jacoco</i>/lib/jacocoant.jar"/&gt;
Marc R. Hoffmannf7d17522009-08-07 11:21:23 +0000[diff] [blame]43<span class="nr"> 6</span> &lt;/classpath&gt;
44<span class="nr"> 7</span> &lt;/taskdef&gt;
45<span class="nr"> 8</span>
46<span class="nr"> 9</span> ...
47<span class="nr"> 10</span>
48<span class="nr"> 11</span>&lt;/project&gt;
49</pre>
50
51<p>
Marc R. Hoffmanndb3e7d02009-08-12 10:57:39 +0000[diff] [blame]52 Alternatively you might also place the <code>jacocoant.jar</code> in your
53 Ant <code><i>ANT_HOME</i>/lib</code> folder. If you use the name space URI
54 <code>antlib:org.jacoco.ant</code> for JaCoCo tasks Ant will find them
55 automatically without the <code>taskdef</code> declaration above.
56</p>
57
58<p>
Marc R. Hoffmannf7d17522009-08-07 11:21:23 +0000[diff] [blame]59 Declaring a XML namespace for JaCoCo tasks is optional but always recommended
60 if you mix tasks from different libraries. All subsequent examples use the
61 <code>jacoco</code> prefix declared above.
62</p>
63
64
Brock Janiczakd267c572010-01-28 09:53:54 +0000[diff] [blame]65<h2><a name="coverage">Task <code>coverage</code></a></h2>
Marc R. Hoffmannf7d17522009-08-07 11:21:23 +0000[diff] [blame]66
67<p>
68 The standard Ant tasks to launch Java programs are <code>java</code> and
69 <code>junit</code>. To add code coverage recording to these tasks they can
70 simply be wrapped with the <code>coverage</code> task as shown in the
71 following examples:
72</p>
73
74<pre class="source">
75<span class="nr"> 1</span>&lt;jacoco:coverage>
76<span class="nr"> 2</span> &lt;java classname="org.jacoco.examples.HelloJaCoCo" fork="true"&gt;
77<span class="nr"> 3</span> &lt;classpath&gt;
78<span class="nr"> 4</span> &lt;pathelement location="./bin"/&gt;
79<span class="nr"> 5</span> &lt;/classpath&gt;
80<span class="nr"> 6</span> &lt;/java&gt;
81<span class="nr"> 7</span>&lt;/jacoco:coverage&gt;
82<span class="nr"> 8</span>
83<span class="nr"> 9</span>
84<span class="nr"> 10</span>&lt;jacoco:coverage>
85<span class="nr"> 11</span> &lt;junit fork="true" forkmode="once"&gt;
86<span class="nr"> 12</span> &lt;test name="org.jacoco.examples.HelloJaCoCoTest"/&gt;
87<span class="nr"> 13</span> &lt;classpath&gt;
88<span class="nr"> 14</span> &lt;pathelement location="./bin"/&gt;
89<span class="nr"> 15</span> &lt;/classpath&gt;
90<span class="nr"> 16</span> &lt;/junit&gt;
91<span class="nr"> 17</span>&lt;/jacoco:coverage>
92</pre>
93
94<p>
Radek Libaad5fbc92009-10-26 13:26:53 +0000[diff] [blame]95 Resulting coverage information is collected during execution and written
96 to a file when the process terminates. Note the <code>fork</code> attribute
97 above in the wrapped <code>java</code> task.
Marc R. Hoffmannf7d17522009-08-07 11:21:23 +0000[diff] [blame]98</p>
99
100<p class="hint">
101 The nested task always has to declare <code>fork="true"</code>, otherwise the
102 <code>coverage</code> task can't record coverage information and will fail.
103 In addition the <code>junit</code> task should declare
104 <code>forkmode="once"</code> to avoid starting a new JVM for every single test
105 case and decreasing execution performance dramatically (unless this is
106 required by the nature of the test cases).
107</p>
108
109<p>
110 The coverage task must wrap exactly one task. While it typically works without
111 any configuration, the behavior can be adjusted with some optional attributes:
112</p>
113
114<table class="coverage">
115 <thead>
116 <tr>
117 <td>Attribute</td>
118 <td>Description</td>
119 <td>Default</td>
120 </tr>
121 </thead>
122 <tbody>
123 <tr>
Brock Janiczakd267c572010-01-28 09:53:54 +0000[diff] [blame]124 <td><code>enabled</code></td>
125 <td>If set to <code>true</code> coverage data will be collected for the contained task.</td>
126 <td><code>true</code></td>
127 </tr>
Marc R. Hoffmanne3ef2f32010-01-28 18:17:46 +0000[diff] [blame]128 <tr>
Brock Janiczak003d47c2010-01-15 00:45:17 +0000[diff] [blame]129 <td><code>destfile</code></td>
Marc R. Hoffmannf7d17522009-08-07 11:21:23 +0000[diff] [blame]130 <td>Path to the output file for execution data.</td>
131 <td><code>jacoco.exec</code></td>
132 </tr>
133 <tr>
Brock Janiczak003d47c2010-01-15 00:45:17 +0000[diff] [blame]134 <td><code>append</code></td>
Marc R. Hoffmannf7d17522009-08-07 11:21:23 +0000[diff] [blame]135 <td>If set to <code>true</code> and the execution data file already
Brock Janiczak003d47c2010-01-15 00:45:17 +0000[diff] [blame]136 exists, coverage data is appended to the existing file. If set to
Marc R. Hoffmannf7d17522009-08-07 11:21:23 +0000[diff] [blame]137 <code>false</code>, an existing execution data file will be replaced.
138 </td>
139 <td><code>true</code></td>
140 </tr>
141 <tr>
Marc R. Hoffmanncf5345f2009-09-10 15:01:24 +0000[diff] [blame]142 <td><code>includes</code></td>
Radek Libaad5fbc92009-10-26 13:26:53 +0000[diff] [blame]143 <td>A list of class names that should be included in execution analysis.
Marc R. Hoffmanncf5345f2009-09-10 15:01:24 +0000[diff] [blame]144 The list entries are separated by a vertical bar (<code>|</code>) and
145 may use wildcard characters (<code>*</code> and <code>?</code>).
146 Except for performance optimization or technical corner cases this
147 option is normally not required.
148 </td>
149 <td><code>*</code> (all classes)</td>
150 </tr>
151 <tr>
152 <td><code>excludes</code></td>
153 <td>A list of class names that should be excluded from execution analysis.
154 The list entries are separated by a vertical bar (<code>|</code>) and
155 may use wildcard characters (<code>*</code> and <code>?</code>).
156 Except for performance optimization or technical corner cases this
157 option is normally not required.
158 </td>
159 <td><i>empty</i> (no excluded classes)</td>
160 </tr>
161 <tr>
Marc R. Hoffmannf7d17522009-08-07 11:21:23 +0000[diff] [blame]162 <td><code>exclclassloader</code></td>
Marc R. Hoffmann2a6b5bf2009-08-11 12:54:36 +0000[diff] [blame]163 <td>A list of class loader names, that should be excluded from execution
164 analysis. The list entries are separated by a vertical bar
165 (<code>|</code>) and may use wildcard characters (<code>*</code> and
166 <code>?</code>). This option might be required in case of special
Marc R. Hoffmann57f9ab42009-08-24 10:52:42 +0000[diff] [blame]167 frameworks that conflict with JaCoCo code instrumentation, in
168 particular class loaders that do not have access to the Java runtime
169 classes.
Marc R. Hoffmannf7d17522009-08-07 11:21:23 +0000[diff] [blame]170 </td>
171 <td><code>sun.reflect.DelegatingClassLoader</code></td>
172 </tr>
173 </tbody>
174</table>
175
176
Brock Janiczakd267c572010-01-28 09:53:54 +0000[diff] [blame]177<h2><a name="agent">Task <code>agent</code></a></h2>
Marc R. Hoffmannf7d17522009-08-07 11:21:23 +0000[diff] [blame]178
Marc R. Hoffmannd519add2009-08-11 11:09:29 +0000[diff] [blame]179<p>
180 If the <code>coverage</code> task is not suitable for your launch target, you
181 might alternatively use the <code>agent</code> task to create the Java agent
182 parameter. The following example defines a Ant property with the name
Radek Libaad5fbc92009-10-26 13:26:53 +0000[diff] [blame]183 <code>agentvmparam</code> that can be directly used as a Java VM parameter:
Marc R. Hoffmannd519add2009-08-11 11:09:29 +0000[diff] [blame]184</p>
185
186<pre class="source">
187<span class="nr"> 1</span>&lt;jacoco:agent property="agentvmparam"/>
188</pre>
189
190<p>
191 This task has the same attributes as the <code>coverage</code> task plus an
192 additional property to specify the target property name:
193</p>
194
195<table class="coverage">
196 <thead>
197 <tr>
198 <td>Attribute</td>
199 <td>Description</td>
200 <td>Default</td>
201 </tr>
202 </thead>
203 <tbody>
204 <tr>
Brock Janiczakd267c572010-01-28 09:53:54 +0000[diff] [blame]205 <td><code>enabled</code></td>
206 <td>When this variable is set to <code>false</code> the value of <code>property</code> will be set to an empty string, effectively
Marc R. Hoffmanne3ef2f32010-01-28 18:17:46 +0000[diff] [blame]207 disabling coverage instrumentation for any tasks that used the value.</td>
Brock Janiczakd267c572010-01-28 09:53:54 +0000[diff] [blame]208 <td><code>true</code></td>
209 </tr>
210 <tr>
Marc R. Hoffmannd519add2009-08-11 11:09:29 +0000[diff] [blame]211 <td><code>property</code></td>
212 <td>Name of the Ant property to set.</td>
213 <td><i>none (required)</i></td>
214 </tr>
Marc R. Hoffmann2bb6fca2009-08-13 14:04:21 +0000[diff] [blame]215 <tr>
216 <td colspan="3"><i>All attributes of the <code>coverage</code> task.</i></td>
217 </tr>
Marc R. Hoffmannd519add2009-08-11 11:09:29 +0000[diff] [blame]218 </tbody>
219</table>
220
Brock Janiczak74c16592010-01-29 21:34:14 +0000[diff] [blame]221
222<h2><a name="merge">Task <code>merge</code></a></h2>
223
224<p>
225 This task can be used to merge the execution data from multiple test runs
226 into a single data store.
227</p>
228
229<pre class="source">
230<span class="nr"> 1</span>&lt;jacoco:merge destfile="merged.exec"/>
231<span class="nr"> 2</span> &lt;fileset dir="executionData" includes="*.exec"/>
232<span class="nr"> 3</span>&lt;/jacoco:merge/>
233</pre>
234
235<p>
236 The task definition can contain any number of resource collection types and
237 has the following mandatory attribute:
238</p>
239
240<table class="coverage">
241 <thead>
242 <tr>
243 <td>Attribute</td>
244 <td>Description</td>
245 <td>Default</td>
246 </tr>
247 </thead>
248 <tbody>
249 <tr>
250 <td><code>destfile</code></td>
251 <td>Location to write the merged execution data.</td>
252 <td><i>none (required)</i></td>
253 </tr>
254 </tbody>
255</table>
256
257
Brock Janiczakd267c572010-01-28 09:53:54 +0000[diff] [blame]258<h2><a name="report">Task <code>report</code></a></h2>
Marc R. Hoffmannf7d17522009-08-07 11:21:23 +0000[diff] [blame]259
Marc R. Hoffmann2bb6fca2009-08-13 14:04:21 +0000[diff] [blame]260<p>
261 Finally different reports can be created with the <code>report</code> task.
262 A report task declaration consists of different sections, two specify the
263 input data, additional ones specify the output formats:
264</p>
265
266<pre class="source">
267<span class="nr"> 1</span>&lt;jacoco:report&gt;
268<span class="nr"> 2</span>
269<span class="nr"> 3</span> &lt;executiondata&gt;
270<span class="nr"> 4</span> &lt;file file="jacoco.exec"/&gt;
271<span class="nr"> 5</span> &lt;/executiondata&gt;
272<span class="nr"> 6</span>
273<span class="nr"> 7</span> &lt;structure name="Example Project"&gt;
274<span class="nr"> 8</span> &lt;classfiles&gt;
275<span class="nr"> 9</span> &lt;fileset dir="bin"/&gt;
276<span class="nr"> 10</span> &lt;/classfiles&gt;
277<span class="nr"> 11</span> &lt;sourcefiles encoding="UTF-8"&gt;
278<span class="nr"> 12</span> &lt;fileset dir="src"/&gt;
279<span class="nr"> 13</span> &lt;/sourcefiles&gt;
280<span class="nr"> 14</span> &lt;/structure&gt;
281<span class="nr"> 15</span>
282<span class="nr"> 16</span> &lt;html destdir="report"/&gt;
283<span class="nr"> 17</span>
284<span class="nr"> 18</span>&lt;/jacoco:report&gt;
285</pre>
286
287<p>
288 As you can see from the example above the <code>report</code> task is based
289 on several nested elements:
290</p>
291
292<h3>Element <code>executiondata</code></h3>
293
294<p>
295 Within this element Ant resources and resource collections can be specified,
296 that represent JaCoCo execution data files. If more than one execution data
297 file is specified, execution data is combined. A particular piece of code is
Radek Libaad5fbc92009-10-26 13:26:53 +0000[diff] [blame]298 considered executed when it is marked as such in any of the input files.
Marc R. Hoffmann2bb6fca2009-08-13 14:04:21 +0000[diff] [blame]299</p>
300
301<h3>Element <code>structure</code></h3>
302
303<p>
Radek Libaad5fbc92009-10-26 13:26:53 +0000[diff] [blame]304 This element defines the report structure. It might contain the following
Marc R. Hoffmann2bb6fca2009-08-13 14:04:21 +0000[diff] [blame]305 nested elements:
306</p>
307
308<ul>
309 <li><code>classfiles</code>: Container element for Ant resources and resource
310 collections that can specify Java class files, JAR files or directories
311 containing class files.</li>
312 <li><code>sourcefiles</code>: Optional container element for Ant resources and
313 resource collections that specify corresponding source files. The element
314 has an optional attribute <code>encoding</code> to specify the character
315 encoding of the source files. If no encoding is given, the platform default
316 is used. If source files are specified, some report formats include
Radek Libaad5fbc92009-10-26 13:26:53 +0000[diff] [blame]317 highlighted source code.</li>
Marc R. Hoffmann2bb6fca2009-08-13 14:04:21 +0000[diff] [blame]318</ul>
319
320<p>
321 The structure can be refined with a hierarchy of <code>group</code> elements.
Radek Libaad5fbc92009-10-26 13:26:53 +0000[diff] [blame]322 This way the coverage report can reflect different modules of a software
Marc R. Hoffmann2bb6fca2009-08-13 14:04:21 +0000[diff] [blame]323 project. For each group element the corresponding class and source files can
Radek Libaad5fbc92009-10-26 13:26:53 +0000[diff] [blame]324 be specified separately. For example, the build script of JaCoCo itself
Marc R. Hoffmann2bb6fca2009-08-13 14:04:21 +0000[diff] [blame]325 contains the following declaration to separate the different bundles in the
326 report (see the <a href="../coverage/index.html">resulting report</a>):
327</p>
328
329<pre class="source">
330<span class="nr"> 1</span>&lt;structure name="JaCoCo"&gt;
331<span class="nr"> 2</span> &lt;group name="org.jacoco.core"&gt;
332<span class="nr"> 3</span> &lt;classfiles&gt;
333<span class="nr"> 4</span> &lt;path refid="bundle-org.jacoco.core"/&gt;
334<span class="nr"> 5</span> &lt;/classfiles&gt;
335<span class="nr"> 6</span> &lt;sourcefiles&gt;
336<span class="nr"> 7</span> &lt;fileset dir="${workspace.dir}/org.jacoco.core/src"/&gt;
337<span class="nr"> 8</span> &lt;/sourcefiles&gt;
338<span class="nr"> 9</span> &lt;/group&gt;
339<span class="nr"> 10</span> &lt;group name="org.jacoco.report"&gt;
340<span class="nr"> 11</span> &lt;classfiles&gt;
341<span class="nr"> 12</span> &lt;path refid="bundle-org.jacoco.report"/&gt;
342<span class="nr"> 13</span> &lt;/classfiles&gt;
343<span class="nr"> 14</span> &lt;sourcefiles&gt;
344<span class="nr"> 15</span> &lt;fileset dir="${workspace.dir}/org.jacoco.report/src"/&gt;
345<span class="nr"> 16</span> &lt;/sourcefiles&gt;
346<span class="nr"> 17</span> &lt;/group&gt;
347<span class="nr"> 18</span>
348<span class="nr"> 19</span> ...
349<span class="nr"> 20</span>
350<span class="nr"> 21</span>&lt;/structure&gt;
351</pre>
352
353<h3>Element <code>html</code></h3>
354
355<p>
356 Create a multi-page report in HTML format.
357</p>
358
359<table class="coverage">
360 <thead>
361 <tr>
362 <td>Attribute</td>
363 <td>Description</td>
364 <td>Default</td>
365 </tr>
366 </thead>
367 <tbody>
368 <tr>
369 <td><code>destdir</code></td>
370 <td>Directory to create the report in.</td>
371 <td><i>none (required)</i></td>
372 </tr>
Marc R. Hoffmann2ecbea52009-09-03 14:19:11 +0000[diff] [blame]373 <tr>
374 <td><code>footer</code></td>
375 <td>Footer text for each report page.</td>
376 <td><i>No footer</i></td>
377 </tr>
Marc R. Hoffmann2becd332009-10-07 16:13:17 +0000[diff] [blame]378 <tr>
379 <td><code>encoding</code></td>
380 <td>Encoding of the generated HTML pages.</td>
381 <td><code>UTF-8</code></td>
382 </tr>
383 </tbody>
384</table>
385
386<h3>Element <code>xml</code></h3>
387
388<p>
389 Create a single-file report in XML format.
390</p>
391
392<table class="coverage">
393 <thead>
394 <tr>
395 <td>Attribute</td>
396 <td>Description</td>
397 <td>Default</td>
398 </tr>
399 </thead>
400 <tbody>
401 <tr>
Marc R. Hoffmann88b3f2f2009-10-19 16:10:35 +0000[diff] [blame]402 <td><code>destfile</code></td>
403 <td>Location to write the report file to.</td>
Marc R. Hoffmann2becd332009-10-07 16:13:17 +0000[diff] [blame]404 <td><i>none (required)</i></td>
405 </tr>
406 <tr>
407 <td><code>encoding</code></td>
408 <td>Encoding of the generated XML document.</td>
409 <td><code>UTF-8</code></td>
410 </tr>
Marc R. Hoffmann2bb6fca2009-08-13 14:04:21 +0000[diff] [blame]411 </tbody>
412</table>
413
414<h3>Element <code>csv</code></h3>
415
416<p>
Marc R. Hoffmann2becd332009-10-07 16:13:17 +0000[diff] [blame]417 Create single-file report in CSV format.
Marc R. Hoffmann2bb6fca2009-08-13 14:04:21 +0000[diff] [blame]418</p>
419
420<table class="coverage">
421 <thead>
422 <tr>
423 <td>Attribute</td>
424 <td>Description</td>
425 <td>Default</td>
426 </tr>
427 </thead>
428 <tbody>
429 <tr>
Marc R. Hoffmann88b3f2f2009-10-19 16:10:35 +0000[diff] [blame]430 <td><code>destfile</code></td>
431 <td>Location to write the report file to.</td>
Marc R. Hoffmann2bb6fca2009-08-13 14:04:21 +0000[diff] [blame]432 <td><i>none (required)</i></td>
433 </tr>
Marc R. Hoffmanne17fd112009-10-19 15:27:04 +0000[diff] [blame]434 <tr>
435 <td><code>encoding</code></td>
436 <td>Encoding of the generated CSV document.</td>
437 <td><code>UTF-8</code></td>
438 </tr>
Marc R. Hoffmann2bb6fca2009-08-13 14:04:21 +0000[diff] [blame]439 </tbody>
440</table>
441
Marc R. Hoffmann17be2692010-02-02 05:44:47 +0000[diff] [blame]442</div>
Marc R. Hoffmannf7d17522009-08-07 11:21:23 +0000[diff] [blame]443<div class="footer">
444 <div class="versioninfo"><a href="@HOMEURL@">JaCoCo</a> @VERSION@</div>
Marc R. Hoffmann889d62b2010-01-26 20:08:15 +0000[diff] [blame]445 <a href="license.html">Copyright</a> &copy; 2009, 2010 Mountainminds GmbH &amp; Co. KG and Contributors
Marc R. Hoffmannf7d17522009-08-07 11:21:23 +0000[diff] [blame]446</div>
447
448</body>
449</html>