Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / jacoco / 5385417528623ecc9a5215f428dc8d4ab0328985 / . / org.jacoco.doc / docroot / doc / ant.html
blob: df3f320f99d5829865768ded8c732db3b0e727ea [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
227 <code>tcpclient</code>.
228 </td>
229 <td><code>localhost</code></td>
230 </tr>
231 <tr>
232 <td><code>port</code></td>
233 <td>Port to bind to when the output method is <code>tcpserver</code> or
234 connect to when the output method is <code>tcpclient</code>. In
235 <code>tcpserver</code> mode the port must be available, which means
236 that if multiple JaCoCo agents should run on the same machine,
237 different ports have to be specified.
238 </td>
239 <td><code>6300</code></td>
240 </tr>
Marc R. Hoffmannf7d17522009-08-07 11:21:23 +0000[diff] [blame]241 </tbody>
242</table>
243
244
Brock Janiczakd267c572010-01-28 09:53:54 +0000[diff] [blame]245<h2><a name="agent">Task <code>agent</code></a></h2>
Marc R. Hoffmannf7d17522009-08-07 11:21:23 +0000[diff] [blame]246
Marc R. Hoffmannd519add2009-08-11 11:09:29 +0000[diff] [blame]247<p>
248 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]249 might alternatively use the <code>agent</code> task to create the
250 <a href="agent.html">Java agent</a> parameter. The following example defines a
251 Ant property with the name <code>agentvmparam</code> that can be directly used
252 as a Java VM parameter:
Marc R. Hoffmannd519add2009-08-11 11:09:29 +0000[diff] [blame]253</p>
254
Marc R. Hoffmanna760f322010-03-10 22:23:52 +0000[diff] [blame]255<pre class="source lang-xml">
Marc R. Hoffmannd519add2009-08-11 11:09:29 +0000[diff] [blame]256<span class="nr"> 1</span>&lt;jacoco:agent property="agentvmparam"/>
257</pre>
258
259<p>
260 This task has the same attributes as the <code>coverage</code> task plus an
261 additional property to specify the target property name:
262</p>
263
264<table class="coverage">
265 <thead>
266 <tr>
267 <td>Attribute</td>
268 <td>Description</td>
269 <td>Default</td>
270 </tr>
271 </thead>
272 <tbody>
273 <tr>
Brock Janiczakd267c572010-01-28 09:53:54 +0000[diff] [blame]274 <td><code>enabled</code></td>
275 <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]276 disabling coverage instrumentation for any tasks that used the value.</td>
Brock Janiczakd267c572010-01-28 09:53:54 +0000[diff] [blame]277 <td><code>true</code></td>
278 </tr>
279 <tr>
Marc R. Hoffmannd519add2009-08-11 11:09:29 +0000[diff] [blame]280 <td><code>property</code></td>
281 <td>Name of the Ant property to set.</td>
282 <td><i>none (required)</i></td>
283 </tr>
Marc R. Hoffmann2bb6fca2009-08-13 14:04:21 +0000[diff] [blame]284 <tr>
285 <td colspan="3"><i>All attributes of the <code>coverage</code> task.</i></td>
286 </tr>
Marc R. Hoffmannd519add2009-08-11 11:09:29 +0000[diff] [blame]287 </tbody>
288</table>
289
Brock Janiczak74c16592010-01-29 21:34:14 +0000[diff] [blame]290
Marc R. Hoffmann7c775162010-05-27 16:43:34 +0000[diff] [blame]291<h2><a name="dump">Task <code>dump</code></a></h2>
292
293<p>
294 This task allows to remotely collect execution data from another JVM without
295 stopping it. For example:
296</p>
297
298<pre class="source lang-xml">
299<span class="nr"> 1</span>&lt;jacoco:dump address="server.example.com" reset="true" destfile="remote.exec"/&gt;
300</pre>
301
302<p>
303 Remote dumps are usefull for long running Java processes like application
304 servers.
305</p>
306
307<p class="hint">
Marc R. Hoffmann6fd10ff2010-06-02 21:42:25 +0000[diff] [blame]308 The target JVM needs to have a <a href="agent.html">JaCoCo agent</a>
309 configured with <code>output</code> mode <code>tcpserver</code>. See
Marc R. Hoffmann7c775162010-05-27 16:43:34 +0000[diff] [blame]310 <a href="#coverage"><code>coverage</code></a> and
311 <a href="#agent"><code>agent</code></a> tasks above.
312</p>
313
314<p>
315 The <code>dump</code> task has the following attributes:
316</p>
317
318<table class="coverage">
319 <thead>
320 <tr>
321 <td>Attribute</td>
322 <td>Description</td>
323 <td>Default</td>
324 </tr>
325 </thead>
326 <tbody>
327 <tr>
328 <td><code>address</code></td>
329 <td>Target IP address or DNS name.</td>
330 <td><code>localhost</code></td>
331 </tr>
332 <tr>
333 <td><code>port</code></td>
334 <td>Target TCP port.</td>
335 <td><code>6300</code></td>
336 </tr>
337 <tr>
338 <td><code>dump</code></td>
339 <td>Flag whether execution data should be dumped.</td>
340 <td><code>true</code></td>
341 </tr>
342 <tr>
343 <td><code>reset</code></td>
344 <td>Flag whether execution data should be reset in the target agent after
345 the dump.</td>
346 <td><code>false</code></td>
347 </tr>
348 <tr>
349 <td><code>destfile</code></td>
350 <td>File location to write the collected execution data to.</td>
351 <td><i>none (required if dump=true)</i></td>
352 </tr>
353 <tr>
354 <td><code>append</code></td>
355 <td>If set to <code>true</code> and the execution data file already
356 exists, coverage data is appended to the existing file. If set to
357 <code>false</code>, an existing execution data file will be replaced.
358 </td>
359 <td><code>true</code></td>
360 </tr>
361 </tbody>
362</table>
363
364
Brock Janiczak74c16592010-01-29 21:34:14 +0000[diff] [blame]365<h2><a name="merge">Task <code>merge</code></a></h2>
366
367<p>
368 This task can be used to merge the execution data from multiple test runs
369 into a single data store.
370</p>
371
Marc R. Hoffmanna760f322010-03-10 22:23:52 +0000[diff] [blame]372<pre class="source lang-xml">
Marc R. Hoffmann5c8a7032010-02-25 11:15:54 +0000[diff] [blame]373<span class="nr"> 1</span>&lt;jacoco:merge destfile="merged.exec"&gt;
374<span class="nr"> 2</span> &lt;fileset dir="executionData" includes="*.exec"/&gt;
375<span class="nr"> 3</span>&lt;/jacoco:merge&gt;
Brock Janiczak74c16592010-01-29 21:34:14 +0000[diff] [blame]376</pre>
377
378<p>
379 The task definition can contain any number of resource collection types and
380 has the following mandatory attribute:
381</p>
382
383<table class="coverage">
384 <thead>
385 <tr>
386 <td>Attribute</td>
387 <td>Description</td>
388 <td>Default</td>
389 </tr>
390 </thead>
391 <tbody>
392 <tr>
393 <td><code>destfile</code></td>
Marc R. Hoffmann7c775162010-05-27 16:43:34 +0000[diff] [blame]394 <td>File location to write the merged execution data to.</td>
Brock Janiczak74c16592010-01-29 21:34:14 +0000[diff] [blame]395 <td><i>none (required)</i></td>
396 </tr>
397 </tbody>
398</table>
399
400
Brock Janiczakd267c572010-01-28 09:53:54 +0000[diff] [blame]401<h2><a name="report">Task <code>report</code></a></h2>
Marc R. Hoffmannf7d17522009-08-07 11:21:23 +0000[diff] [blame]402
Marc R. Hoffmann2bb6fca2009-08-13 14:04:21 +0000[diff] [blame]403<p>
404 Finally different reports can be created with the <code>report</code> task.
405 A report task declaration consists of different sections, two specify the
406 input data, additional ones specify the output formats:
407</p>
408
Marc R. Hoffmanna760f322010-03-10 22:23:52 +0000[diff] [blame]409<pre class="source lang-xml">
Marc R. Hoffmann2bb6fca2009-08-13 14:04:21 +0000[diff] [blame]410<span class="nr"> 1</span>&lt;jacoco:report&gt;
411<span class="nr"> 2</span>
412<span class="nr"> 3</span> &lt;executiondata&gt;
413<span class="nr"> 4</span> &lt;file file="jacoco.exec"/&gt;
414<span class="nr"> 5</span> &lt;/executiondata&gt;
415<span class="nr"> 6</span>
416<span class="nr"> 7</span> &lt;structure name="Example Project"&gt;
417<span class="nr"> 8</span> &lt;classfiles&gt;
418<span class="nr"> 9</span> &lt;fileset dir="bin"/&gt;
419<span class="nr"> 10</span> &lt;/classfiles&gt;
420<span class="nr"> 11</span> &lt;sourcefiles encoding="UTF-8"&gt;
421<span class="nr"> 12</span> &lt;fileset dir="src"/&gt;
422<span class="nr"> 13</span> &lt;/sourcefiles&gt;
423<span class="nr"> 14</span> &lt;/structure&gt;
424<span class="nr"> 15</span>
425<span class="nr"> 16</span> &lt;html destdir="report"/&gt;
426<span class="nr"> 17</span>
427<span class="nr"> 18</span>&lt;/jacoco:report&gt;
428</pre>
429
430<p>
431 As you can see from the example above the <code>report</code> task is based
432 on several nested elements:
433</p>
434
435<h3>Element <code>executiondata</code></h3>
436
437<p>
438 Within this element Ant resources and resource collections can be specified,
439 that represent JaCoCo execution data files. If more than one execution data
440 file is specified, execution data is combined. A particular piece of code is
Radek Libaad5fbc92009-10-26 13:26:53 +0000[diff] [blame]441 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]442</p>
443
444<h3>Element <code>structure</code></h3>
445
446<p>
Radek Libaad5fbc92009-10-26 13:26:53 +0000[diff] [blame]447 This element defines the report structure. It might contain the following
Marc R. Hoffmann2bb6fca2009-08-13 14:04:21 +0000[diff] [blame]448 nested elements:
449</p>
450
451<ul>
452 <li><code>classfiles</code>: Container element for Ant resources and resource
Marc R. Hoffmannff7cd3a2010-04-06 08:54:29 +0000[diff] [blame]453 collections that can specify Java class files, ZIP archive files (jar, war,
454 ear etc.) or folders containing class files. Archives and folders are
455 searched recursively for class files.</li>
Marc R. Hoffmann2bb6fca2009-08-13 14:04:21 +0000[diff] [blame]456 <li><code>sourcefiles</code>: Optional container element for Ant resources and
457 resource collections that specify corresponding source files. The element
458 has an optional attribute <code>encoding</code> to specify the character
459 encoding of the source files. If no encoding is given, the platform default
460 is used. If source files are specified, some report formats include
Radek Libaad5fbc92009-10-26 13:26:53 +0000[diff] [blame]461 highlighted source code.</li>
Marc R. Hoffmann2bb6fca2009-08-13 14:04:21 +0000[diff] [blame]462</ul>
463
464<p>
465 The structure can be refined with a hierarchy of <code>group</code> elements.
Radek Libaad5fbc92009-10-26 13:26:53 +0000[diff] [blame]466 This way the coverage report can reflect different modules of a software
Marc R. Hoffmann2bb6fca2009-08-13 14:04:21 +0000[diff] [blame]467 project. For each group element the corresponding class and source files can
Radek Libaad5fbc92009-10-26 13:26:53 +0000[diff] [blame]468 be specified separately. For example, the build script of JaCoCo itself
Marc R. Hoffmann2bb6fca2009-08-13 14:04:21 +0000[diff] [blame]469 contains the following declaration to separate the different bundles in the
470 report (see the <a href="../coverage/index.html">resulting report</a>):
471</p>
472
Marc R. Hoffmanna760f322010-03-10 22:23:52 +0000[diff] [blame]473<pre class="source lang-xml">
Marc R. Hoffmann2bb6fca2009-08-13 14:04:21 +0000[diff] [blame]474<span class="nr"> 1</span>&lt;structure name="JaCoCo"&gt;
475<span class="nr"> 2</span> &lt;group name="org.jacoco.core"&gt;
476<span class="nr"> 3</span> &lt;classfiles&gt;
477<span class="nr"> 4</span> &lt;path refid="bundle-org.jacoco.core"/&gt;
478<span class="nr"> 5</span> &lt;/classfiles&gt;
479<span class="nr"> 6</span> &lt;sourcefiles&gt;
480<span class="nr"> 7</span> &lt;fileset dir="${workspace.dir}/org.jacoco.core/src"/&gt;
481<span class="nr"> 8</span> &lt;/sourcefiles&gt;
482<span class="nr"> 9</span> &lt;/group&gt;
483<span class="nr"> 10</span> &lt;group name="org.jacoco.report"&gt;
484<span class="nr"> 11</span> &lt;classfiles&gt;
485<span class="nr"> 12</span> &lt;path refid="bundle-org.jacoco.report"/&gt;
486<span class="nr"> 13</span> &lt;/classfiles&gt;
487<span class="nr"> 14</span> &lt;sourcefiles&gt;
488<span class="nr"> 15</span> &lt;fileset dir="${workspace.dir}/org.jacoco.report/src"/&gt;
489<span class="nr"> 16</span> &lt;/sourcefiles&gt;
490<span class="nr"> 17</span> &lt;/group&gt;
491<span class="nr"> 18</span>
492<span class="nr"> 19</span> ...
493<span class="nr"> 20</span>
494<span class="nr"> 21</span>&lt;/structure&gt;
495</pre>
496
Marc R. Hoffmann722cad82010-03-09 18:22:33 +0000[diff] [blame]497<p>
498 Both <code>structure</code> and <code>group</code> elements have the following
499 mandatory attribute:
500</p>
501
502<table class="coverage">
503 <thead>
504 <tr>
505 <td>Attribute</td>
506 <td>Description</td>
507 <td>Default</td>
508 </tr>
509 </thead>
510 <tbody>
511 <tr>
512 <td><code>name</code></td>
513 <td>Name of the structure or group.</td>
514 <td><i>none (required)</i></td>
515 </tr>
516 </tbody>
517</table>
518
Marc R. Hoffmann2bb6fca2009-08-13 14:04:21 +0000[diff] [blame]519<h3>Element <code>html</code></h3>
520
521<p>
Marc R. Hoffmann81f79202010-03-12 07:36:50 +0000[diff] [blame]522 Create a multi-page report in HTML format. The report can either be written as
523 multiple files into a directory or compressed into a single ZIP file.
Marc R. Hoffmann2bb6fca2009-08-13 14:04:21 +0000[diff] [blame]524</p>
525
526<table class="coverage">
527 <thead>
528 <tr>
529 <td>Attribute</td>
530 <td>Description</td>
531 <td>Default</td>
532 </tr>
533 </thead>
534 <tbody>
535 <tr>
536 <td><code>destdir</code></td>
Marc R. Hoffmann81f79202010-03-12 07:36:50 +0000[diff] [blame]537 <td>Directory to create the report in. Either this property or
538 <code>destfile</code> has to be supplied.</td>
539 <td><i>none (required)</i></td>
540 </tr>
541 <tr>
542 <td><code>destfile</code></td>
543 <td>Zip file to create the report in. Either this property or
544 <code>destdir</code> has to be supplied.</td>
Marc R. Hoffmann2bb6fca2009-08-13 14:04:21 +0000[diff] [blame]545 <td><i>none (required)</i></td>
546 </tr>
Marc R. Hoffmann2ecbea52009-09-03 14:19:11 +0000[diff] [blame]547 <tr>
548 <td><code>footer</code></td>
549 <td>Footer text for each report page.</td>
550 <td><i>No footer</i></td>
551 </tr>
Marc R. Hoffmann2becd332009-10-07 16:13:17 +0000[diff] [blame]552 <tr>
553 <td><code>encoding</code></td>
554 <td>Encoding of the generated HTML pages.</td>
555 <td><code>UTF-8</code></td>
556 </tr>
557 </tbody>
558</table>
559
560<h3>Element <code>xml</code></h3>
561
562<p>
563 Create a single-file report in XML format.
564</p>
565
566<table class="coverage">
567 <thead>
568 <tr>
569 <td>Attribute</td>
570 <td>Description</td>
571 <td>Default</td>
572 </tr>
573 </thead>
574 <tbody>
575 <tr>
Marc R. Hoffmann88b3f2f2009-10-19 16:10:35 +0000[diff] [blame]576 <td><code>destfile</code></td>
577 <td>Location to write the report file to.</td>
Marc R. Hoffmann2becd332009-10-07 16:13:17 +0000[diff] [blame]578 <td><i>none (required)</i></td>
579 </tr>
580 <tr>
581 <td><code>encoding</code></td>
582 <td>Encoding of the generated XML document.</td>
583 <td><code>UTF-8</code></td>
584 </tr>
Marc R. Hoffmann2bb6fca2009-08-13 14:04:21 +0000[diff] [blame]585 </tbody>
586</table>
587
588<h3>Element <code>csv</code></h3>
589
590<p>
Marc R. Hoffmann2becd332009-10-07 16:13:17 +0000[diff] [blame]591 Create single-file report in CSV format.
Marc R. Hoffmann2bb6fca2009-08-13 14:04:21 +0000[diff] [blame]592</p>
593
594<table class="coverage">
595 <thead>
596 <tr>
597 <td>Attribute</td>
598 <td>Description</td>
599 <td>Default</td>
600 </tr>
601 </thead>
602 <tbody>
603 <tr>
Marc R. Hoffmann88b3f2f2009-10-19 16:10:35 +0000[diff] [blame]604 <td><code>destfile</code></td>
605 <td>Location to write the report file to.</td>
Marc R. Hoffmann2bb6fca2009-08-13 14:04:21 +0000[diff] [blame]606 <td><i>none (required)</i></td>
607 </tr>
Marc R. Hoffmanne17fd112009-10-19 15:27:04 +0000[diff] [blame]608 <tr>
609 <td><code>encoding</code></td>
610 <td>Encoding of the generated CSV document.</td>
611 <td><code>UTF-8</code></td>
612 </tr>
Marc R. Hoffmann2bb6fca2009-08-13 14:04:21 +0000[diff] [blame]613 </tbody>
614</table>
615
Marc R. Hoffmann17be2692010-02-02 05:44:47 +0000[diff] [blame]616</div>
Marc R. Hoffmannf7d17522009-08-07 11:21:23 +0000[diff] [blame]617<div class="footer">
Marc R. Hoffmannb623ffb2010-05-06 19:48:08 +0000[diff] [blame]618 <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]619 <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]620</div>
621
622</body>
623</html>