Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / jacoco / 5625ff67708fb53682d6574d4360ac2a9ca00b71 / . / org.jacoco.doc / docroot / doc / ant.html
blob: 068477fa4f617cfbf8ffcc1b2f612e4f6ef24417 [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" />
Marc R. Hoffmanna760f322010-03-10 22:23:52 +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. Hoffmanna760f322010-03-10 22:23:52 +0000[diff] [blame]9 <script type="text/javascript" src="../coverage/.resources/prettify.js"></script>
Marc R. Hoffmannf7d17522009-08-07 11:21:23 +0000[diff] [blame]10 <title>JaCoCo - Ant Tasks</title>
11</head>
Marc R. Hoffmanna760f322010-03-10 22:23:52 +0000[diff] [blame]12<body onload="prettyPrint()">
Marc R. Hoffmannf7d17522009-08-07 11:21:23 +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. Hoffmannf7d17522009-08-07 11:21:23 +0000[diff] [blame]16 <a href="index.html" class="el_group">Documentation</a> &gt;
17 <span class="el_source">Ant Tasks</span>
18</div>
Marc R. Hoffmann17be2692010-02-02 05:44:47 +0000[diff] [blame]19<div id="content">
Marc R. Hoffmannf7d17522009-08-07 11:21:23 +0000[diff] [blame]20
21<h1>Ant Tasks</h1>
22
23<p>
24 JaCoCo comes with Ant tasks to launch Java programs with execution recording
Marc R. Hoffmann6fd10ff2010-06-02 21:42:25 +0000[diff] [blame]25 and for creating coverage reports from the recorded data. Execution data can
26 be collected and managed with the tasks
27 <a href="#coverage"><code>coverage</code></a>,
28 <a href="#agent"><code>agent</code></a>,
29 <a href="#dump"><code>dump</code></a> and
30 <a href="#merge"><code>merge</code></a>. Reports in different formats are
31 creates with the <a href="#report"><code>report</code></a> task.
32</p>
33
Marc R. Hoffmannc5d6e802010-07-02 19:34:16 +0000[diff] [blame]34<p class="hint">
35 If you want to have line number information included in the coverage reports
36 or you want source code highlighting the class files of the test target must
37 be compiled with debug information.
38</p>
39
Marc R. Hoffmann6fd10ff2010-06-02 21:42:25 +0000[diff] [blame]40<h2>Example</h2>
41
42<p>
43 The JaCoCo distribution contains a simple example how code coverage can be
44 added to a Ant based build. The
45 <a href="examples/ant/build.xml">build script</a> compiles Java sources, runs
46 the test program and creates a coverage report. The complete example is
47 located in the <code>./doc/examples/ant</code> folder of the distribution.
48</p>
49
50
51<h2>Prerequisites</h2>
52
53<p>
54 The JaCoCo Ant tasks require
Marc R. Hoffmannb8a77462009-08-21 14:53:50 +0000[diff] [blame]55</p>
56
57<ul>
58 <li>Ant 1.7.0 or higher and</li>
59 <li>Java 1.5 or higher (for both, the Ant runner and the test executor).</li>
60</ul>
61
62
Marc R. Hoffmann57f9ab42009-08-24 10:52:42 +0000[diff] [blame]63<p>All tasks are defined in <code>jacocoant.jar</code> (which is part of the
64 distribution) and can be included in your Ant scripts with the usual
65 <code>taskdef</code> declaration:
Marc R. Hoffmannf7d17522009-08-07 11:21:23 +0000[diff] [blame]66</p>
67
Marc R. Hoffmann0fd9c832011-03-16 20:42:40 +0000[diff] [blame]68<pre class="source lang-xml linenums">
69&lt;project name="Example" xmlns:jacoco="antlib:org.jacoco.ant"&gt;
70
71 &lt;taskdef uri="antlib:org.jacoco.ant" resource="org/jacoco/ant/antlib.xml"&gt;
72 &lt;classpath path="<i>path_to_jacoco</i>/lib/jacocoant.jar"/&gt;
73 &lt;/taskdef&gt;
74
75 ...
76
77&lt;/project&gt;
Marc R. Hoffmannf7d17522009-08-07 11:21:23 +0000[diff] [blame]78</pre>
79
80<p>
Marc R. Hoffmanndb3e7d02009-08-12 10:57:39 +0000[diff] [blame]81 Alternatively you might also place the <code>jacocoant.jar</code> in your
82 Ant <code><i>ANT_HOME</i>/lib</code> folder. If you use the name space URI
83 <code>antlib:org.jacoco.ant</code> for JaCoCo tasks Ant will find them
Marc R. Hoffmann6fd10ff2010-06-02 21:42:25 +0000[diff] [blame]84 automatically without the <code>taskdef</code> declaration above. Declaring a
85 XML namespace for JaCoCo tasks is optional but always recommended if you mix
86 tasks from different libraries. All subsequent examples use the
Marc R. Hoffmannf7d17522009-08-07 11:21:23 +0000[diff] [blame]87 <code>jacoco</code> prefix declared above.
88</p>
89
Brock Janiczakd267c572010-01-28 09:53:54 +0000[diff] [blame]90<h2><a name="coverage">Task <code>coverage</code></a></h2>
Marc R. Hoffmannf7d17522009-08-07 11:21:23 +0000[diff] [blame]91
92<p>
Evgeny Mandrikov71b5f6e2011-02-19 22:55:47 +0000[diff] [blame]93 The standard Ant tasks to launch Java programs are <code>java</code>, <code>junit</code> and
94 <code>testng</code>. To add code coverage recording to these tasks they can
Marc R. Hoffmannf7d17522009-08-07 11:21:23 +0000[diff] [blame]95 simply be wrapped with the <code>coverage</code> task as shown in the
96 following examples:
97</p>
98
Marc R. Hoffmann0fd9c832011-03-16 20:42:40 +0000[diff] [blame]99<pre class="source lang-xml linenums">
100&lt;jacoco:coverage>
101 &lt;java classname="org.jacoco.examples.HelloJaCoCo" fork="true"&gt;
102 &lt;classpath&gt;
103 &lt;pathelement location="./bin"/&gt;
104 &lt;/classpath&gt;
105 &lt;/java&gt;
106&lt;/jacoco:coverage&gt;
107
108
109&lt;jacoco:coverage>
110 &lt;junit fork="true" forkmode="once"&gt;
111 &lt;test name="org.jacoco.examples.HelloJaCoCoTest"/&gt;
112 &lt;classpath&gt;
113 &lt;pathelement location="./bin"/&gt;
114 &lt;/classpath&gt;
115 &lt;/junit&gt;
116&lt;/jacoco:coverage&gt;
Marc R. Hoffmannf7d17522009-08-07 11:21:23 +0000[diff] [blame]117</pre>
118
119<p>
Radek Libaad5fbc92009-10-26 13:26:53 +0000[diff] [blame]120 Resulting coverage information is collected during execution and written
121 to a file when the process terminates. Note the <code>fork</code> attribute
122 above in the wrapped <code>java</code> task.
Marc R. Hoffmannf7d17522009-08-07 11:21:23 +0000[diff] [blame]123</p>
124
125<p class="hint">
126 The nested task always has to declare <code>fork="true"</code>, otherwise the
127 <code>coverage</code> task can't record coverage information and will fail.
128 In addition the <code>junit</code> task should declare
129 <code>forkmode="once"</code> to avoid starting a new JVM for every single test
130 case and decreasing execution performance dramatically (unless this is
131 required by the nature of the test cases).
132</p>
133
134<p>
135 The coverage task must wrap exactly one task. While it typically works without
136 any configuration, the behavior can be adjusted with some optional attributes:
137</p>
138
139<table class="coverage">
140 <thead>
141 <tr>
142 <td>Attribute</td>
143 <td>Description</td>
144 <td>Default</td>
145 </tr>
146 </thead>
147 <tbody>
148 <tr>
Brock Janiczakd267c572010-01-28 09:53:54 +0000[diff] [blame]149 <td><code>enabled</code></td>
150 <td>If set to <code>true</code> coverage data will be collected for the contained task.</td>
151 <td><code>true</code></td>
152 </tr>
Marc R. Hoffmanne3ef2f32010-01-28 18:17:46 +0000[diff] [blame]153 <tr>
Brock Janiczak003d47c2010-01-15 00:45:17 +0000[diff] [blame]154 <td><code>destfile</code></td>
Marc R. Hoffmannf7d17522009-08-07 11:21:23 +0000[diff] [blame]155 <td>Path to the output file for execution data.</td>
156 <td><code>jacoco.exec</code></td>
157 </tr>
158 <tr>
Brock Janiczak003d47c2010-01-15 00:45:17 +0000[diff] [blame]159 <td><code>append</code></td>
Marc R. Hoffmannf7d17522009-08-07 11:21:23 +0000[diff] [blame]160 <td>If set to <code>true</code> and the execution data file already
Brock Janiczak003d47c2010-01-15 00:45:17 +0000[diff] [blame]161 exists, coverage data is appended to the existing file. If set to
Marc R. Hoffmannf7d17522009-08-07 11:21:23 +0000[diff] [blame]162 <code>false</code>, an existing execution data file will be replaced.
163 </td>
164 <td><code>true</code></td>
165 </tr>
166 <tr>
Marc R. Hoffmanncf5345f2009-09-10 15:01:24 +0000[diff] [blame]167 <td><code>includes</code></td>
Radek Libaad5fbc92009-10-26 13:26:53 +0000[diff] [blame]168 <td>A list of class names that should be included in execution analysis.
Evgeny Mandrikovbab5da42011-02-20 21:43:33 +0000[diff] [blame]169 The list entries are separated by a colon (<code>:</code>) and
Marc R. Hoffmanncf5345f2009-09-10 15:01:24 +0000[diff] [blame]170 may use wildcard characters (<code>*</code> and <code>?</code>).
171 Except for performance optimization or technical corner cases this
172 option is normally not required.
173 </td>
174 <td><code>*</code> (all classes)</td>
175 </tr>
176 <tr>
177 <td><code>excludes</code></td>
178 <td>A list of class names that should be excluded from execution analysis.
Evgeny Mandrikovbab5da42011-02-20 21:43:33 +0000[diff] [blame]179 The list entries are separated by a colon (<code>:</code>) and
Marc R. Hoffmanncf5345f2009-09-10 15:01:24 +0000[diff] [blame]180 may use wildcard characters (<code>*</code> and <code>?</code>).
181 Except for performance optimization or technical corner cases this
182 option is normally not required.
183 </td>
184 <td><i>empty</i> (no excluded classes)</td>
185 </tr>
186 <tr>
Marc R. Hoffmannf7d17522009-08-07 11:21:23 +0000[diff] [blame]187 <td><code>exclclassloader</code></td>
Marc R. Hoffmann2a6b5bf2009-08-11 12:54:36 +0000[diff] [blame]188 <td>A list of class loader names, that should be excluded from execution
Evgeny Mandrikovbab5da42011-02-20 21:43:33 +0000[diff] [blame]189 analysis. The list entries are separated by a colon
190 (<code>:</code>) and may use wildcard characters (<code>*</code> and
Marc R. Hoffmann2a6b5bf2009-08-11 12:54:36 +0000[diff] [blame]191 <code>?</code>). This option might be required in case of special
Marc R. Hoffmann57f9ab42009-08-24 10:52:42 +0000[diff] [blame]192 frameworks that conflict with JaCoCo code instrumentation, in
193 particular class loaders that do not have access to the Java runtime
194 classes.
Marc R. Hoffmannf7d17522009-08-07 11:21:23 +0000[diff] [blame]195 </td>
196 <td><code>sun.reflect.DelegatingClassLoader</code></td>
197 </tr>
Brock Janiczakf2d6f882010-05-04 06:47:40 +0000[diff] [blame]198 <tr>
Marc R. Hoffmannadfa1182010-05-05 12:59:42 +0000[diff] [blame]199 <td><code>sessionid</code></td>
200 <td>A session identifier that is written with the execution data. Without
201 this parameter a random identifier is created by the agent.
202 </td>
203 <td><i>auto-generated</i></td>
204 </tr>
205 <tr>
Brock Janiczakf2d6f882010-05-04 06:47:40 +0000[diff] [blame]206 <td><code>dumponexit</code></td>
Marc R. Hoffmannadfa1182010-05-05 12:59:42 +0000[diff] [blame]207 <td>If set to <code>true</code> coverage data will be written on VM
208 shutdown.
209 </td>
Brock Janiczakf2d6f882010-05-04 06:47:40 +0000[diff] [blame]210 <td><code>true</code></td>
211 </tr>
Marc R. Hoffmann4c3512a2010-05-12 08:50:23 +0000[diff] [blame]212 <tr>
213 <td><code>output</code></td>
214 <td>Output method to use for writing coverage data. Valid options are:
215 <ul>
216 <li><code>file</code>: At VM termination execution data is written to
217 the file specified in the <code>tofile</code> attribute.</li>
218 <li><code>tcpserver</code>: The agent listens for incoming connections
219 on the TCP port specified by the <code>address</code> and
220 <code>port</code> attribute. Execution data is written to this
221 TCP connection.</li>
222 <li><code>tcpclient</code>: At startup the agent connects to the TCP
223 port specified by the <code>address</code> and <code>port</code>
224 attribute. Execution data is written to this TCP connection.</li>
225 </ul>
226 </td>
227 <td><code>file</code></td>
228 </tr>
229 <tr>
230 <td><code>address</code></td>
231 <td>IP address or hostname to bind to when the output method is
232 <code>tcpserver</code> or connect to when the output method is
Marc R. Hoffmann1cf157a2010-06-04 05:54:48 +0000[diff] [blame]233 <code>tcpclient</code>. In <code>tcpserver</code> mode the value
234 "<code>*</code>" causes the agent to accept connections on any local
235 address.
Marc R. Hoffmann4c3512a2010-05-12 08:50:23 +0000[diff] [blame]236 </td>
Marc R. Hoffmann1cf157a2010-06-04 05:54:48 +0000[diff] [blame]237 <td><i>loopback interface</i></td>
Marc R. Hoffmann4c3512a2010-05-12 08:50:23 +0000[diff] [blame]238 </tr>
239 <tr>
240 <td><code>port</code></td>
241 <td>Port to bind to when the output method is <code>tcpserver</code> or
242 connect to when the output method is <code>tcpclient</code>. In
243 <code>tcpserver</code> mode the port must be available, which means
244 that if multiple JaCoCo agents should run on the same machine,
245 different ports have to be specified.
246 </td>
247 <td><code>6300</code></td>
248 </tr>
Marc R. Hoffmannf7d17522009-08-07 11:21:23 +0000[diff] [blame]249 </tbody>
250</table>
251
252
Brock Janiczakd267c572010-01-28 09:53:54 +0000[diff] [blame]253<h2><a name="agent">Task <code>agent</code></a></h2>
Marc R. Hoffmannf7d17522009-08-07 11:21:23 +0000[diff] [blame]254
Marc R. Hoffmannd519add2009-08-11 11:09:29 +0000[diff] [blame]255<p>
256 If the <code>coverage</code> task is not suitable for your launch target, you
Marc R. Hoffmann6fd10ff2010-06-02 21:42:25 +0000[diff] [blame]257 might alternatively use the <code>agent</code> task to create the
258 <a href="agent.html">Java agent</a> parameter. The following example defines a
259 Ant property with the name <code>agentvmparam</code> that can be directly used
260 as a Java VM parameter:
Marc R. Hoffmannd519add2009-08-11 11:09:29 +0000[diff] [blame]261</p>
262
Marc R. Hoffmann0fd9c832011-03-16 20:42:40 +0000[diff] [blame]263<pre class="source lang-xml linenums">
264&lt;jacoco:agent property="agentvmparam"/&gt;
Marc R. Hoffmannd519add2009-08-11 11:09:29 +0000[diff] [blame]265</pre>
266
267<p>
268 This task has the same attributes as the <code>coverage</code> task plus an
269 additional property to specify the target property name:
270</p>
271
272<table class="coverage">
273 <thead>
274 <tr>
275 <td>Attribute</td>
276 <td>Description</td>
277 <td>Default</td>
278 </tr>
279 </thead>
280 <tbody>
281 <tr>
Brock Janiczakd267c572010-01-28 09:53:54 +0000[diff] [blame]282 <td><code>enabled</code></td>
283 <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]284 disabling coverage instrumentation for any tasks that used the value.</td>
Brock Janiczakd267c572010-01-28 09:53:54 +0000[diff] [blame]285 <td><code>true</code></td>
286 </tr>
287 <tr>
Marc R. Hoffmannd519add2009-08-11 11:09:29 +0000[diff] [blame]288 <td><code>property</code></td>
289 <td>Name of the Ant property to set.</td>
290 <td><i>none (required)</i></td>
291 </tr>
Marc R. Hoffmann2bb6fca2009-08-13 14:04:21 +0000[diff] [blame]292 <tr>
293 <td colspan="3"><i>All attributes of the <code>coverage</code> task.</i></td>
294 </tr>
Marc R. Hoffmannd519add2009-08-11 11:09:29 +0000[diff] [blame]295 </tbody>
296</table>
297
Brock Janiczak74c16592010-01-29 21:34:14 +0000[diff] [blame]298
Marc R. Hoffmann7c775162010-05-27 16:43:34 +0000[diff] [blame]299<h2><a name="dump">Task <code>dump</code></a></h2>
300
301<p>
302 This task allows to remotely collect execution data from another JVM without
303 stopping it. For example:
304</p>
305
Marc R. Hoffmann0fd9c832011-03-16 20:42:40 +0000[diff] [blame]306<pre class="source lang-xml linenums">
307&lt;jacoco:dump address="server.example.com" reset="true" destfile="remote.exec"/&gt;
Marc R. Hoffmann7c775162010-05-27 16:43:34 +0000[diff] [blame]308</pre>
309
310<p>
311 Remote dumps are usefull for long running Java processes like application
312 servers.
313</p>
314
315<p class="hint">
Marc R. Hoffmann6fd10ff2010-06-02 21:42:25 +0000[diff] [blame]316 The target JVM needs to have a <a href="agent.html">JaCoCo agent</a>
317 configured with <code>output</code> mode <code>tcpserver</code>. See
Marc R. Hoffmann7c775162010-05-27 16:43:34 +0000[diff] [blame]318 <a href="#coverage"><code>coverage</code></a> and
319 <a href="#agent"><code>agent</code></a> tasks above.
320</p>
321
322<p>
323 The <code>dump</code> task has the following attributes:
324</p>
325
326<table class="coverage">
327 <thead>
328 <tr>
329 <td>Attribute</td>
330 <td>Description</td>
331 <td>Default</td>
332 </tr>
333 </thead>
334 <tbody>
335 <tr>
336 <td><code>address</code></td>
337 <td>Target IP address or DNS name.</td>
338 <td><code>localhost</code></td>
339 </tr>
340 <tr>
341 <td><code>port</code></td>
342 <td>Target TCP port.</td>
343 <td><code>6300</code></td>
344 </tr>
345 <tr>
346 <td><code>dump</code></td>
347 <td>Flag whether execution data should be dumped.</td>
348 <td><code>true</code></td>
349 </tr>
350 <tr>
351 <td><code>reset</code></td>
352 <td>Flag whether execution data should be reset in the target agent after
353 the dump.</td>
354 <td><code>false</code></td>
355 </tr>
356 <tr>
357 <td><code>destfile</code></td>
358 <td>File location to write the collected execution data to.</td>
359 <td><i>none (required if dump=true)</i></td>
360 </tr>
361 <tr>
362 <td><code>append</code></td>
363 <td>If set to <code>true</code> and the execution data file already
364 exists, coverage data is appended to the existing file. If set to
365 <code>false</code>, an existing execution data file will be replaced.
366 </td>
367 <td><code>true</code></td>
368 </tr>
369 </tbody>
370</table>
371
372
Brock Janiczak74c16592010-01-29 21:34:14 +0000[diff] [blame]373<h2><a name="merge">Task <code>merge</code></a></h2>
374
375<p>
376 This task can be used to merge the execution data from multiple test runs
377 into a single data store.
378</p>
379
Marc R. Hoffmann0fd9c832011-03-16 20:42:40 +0000[diff] [blame]380<pre class="source lang-xml linenums">
381&lt;jacoco:merge destfile="merged.exec"&gt;
382 &lt;fileset dir="executionData" includes="*.exec"/&gt;
383&lt;/jacoco:merge&gt;
Brock Janiczak74c16592010-01-29 21:34:14 +0000[diff] [blame]384</pre>
385
386<p>
387 The task definition can contain any number of resource collection types and
388 has the following mandatory attribute:
389</p>
390
391<table class="coverage">
392 <thead>
393 <tr>
394 <td>Attribute</td>
395 <td>Description</td>
396 <td>Default</td>
397 </tr>
398 </thead>
399 <tbody>
400 <tr>
401 <td><code>destfile</code></td>
Marc R. Hoffmann7c775162010-05-27 16:43:34 +0000[diff] [blame]402 <td>File location to write the merged execution data to.</td>
Brock Janiczak74c16592010-01-29 21:34:14 +0000[diff] [blame]403 <td><i>none (required)</i></td>
404 </tr>
405 </tbody>
406</table>
407
408
Brock Janiczakd267c572010-01-28 09:53:54 +0000[diff] [blame]409<h2><a name="report">Task <code>report</code></a></h2>
Marc R. Hoffmannf7d17522009-08-07 11:21:23 +0000[diff] [blame]410
Marc R. Hoffmann2bb6fca2009-08-13 14:04:21 +0000[diff] [blame]411<p>
412 Finally different reports can be created with the <code>report</code> task.
413 A report task declaration consists of different sections, two specify the
414 input data, additional ones specify the output formats:
415</p>
416
Marc R. Hoffmann0fd9c832011-03-16 20:42:40 +0000[diff] [blame]417<pre class="source lang-xml linenums">
418&lt;jacoco:report&gt;
419
420 &lt;executiondata&gt;
421 &lt;file file="jacoco.exec"/&gt;
422 &lt;/executiondata&gt;
423
424 &lt;structure name="Example Project"&gt;
425 &lt;classfiles&gt;
426 &lt;fileset dir="classes"/&gt;
427 &lt;/classfiles&gt;
428 &lt;sourcefiles encoding="UTF-8"&gt;
429 &lt;fileset dir="src"/&gt;
430 &lt;/sourcefiles&gt;
431 &lt;/structure&gt;
432
433 &lt;html destdir="report"/&gt;
434
435&lt;/jacoco:report&gt;
Marc R. Hoffmann2bb6fca2009-08-13 14:04:21 +0000[diff] [blame]436</pre>
437
438<p>
439 As you can see from the example above the <code>report</code> task is based
440 on several nested elements:
441</p>
442
443<h3>Element <code>executiondata</code></h3>
444
445<p>
446 Within this element Ant resources and resource collections can be specified,
447 that represent JaCoCo execution data files. If more than one execution data
448 file is specified, execution data is combined. A particular piece of code is
Radek Libaad5fbc92009-10-26 13:26:53 +0000[diff] [blame]449 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]450</p>
451
452<h3>Element <code>structure</code></h3>
453
454<p>
Radek Libaad5fbc92009-10-26 13:26:53 +0000[diff] [blame]455 This element defines the report structure. It might contain the following
Marc R. Hoffmann2bb6fca2009-08-13 14:04:21 +0000[diff] [blame]456 nested elements:
457</p>
458
459<ul>
460 <li><code>classfiles</code>: Container element for Ant resources and resource
Marc R. Hoffmannff7cd3a2010-04-06 08:54:29 +0000[diff] [blame]461 collections that can specify Java class files, ZIP archive files (jar, war,
462 ear etc.) or folders containing class files. Archives and folders are
463 searched recursively for class files.</li>
Marc R. Hoffmann2bb6fca2009-08-13 14:04:21 +0000[diff] [blame]464 <li><code>sourcefiles</code>: Optional container element for Ant resources and
Marc R. Hoffmann5625ff62011-03-27 12:53:52 +0000[diff] [blame^]465 resource collections that specify corresponding source files. If source
466 files are specified, some report formats include highlighted source code.</li>
Marc R. Hoffmann2bb6fca2009-08-13 14:04:21 +0000[diff] [blame]467</ul>
468
469<p>
Marc R. Hoffmann5625ff62011-03-27 12:53:52 +0000[diff] [blame^]470 The <code>sourcefiles</code> element has these optional attributes:
471</p>
472
473<table class="coverage">
474 <thead>
475 <tr>
476 <td>Attribute</td>
477 <td>Description</td>
478 <td>Default</td>
479 </tr>
480 </thead>
481 <tbody>
482 <tr>
483 <td><code>encoding</code></td>
484 <td>Character encoding of the source files.</td>
485 <td>Platform default encoding</td>
486 </tr>
487 <tr>
488 <td><code>tabwidth</code></td>
489 <td>Number of whitespace characters that represent a tab character.</td>
490 <td>4 characters</td>
491 </tr>
492 </tbody>
493</table>
494
495<p>
Marc R. Hoffmann1f01f862011-01-12 21:58:34 +0000[diff] [blame]496 Note that the <code>classfiles</code> and <code>sourcefiles</code> elements
497 accept any
498 <a href="http://ant.apache.org/manual/Types/resources.html#collection">Ant
499 resource collection</a>. Therefore also filtering the class file set is
500 possible and allows to narrow the scope of the report, for example:
Marc R. Hoffmann2bb6fca2009-08-13 14:04:21 +0000[diff] [blame]501</p>
502
Marc R. Hoffmann0fd9c832011-03-16 20:42:40 +0000[diff] [blame]503<pre class="source lang-xml linenums">
504&lt;classfiles&gt;
505 &lt;fileset dir="classes"&gt;
506 &lt;include name="org/jacoco/examples/important/**/*.class"/&gt;
507 &lt;/fileset&gt;
508&lt;/classfiles&gt;
Marc R. Hoffmann1f01f862011-01-12 21:58:34 +0000[diff] [blame]509</pre>
510
Marc R. Hoffmann7232b742011-03-07 21:54:08 +0000[diff] [blame]511<p class="hint">
512 <b>Performance Warning:</b> Although it is technically possible and sometimes
513 convenient to use Ant's <code>zipfileset</code> to specify class or source
514 files, this resource type has poor performance characteristics and comes with
515 an huge memory overhead especially for large scale projects.
516</p>
517
Marc R. Hoffmann1f01f862011-01-12 21:58:34 +0000[diff] [blame]518<p>
519 The structure can be refined with a hierarchy of <code>group</code> elements.
520 This way the coverage report can reflect different modules of a software
521 project. For each group element the corresponding class and source files can
522 be specified separately. For example:
523</p>
524
Marc R. Hoffmann0fd9c832011-03-16 20:42:40 +0000[diff] [blame]525<pre class="source lang-xml linenums">
526&lt;structure name="Example Project"&gt;
527 &lt;group name="Server"&gt;
528 &lt;classfiles&gt;
529 &lt;fileset dir="${workspace.dir}/org.jacoco.example.server/classes"/&gt;
530 &lt;/classfiles&gt;
531 &lt;sourcefiles&gt;
532 &lt;fileset dir="${workspace.dir}/org.jacoco.example.server/src"/&gt;
533 &lt;/sourcefiles&gt;
534 &lt;/group&gt;
535 &lt;group name="Client"&gt;
536 &lt;classfiles&gt;
537 &lt;fileset dir="${workspace.dir}/org.jacoco.example.client/classes"/&gt;
538 &lt;/classfiles&gt;
539 &lt;sourcefiles&gt;
540 &lt;fileset dir="${workspace.dir}/org.jacoco.example.client/src"/&gt;
541 &lt;/sourcefiles&gt;
542 &lt;/group&gt;
543
544 ...
545
546&lt;/structure&gt;
Marc R. Hoffmann2bb6fca2009-08-13 14:04:21 +0000[diff] [blame]547</pre>
548
Marc R. Hoffmann722cad82010-03-09 18:22:33 +0000[diff] [blame]549<p>
550 Both <code>structure</code> and <code>group</code> elements have the following
551 mandatory attribute:
552</p>
553
554<table class="coverage">
555 <thead>
556 <tr>
557 <td>Attribute</td>
558 <td>Description</td>
559 <td>Default</td>
560 </tr>
561 </thead>
562 <tbody>
563 <tr>
564 <td><code>name</code></td>
565 <td>Name of the structure or group.</td>
566 <td><i>none (required)</i></td>
567 </tr>
568 </tbody>
569</table>
570
Marc R. Hoffmann2bb6fca2009-08-13 14:04:21 +0000[diff] [blame]571<h3>Element <code>html</code></h3>
572
573<p>
Marc R. Hoffmann81f79202010-03-12 07:36:50 +0000[diff] [blame]574 Create a multi-page report in HTML format. The report can either be written as
575 multiple files into a directory or compressed into a single ZIP file.
Marc R. Hoffmann2bb6fca2009-08-13 14:04:21 +0000[diff] [blame]576</p>
577
578<table class="coverage">
579 <thead>
580 <tr>
581 <td>Attribute</td>
582 <td>Description</td>
583 <td>Default</td>
584 </tr>
585 </thead>
586 <tbody>
587 <tr>
588 <td><code>destdir</code></td>
Marc R. Hoffmann81f79202010-03-12 07:36:50 +0000[diff] [blame]589 <td>Directory to create the report in. Either this property or
590 <code>destfile</code> has to be supplied.</td>
591 <td><i>none (required)</i></td>
592 </tr>
593 <tr>
594 <td><code>destfile</code></td>
595 <td>Zip file to create the report in. Either this property or
596 <code>destdir</code> has to be supplied.</td>
Marc R. Hoffmann2bb6fca2009-08-13 14:04:21 +0000[diff] [blame]597 <td><i>none (required)</i></td>
598 </tr>
Marc R. Hoffmann2ecbea52009-09-03 14:19:11 +0000[diff] [blame]599 <tr>
600 <td><code>footer</code></td>
601 <td>Footer text for each report page.</td>
Marc R. Hoffmannae8c2a82010-10-05 16:20:10 +0000[diff] [blame]602 <td><i>no footer</i></td>
Marc R. Hoffmann2ecbea52009-09-03 14:19:11 +0000[diff] [blame]603 </tr>
Marc R. Hoffmann2becd332009-10-07 16:13:17 +0000[diff] [blame]604 <tr>
605 <td><code>encoding</code></td>
Marc R. Hoffmannae8c2a82010-10-05 16:20:10 +0000[diff] [blame]606 <td>Character encoding of generated HTML pages.</td>
Marc R. Hoffmann2becd332009-10-07 16:13:17 +0000[diff] [blame]607 <td><code>UTF-8</code></td>
608 </tr>
Marc R. Hoffmannae8c2a82010-10-05 16:20:10 +0000[diff] [blame]609 <tr>
610 <td><code>locale</code></td>
611 <td>Locale specified as ISO code (en, fr, jp, ...) used for number formating.</td>
612 <td><i>platform locale</i></td>
613 </tr>
Marc R. Hoffmann2becd332009-10-07 16:13:17 +0000[diff] [blame]614 </tbody>
615</table>
616
617<h3>Element <code>xml</code></h3>
618
619<p>
620 Create a single-file report in XML format.
621</p>
622
623<table class="coverage">
624 <thead>
625 <tr>
626 <td>Attribute</td>
627 <td>Description</td>
628 <td>Default</td>
629 </tr>
630 </thead>
631 <tbody>
632 <tr>
Marc R. Hoffmann88b3f2f2009-10-19 16:10:35 +0000[diff] [blame]633 <td><code>destfile</code></td>
634 <td>Location to write the report file to.</td>
Marc R. Hoffmann2becd332009-10-07 16:13:17 +0000[diff] [blame]635 <td><i>none (required)</i></td>
636 </tr>
637 <tr>
638 <td><code>encoding</code></td>
639 <td>Encoding of the generated XML document.</td>
640 <td><code>UTF-8</code></td>
641 </tr>
Marc R. Hoffmann2bb6fca2009-08-13 14:04:21 +0000[diff] [blame]642 </tbody>
643</table>
644
645<h3>Element <code>csv</code></h3>
646
647<p>
Marc R. Hoffmann2becd332009-10-07 16:13:17 +0000[diff] [blame]648 Create single-file report in CSV format.
Marc R. Hoffmann2bb6fca2009-08-13 14:04:21 +0000[diff] [blame]649</p>
650
651<table class="coverage">
652 <thead>
653 <tr>
654 <td>Attribute</td>
655 <td>Description</td>
656 <td>Default</td>
657 </tr>
658 </thead>
659 <tbody>
660 <tr>
Marc R. Hoffmann88b3f2f2009-10-19 16:10:35 +0000[diff] [blame]661 <td><code>destfile</code></td>
662 <td>Location to write the report file to.</td>
Marc R. Hoffmann2bb6fca2009-08-13 14:04:21 +0000[diff] [blame]663 <td><i>none (required)</i></td>
664 </tr>
Marc R. Hoffmanne17fd112009-10-19 15:27:04 +0000[diff] [blame]665 <tr>
666 <td><code>encoding</code></td>
667 <td>Encoding of the generated CSV document.</td>
668 <td><code>UTF-8</code></td>
669 </tr>
Marc R. Hoffmann2bb6fca2009-08-13 14:04:21 +0000[diff] [blame]670 </tbody>
671</table>
672
Marc R. Hoffmann17be2692010-02-02 05:44:47 +0000[diff] [blame]673</div>
Marc R. Hoffmannf7d17522009-08-07 11:21:23 +0000[diff] [blame]674<div class="footer">
Marc R. Hoffmannb623ffb2010-05-06 19:48:08 +0000[diff] [blame]675 <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]676 <a href="license.html">Copyright</a> &copy; @copyright.years@ Mountainminds GmbH &amp; Co. KG and Contributors
Marc R. Hoffmannf7d17522009-08-07 11:21:23 +0000[diff] [blame]677</div>
678
679</body>
680</html>