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