Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / jacoco / 1a56c9619e03ee3e4e1b539e592e7d8b51f53a7b / . / org.jacoco.doc / docroot / doc / offline.html
blob: 162113758281669871c049ab3ccc39f3d6e288d6 [file] [log] [blame]
Marc R. Hoffmann235a09e2012-12-23 15:57:16 +0100[diff] [blame]1<?xml version="1.0" encoding="UTF-8" ?>
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=UTF-8" />
Evgeny Mandrikov8b212982016-06-12 17:55:49 +0200[diff] [blame]6 <link rel="stylesheet" href="resources/doc.css" charset="UTF-8" type="text/css" />
7 <link rel="shortcut icon" href="resources/report.gif" type="image/gif" />
Marc R. Hoffmann235a09e2012-12-23 15:57:16 +0100[diff] [blame]8 <title>JaCoCo - Offline Instrumentation</title>
9</head>
10<body>
11
12<div class="breadcrumb">
13 <a href="../index.html" class="el_report">JaCoCo</a> &gt;
14 <a href="index.html" class="el_group">Documentation</a> &gt;
15 <span class="el_source">Offline Instrumentation</span>
16</div>
17<div id="content">
18
19<h1>Offline Instrumentation</h1>
20
21<p>
22 One of the main benefits of JaCoCo is the Java agent, which instruments
23 classes on-the-fly. This simplifies code coverage analysis a lot as no
24 pre-instrumentation and classpath tweaking is required. However, there can be
25 situations where on-the-fly instrumentation is not suitable, for example:
26</p>
27<ul>
28 <li>Runtime environments that do not support Java agents.</li>
29 <li>Deployments where it is not possible to configure JVM options.</li>
30 <li>Bytecode needs to be converted for another VM like the Android Dalvik VM.</li>
31 <li>Conflicts with other agents that do dynamic classfile transformation.</li>
32</ul>
33
34<p>
35 For such scenarios class files can be pre-instrumented with JaCoCo, for
36 example with the <a href="ant.html#instrument"><code>instrument</code></a>
37 Ant task. At runtime the pre-instrumented classes needs be on the classpath
38 instead of the original classes. In addition <code>jacocoagent.jar</code> must
39 be put on the classpath.
40</p>
41
42<h2>Configuration</h2>
43<p>
Marc R. Hoffmann47990a42012-12-28 13:54:23 +0100[diff] [blame]44 In offline mode the JaCoCo runtime can be configured with the same set of
45 properties which are available for the <a href="agent.html">agent</a>, except
46 for the <code>includes</code>/<code>excludes</code> options as the class files
47 are already instrumented. There are two different ways to provide the
48 configuration:
Marc R. Hoffmann235a09e2012-12-23 15:57:16 +0100[diff] [blame]49</p>
50
Marc R. Hoffmann47990a42012-12-28 13:54:23 +0100[diff] [blame]51<ul>
52 <li><b>Configuration File:</b> If a file <code>jacoco-agent.properties</code>
53 is supplied on the classpath options are loaded from this file. The file
54 has to be formatted in the
55 <a href="http://docs.oracle.com/javase/7/docs/api/java/util/Properties.html#load%28java.io.Reader%29">Java
56 properties file format</a>.</li>
57 <li><b>System Properties:</b> Options can also be supplied as Java system
58 properties. In this case the options have to be prefixed with
59 "<code>jacoco-agent.</code>". For example the location of the
60 <code>*.exec</code> file can be configured with the system property
61 "<code>jacoco-agent.destfile</code>".</li>
62</ul>
63
Marc R. Hoffmann00920552014-12-26 17:47:32 +0100[diff] [blame]64<p>
65 In both cases configuration values may contain variables in the format
66 <code>${<i>name</i>}</code> which are resolved with system property values
67 at runtime. For example:
68</p>
69
70<pre class="source">
71destfile=${user.home}/jacoco.exec
72</pre>
73
Marc R. Hoffmann235a09e2012-12-23 15:57:16 +0100[diff] [blame]74<h2>Class Loading and Initialization</h2>
75<p>
76 Unlike with on-the-fly instrumentation offline instrumented classes get a
77 direct dependency on the JaCoCo runtime. Therefore
78 <code>jacocoagent.jar</code> has to be on the classpath and accessible by the
79 instrumented classes. The proper location for <code>jacocoagent.jar</code>
80 might depend on your deployment scenario. The first instrumented class loaded
81 will trigger the initialization of the JaCoCo runtime. If no instrumented
82 class is loaded the JaCoCo runtime will not get started at all.
83</p>
84
85<h2>Using Pre-Instrumented Classes With the Java Agent</h2>
86<p>
87 It is possible to also use offline-instrumented classes with the JaCoCo Java
88 agent. In this case the configuration is taken from the agent options. The
89 agent must be configured in a way that pre-instrumented classes are excluded,
Marc R. Hoffmann47990a42012-12-28 13:54:23 +0100[diff] [blame]90 e.g. with "<code>excludes=*</code>". Otherwise it will result in error
91 messages on the console if the agent instruments such classes again.
Marc R. Hoffmann235a09e2012-12-23 15:57:16 +0100[diff] [blame]92</p>
93
94<h2>Execution Data Collection</h2>
95<p>
96 If <code>jacocoagent.jar</code> is used on the classpath it will collect
97 execution data the same way as used as a <a href="agent.html">Java agent</a>.
98 Depending on the <code>output</code> configuration execution data can be
99 collected via a remote connection or is written to the file system when the
100 JVM terminates. For the latter it is required that e.g. a <code>java</code>
101 task is executed with <code>fork="true"</code>.
102</p>
103
104<h2>Report Generation</h2>
105<p>
106 Based on the collected <code>*.exec</code> files reports can be created the
107 same way as for execution data collected with the Java agent. Note that for
108 report generation the original class files have to be supplied, not the
109 instrumented copies.
110</p>
111
112</div>
113<div class="footer">
114 <span class="right"><a href="@jacoco.home.url@">JaCoCo</a> @qualified.bundle.version@</span>
115 <a href="license.html">Copyright</a> &copy; @copyright.years@ Mountainminds GmbH &amp; Co. KG and Contributors
116</div>
117
118</body>
119</html>