Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / jacoco / d7d2f75c3b74ac589b61c8d3f3a23603fd33828d / . / org.jacoco.doc / docroot / doc / agent.html
blob: 4318cf5adf7ea4641ed99b1019bb2c2831be9083 [file] [log] [blame]
Marc R. Hoffmann57f9ab42009-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" />
Marc R. Hoffmannd7d2f752010-05-06 21:12:31 +0000[diff] [blame^]7 <link rel="shortcut icon" href=".resources/report.gif" type="image/gif" />
Marc R. Hoffmann57f9ab42009-08-24 10:52:42 +0000[diff] [blame]8 <title>JaCoCo - Java Agent</title>
9</head>
10<body>
11
12<div class="breadcrumb">
Marc R. Hoffmannd7d2f752010-05-06 21:12:31 +0000[diff] [blame^]13 <a href="../index.html" class="el_report">JaCoCo</a> &gt;
Marc R. Hoffmann57f9ab42009-08-24 10:52:42 +0000[diff] [blame]14 <a href="index.html" class="el_group">Documentation</a> &gt;
15 <span class="el_source">Java Agent</span>
16</div>
Marc R. Hoffmann17be2692010-02-02 05:44:47 +0000[diff] [blame]17<div id="content">
Marc R. Hoffmann57f9ab42009-08-24 10:52:42 +0000[diff] [blame]18
19<h1>Java Agent</h1>
20
21<p>
22 JaCoCo uses class file instrumentation to record execution coverage data.
Radek Libaad5fbc92009-10-26 13:26:53 +0000[diff] [blame]23 Class files are instrumented on-the-fly using a so called Java agent. This
Marc R. Hoffmann57f9ab42009-08-24 10:52:42 +0000[diff] [blame]24 mechanism allows in-memory pre-processing of all class files during class
Marc R. Hoffmann58d76212009-10-08 15:40:46 +0000[diff] [blame]25 loading independent of the application framework. The JaCoCo agent collects
26 execution information and dumps it to a local file when the JVM exits.
Marc R. Hoffmann57f9ab42009-08-24 10:52:42 +0000[diff] [blame]27</p>
28
29<p class="hint">
30 If you use the <a href="ant.html">JaCoCo Ant tasks</a> you don't have to care
Radek Libaad5fbc92009-10-26 13:26:53 +0000[diff] [blame]31 about the agent and its options directly. This is transparently handled by the
32 Ant tasks.
Marc R. Hoffmann57f9ab42009-08-24 10:52:42 +0000[diff] [blame]33</p>
34
35<p>
36 The agent <code>jacocoagent.jar</code> is part of the JaCoCo distribution and
37 includes all required dependencies. A Java agent can be activated with the
38 following JVM option:
39</p>
40
41<pre>
42 -javaagent:<i>[yourpath/]</i>jacocoagent.jar=<i>[option1]</i>=<i>[value1]</i>,<i>[option2]</i>=<i>[value2]</i>
43</pre>
44
45<p>
46 The JaCoCo agent accepts the following options:
47</p>
48
49<table class="coverage">
50 <thead>
51 <tr>
52 <td>Option</td>
53 <td>Description</td>
54 <td>Default</td>
55 </tr>
56 </thead>
57 <tbody>
58 <tr>
Brock Janiczak003d47c2010-01-15 00:45:17 +0000[diff] [blame]59 <td><code>destfile</code></td>
Marc R. Hoffmann57f9ab42009-08-24 10:52:42 +0000[diff] [blame]60 <td>Path to the output file for execution data.</td>
61 <td><code>jacoco.exec</code></td>
62 </tr>
63 <tr>
Brock Janiczak003d47c2010-01-15 00:45:17 +0000[diff] [blame]64 <td><code>append</code></td>
Marc R. Hoffmann57f9ab42009-08-24 10:52:42 +0000[diff] [blame]65 <td>If set to <code>true</code> and the execution data file already
Brock Janiczak003d47c2010-01-15 00:45:17 +0000[diff] [blame]66 exists, coverage data is appended to the existing file. If set to
Marc R. Hoffmann57f9ab42009-08-24 10:52:42 +0000[diff] [blame]67 <code>false</code>, an existing execution data file will be replaced.
68 </td>
69 <td><code>true</code></td>
70 </tr>
71 <tr>
Marc R. Hoffmanncf5345f2009-09-10 15:01:24 +0000[diff] [blame]72 <td><code>includes</code></td>
Radek Libaad5fbc92009-10-26 13:26:53 +0000[diff] [blame]73 <td>A list of class names that should be included in execution analysis.
Marc R. Hoffmanncf5345f2009-09-10 15:01:24 +0000[diff] [blame]74 The list entries are separated by a vertical bar (<code>|</code>) and
75 may use wildcard characters (<code>*</code> and <code>?</code>).
76 Except for performance optimization or technical corner cases this
77 option is normally not required.
78 </td>
79 <td><code>*</code> (all classes)</td>
80 </tr>
81 <tr>
82 <td><code>excludes</code></td>
83 <td>A list of class names that should be excluded from execution analysis.
84 The list entries are separated by a vertical bar (<code>|</code>) and
85 may use wildcard characters (<code>*</code> and <code>?</code>).
86 Except for performance optimization or technical corner cases this
87 option is normally not required.
88 </td>
89 <td><i>empty</i> (no excluded classes)</td>
90 </tr>
91 <tr>
Marc R. Hoffmann57f9ab42009-08-24 10:52:42 +0000[diff] [blame]92 <td><code>exclclassloader</code></td>
Marc R. Hoffmanncf5345f2009-09-10 15:01:24 +0000[diff] [blame]93 <td>A list of class loader names that should be excluded from execution
Marc R. Hoffmann57f9ab42009-08-24 10:52:42 +0000[diff] [blame]94 analysis. The list entries are separated by a vertical bar
95 (<code>|</code>) and may use wildcard characters (<code>*</code> and
96 <code>?</code>). This option might be required in case of special
97 frameworks that conflict with JaCoCo code instrumentation, in
98 particular class loaders that do not have access to the Java runtime
99 classes.
100 </td>
101 <td><code>sun.reflect.DelegatingClassLoader</code></td>
102 </tr>
Brock Janiczakf2d6f882010-05-04 06:47:40 +0000[diff] [blame]103 <tr>
Marc R. Hoffmannadfa1182010-05-05 12:59:42 +0000[diff] [blame]104 <td><code>sessionid</code></td>
105 <td>A session identifier that is written with the execution data. Without
106 this parameter a random identifier is created by the agent.
107 </td>
108 <td><i>auto-generated</i></td>
109 </tr>
110 <tr>
Brock Janiczakf2d6f882010-05-04 06:47:40 +0000[diff] [blame]111 <td><code>dumponexit</code></td>
Marc R. Hoffmannadfa1182010-05-05 12:59:42 +0000[diff] [blame]112 <td>If set to <code>true</code> coverage data will be written on VM
113 shutdown.
114 </td>
Brock Janiczakf2d6f882010-05-04 06:47:40 +0000[diff] [blame]115 <td><code>true</code></td>
116 </tr>
Marc R. Hoffmann57f9ab42009-08-24 10:52:42 +0000[diff] [blame]117 </tbody>
118</table>
119
Marc R. Hoffmann17be2692010-02-02 05:44:47 +0000[diff] [blame]120</div>
Marc R. Hoffmann57f9ab42009-08-24 10:52:42 +0000[diff] [blame]121<div class="footer">
Marc R. Hoffmannb623ffb2010-05-06 19:48:08 +0000[diff] [blame]122 <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]123 <a href="license.html">Copyright</a> &copy; @copyright.years@ Mountainminds GmbH &amp; Co. KG and Contributors
Marc R. Hoffmann57f9ab42009-08-24 10:52:42 +0000[diff] [blame]124</div>
125
126</body>
127</html>