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