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