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