| Marc R. Hoffmann | 57f9ab4 | 2009-08-24 10:52:42 +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" />
|
| 7 | <title>JaCoCo - Java Agent</title>
|
| 8 | </head>
|
| 9 | <body>
|
| 10 |
|
| 11 | <div class="breadcrumb">
|
| 12 | <a href="../index.html" class="el_session">JaCoCo</a> >
|
| 13 | <a href="index.html" class="el_group">Documentation</a> >
|
| 14 | <span class="el_source">Java Agent</span>
|
| 15 | </div>
|
| 16 |
|
| 17 | <h1>Java Agent</h1>
|
| 18 |
|
| 19 | <p>
|
| 20 | JaCoCo uses class file instrumentation to record execution coverage data.
|
| Radek Liba | ad5fbc9 | 2009-10-26 13:26:53 +0000 | [diff] [blame^] | 21 | Class files are instrumented on-the-fly using a so called Java agent. This
|
| Marc R. Hoffmann | 57f9ab4 | 2009-08-24 10:52:42 +0000 | [diff] [blame] | 22 | mechanism allows in-memory pre-processing of all class files during class
|
| Marc R. Hoffmann | 58d7621 | 2009-10-08 15:40:46 +0000 | [diff] [blame] | 23 | loading independent of the application framework. The JaCoCo agent collects
|
| 24 | execution information and dumps it to a local file when the JVM exits.
|
| Marc R. Hoffmann | 57f9ab4 | 2009-08-24 10:52:42 +0000 | [diff] [blame] | 25 | </p>
|
| 26 |
|
| 27 | <p class="hint">
|
| 28 | If you use the <a href="ant.html">JaCoCo Ant tasks</a> you don't have to care
|
| Radek Liba | ad5fbc9 | 2009-10-26 13:26:53 +0000 | [diff] [blame^] | 29 | about the agent and its options directly. This is transparently handled by the
|
| 30 | Ant tasks.
|
| Marc R. Hoffmann | 57f9ab4 | 2009-08-24 10:52:42 +0000 | [diff] [blame] | 31 | </p>
|
| 32 |
|
| 33 | <p>
|
| 34 | The agent <code>jacocoagent.jar</code> is part of the JaCoCo distribution and
|
| 35 | includes all required dependencies. A Java agent can be activated with the
|
| 36 | following JVM option:
|
| 37 | </p>
|
| 38 |
|
| 39 | <pre>
|
| 40 | -javaagent:<i>[yourpath/]</i>jacocoagent.jar=<i>[option1]</i>=<i>[value1]</i>,<i>[option2]</i>=<i>[value2]</i>
|
| 41 | </pre>
|
| 42 |
|
| 43 | <p>
|
| 44 | The JaCoCo agent accepts the following options:
|
| 45 | </p>
|
| 46 |
|
| 47 | <table class="coverage">
|
| 48 | <thead>
|
| 49 | <tr>
|
| 50 | <td>Option</td>
|
| 51 | <td>Description</td>
|
| 52 | <td>Default</td>
|
| 53 | </tr>
|
| 54 | </thead>
|
| 55 | <tbody>
|
| 56 | <tr>
|
| 57 | <td><code>file</code></td>
|
| 58 | <td>Path to the output file for execution data.</td>
|
| 59 | <td><code>jacoco.exec</code></td>
|
| 60 | </tr>
|
| 61 | <tr>
|
| 62 | <td><code>merge</code></td>
|
| 63 | <td>If set to <code>true</code> and the execution data file already
|
| 64 | exists, coverage data is merged to the existing file. If set to
|
| 65 | <code>false</code>, an existing execution data file will be replaced.
|
| 66 | </td>
|
| 67 | <td><code>true</code></td>
|
| 68 | </tr>
|
| 69 | <tr>
|
| Marc R. Hoffmann | cf5345f | 2009-09-10 15:01:24 +0000 | [diff] [blame] | 70 | <td><code>includes</code></td>
|
| Radek Liba | ad5fbc9 | 2009-10-26 13:26:53 +0000 | [diff] [blame^] | 71 | <td>A list of class names that should be included in execution analysis.
|
| Marc R. Hoffmann | cf5345f | 2009-09-10 15:01:24 +0000 | [diff] [blame] | 72 | The list entries are separated by a vertical bar (<code>|</code>) and
|
| 73 | may use wildcard characters (<code>*</code> and <code>?</code>).
|
| 74 | Except for performance optimization or technical corner cases this
|
| 75 | option is normally not required.
|
| 76 | </td>
|
| 77 | <td><code>*</code> (all classes)</td>
|
| 78 | </tr>
|
| 79 | <tr>
|
| 80 | <td><code>excludes</code></td>
|
| 81 | <td>A list of class names that should be excluded from execution analysis.
|
| 82 | The list entries are separated by a vertical bar (<code>|</code>) and
|
| 83 | may use wildcard characters (<code>*</code> and <code>?</code>).
|
| 84 | Except for performance optimization or technical corner cases this
|
| 85 | option is normally not required.
|
| 86 | </td>
|
| 87 | <td><i>empty</i> (no excluded classes)</td>
|
| 88 | </tr>
|
| 89 | <tr>
|
| Marc R. Hoffmann | 57f9ab4 | 2009-08-24 10:52:42 +0000 | [diff] [blame] | 90 | <td><code>exclclassloader</code></td>
|
| Marc R. Hoffmann | cf5345f | 2009-09-10 15:01:24 +0000 | [diff] [blame] | 91 | <td>A list of class loader names that should be excluded from execution
|
| Marc R. Hoffmann | 57f9ab4 | 2009-08-24 10:52:42 +0000 | [diff] [blame] | 92 | analysis. The list entries are separated by a vertical bar
|
| 93 | (<code>|</code>) and may use wildcard characters (<code>*</code> and
|
| 94 | <code>?</code>). This option might be required in case of special
|
| 95 | frameworks that conflict with JaCoCo code instrumentation, in
|
| 96 | particular class loaders that do not have access to the Java runtime
|
| 97 | classes.
|
| 98 | </td>
|
| 99 | <td><code>sun.reflect.DelegatingClassLoader</code></td>
|
| 100 | </tr>
|
| 101 | </tbody>
|
| 102 | </table>
|
| 103 |
|
| 104 |
|
| 105 | <div class="footer">
|
| 106 | <div class="versioninfo"><a href="@HOMEURL@">JaCoCo</a> @VERSION@</div>
|
| 107 | <a href="license.html">Copyright</a> © 2009 Mountainminds GmbH & Co. KG and Contributors
|
| 108 | </div>
|
| 109 |
|
| 110 | </body>
|
| 111 | </html> |