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