xref: /aosp_15_r20/external/jacoco/org.jacoco.doc/docroot/doc/ant.html (revision 7e63c1270baf9bfa84f5b6aecf17bd0c1a75af94) 
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="stylesheet" href="../coverage/jacoco-resources/prettify.css" charset="UTF-8" type="text/css" />
8*7e63c127SSorin Basca  <link rel="shortcut icon" href="resources/report.gif" type="image/gif" />
9*7e63c127SSorin Basca  <script type="text/javascript" src="../coverage/jacoco-resources/prettify.js"></script>
10*7e63c127SSorin Basca  <title>JaCoCo - Ant Tasks</title>
11*7e63c127SSorin Basca</head>
12*7e63c127SSorin Basca<body onload="prettyPrint()">
13*7e63c127SSorin Basca
14*7e63c127SSorin Basca<div class="breadcrumb">
15*7e63c127SSorin Basca  <a href="../index.html" class="el_report">JaCoCo</a> &gt;
16*7e63c127SSorin Basca  <a href="index.html" class="el_group">Documentation</a> &gt;
17*7e63c127SSorin Basca  <span class="el_source">Ant Tasks</span>
18*7e63c127SSorin Basca</div>
19*7e63c127SSorin Basca<div id="content">
20*7e63c127SSorin Basca
21*7e63c127SSorin Basca<h1>Ant Tasks</h1>
22*7e63c127SSorin Basca
23*7e63c127SSorin Basca<p>
24*7e63c127SSorin Basca  JaCoCo comes with Ant tasks to launch Java programs with execution recording
25*7e63c127SSorin Basca  and for creating coverage reports from the recorded data. Execution data can
26*7e63c127SSorin Basca  be collected and managed with the tasks
27*7e63c127SSorin Basca  <a href="#coverage"><code>coverage</code></a>,
28*7e63c127SSorin Basca  <a href="#agent"><code>agent</code></a>,
29*7e63c127SSorin Basca  <a href="#dump"><code>dump</code></a> and
30*7e63c127SSorin Basca  <a href="#merge"><code>merge</code></a>. Reports in different formats are
31*7e63c127SSorin Basca  created with the <a href="#report"><code>report</code></a> task. For
32*7e63c127SSorin Basca  <a href="offline.html">offline instrumentation</a> the task
33*7e63c127SSorin Basca  <a href="#instrument"><code>instrument</code></a> can be used to prepare class
34*7e63c127SSorin Basca  files.
35*7e63c127SSorin Basca</p>
36*7e63c127SSorin Basca
37*7e63c127SSorin Basca<p class="hint">
38*7e63c127SSorin Basca  If you want to have line number information included in the coverage reports
39*7e63c127SSorin Basca  or you want source code highlighting the class files of the test target must
40*7e63c127SSorin Basca  be compiled with debug information.
41*7e63c127SSorin Basca</p>
42*7e63c127SSorin Basca
43*7e63c127SSorin Basca<h2>Example</h2>
44*7e63c127SSorin Basca
45*7e63c127SSorin Basca<p>
46*7e63c127SSorin Basca  The JaCoCo distribution contains a simple example how code coverage can be
47*7e63c127SSorin Basca  added to a Ant based build. The
48*7e63c127SSorin Basca  <a href="examples/build/build.xml">build script</a> compiles Java sources,
49*7e63c127SSorin Basca  runs an simple Java program and creates a coverage report. The complete
50*7e63c127SSorin Basca  example is located in the <code>./doc/examples/build</code> folder of the
51*7e63c127SSorin Basca  distribution.
52*7e63c127SSorin Basca</p>
53*7e63c127SSorin Basca
54*7e63c127SSorin Basca
55*7e63c127SSorin Basca<h2>Prerequisites</h2>
56*7e63c127SSorin Basca
57*7e63c127SSorin Basca<p>
58*7e63c127SSorin Basca  The JaCoCo Ant tasks require
59*7e63c127SSorin Basca</p>
60*7e63c127SSorin Basca
61*7e63c127SSorin Basca<ul>
62*7e63c127SSorin Basca  <li>Ant 1.7.0 or higher and</li>
63*7e63c127SSorin Basca  <li>Java 1.5 or higher (for both, the Ant runner and the test executor).</li>
64*7e63c127SSorin Basca</ul>
65*7e63c127SSorin Basca
66*7e63c127SSorin Basca
67*7e63c127SSorin Basca<p>All tasks are defined in <code>jacocoant.jar</code> (which is part of the
68*7e63c127SSorin Basca  distribution) and can be included in your Ant scripts with the usual
69*7e63c127SSorin Basca  <code>taskdef</code> declaration:
70*7e63c127SSorin Basca</p>
71*7e63c127SSorin Basca
72*7e63c127SSorin Basca<pre class="source lang-xml linenums">
73*7e63c127SSorin Basca&lt;project name="Example" xmlns:jacoco="antlib:org.jacoco.ant"&gt;
74*7e63c127SSorin Basca
75*7e63c127SSorin Basca    &lt;taskdef uri="antlib:org.jacoco.ant" resource="org/jacoco/ant/antlib.xml"&gt;
76*7e63c127SSorin Basca        &lt;classpath path="<i>path_to_jacoco</i>/lib/jacocoant.jar"/&gt;
77*7e63c127SSorin Basca    &lt;/taskdef&gt;
78*7e63c127SSorin Basca
79*7e63c127SSorin Basca    ...
80*7e63c127SSorin Basca
81*7e63c127SSorin Basca&lt;/project&gt;
82*7e63c127SSorin Basca</pre>
83*7e63c127SSorin Basca
84*7e63c127SSorin Basca<p>
85*7e63c127SSorin Basca  Alternatively you might also place the <code>jacocoant.jar</code> in your
86*7e63c127SSorin Basca  Ant <code><i>ANT_HOME</i>/lib</code> folder. If you use the name space URI
87*7e63c127SSorin Basca  <code>antlib:org.jacoco.ant</code> for JaCoCo tasks Ant will find them
88*7e63c127SSorin Basca  automatically without the <code>taskdef</code> declaration above.
89*7e63c127SSorin Basca</p>
90*7e63c127SSorin Basca
91*7e63c127SSorin Basca<p class="hint">
92*7e63c127SSorin Basca  Declaring a XML namespace for JaCoCo tasks is optional but always recommended
93*7e63c127SSorin Basca  if you mix tasks from different libraries. All subsequent examples use the
94*7e63c127SSorin Basca  <code>jacoco</code> prefix declared above. If you don't declare a separate
95*7e63c127SSorin Basca  namespace the <code>jacoco</code> prefix must be removed from the following
96*7e63c127SSorin Basca  examples.
97*7e63c127SSorin Basca</p>
98*7e63c127SSorin Basca
99*7e63c127SSorin Basca<h2><a name="coverage">Task <code>coverage</code></a></h2>
100*7e63c127SSorin Basca
101*7e63c127SSorin Basca<p>
102*7e63c127SSorin Basca  The standard Ant tasks to launch Java programs are <code>java</code>, <code>junit</code> and
103*7e63c127SSorin Basca  <code>testng</code>. To add code coverage recording to these tasks they can
104*7e63c127SSorin Basca  simply be wrapped with the <code>coverage</code> task as shown in the
105*7e63c127SSorin Basca  following examples:
106*7e63c127SSorin Basca</p>
107*7e63c127SSorin Basca
108*7e63c127SSorin Basca<pre class="source lang-xml linenums">
109*7e63c127SSorin Basca&lt;jacoco:coverage>
110*7e63c127SSorin Basca    &lt;java classname="org.jacoco.examples.HelloJaCoCo" fork="true"&gt;
111*7e63c127SSorin Basca        &lt;classpath&gt;
112*7e63c127SSorin Basca            &lt;pathelement location="./bin"/&gt;
113*7e63c127SSorin Basca        &lt;/classpath&gt;
114*7e63c127SSorin Basca    &lt;/java&gt;
115*7e63c127SSorin Basca&lt;/jacoco:coverage&gt;
116*7e63c127SSorin Basca
117*7e63c127SSorin Basca
118*7e63c127SSorin Basca&lt;jacoco:coverage>
119*7e63c127SSorin Basca    &lt;junit fork="true" forkmode="once"&gt;
120*7e63c127SSorin Basca        &lt;test name="org.jacoco.examples.HelloJaCoCoTest"/&gt;
121*7e63c127SSorin Basca        &lt;classpath&gt;
122*7e63c127SSorin Basca            &lt;pathelement location="./bin"/&gt;
123*7e63c127SSorin Basca        &lt;/classpath&gt;
124*7e63c127SSorin Basca    &lt;/junit&gt;
125*7e63c127SSorin Basca&lt;/jacoco:coverage&gt;
126*7e63c127SSorin Basca</pre>
127*7e63c127SSorin Basca
128*7e63c127SSorin Basca<p>
129*7e63c127SSorin Basca  Resulting coverage information is collected during execution and written
130*7e63c127SSorin Basca  to a file when the process terminates. Note the <code>fork</code> attribute
131*7e63c127SSorin Basca  above in the wrapped <code>java</code> task.
132*7e63c127SSorin Basca</p>
133*7e63c127SSorin Basca
134*7e63c127SSorin Basca<p class="hint">
135*7e63c127SSorin Basca  The nested task always has to declare <code>fork="true"</code>, otherwise the
136*7e63c127SSorin Basca  <code>coverage</code> task can't record coverage information and will fail.
137*7e63c127SSorin Basca  In addition the <code>junit</code> task should declare
138*7e63c127SSorin Basca  <code>forkmode="once"</code> to avoid starting a new JVM for every single test
139*7e63c127SSorin Basca  case and decreasing execution performance dramatically (unless this is
140*7e63c127SSorin Basca  required by the nature of the test cases). Note that
141*7e63c127SSorin Basca  <code>forkmode="perTest"</code> or <code>forkmode="perBatch"</code> should not
142*7e63c127SSorin Basca  be combined with <code>append="false"</code> as the execution data file is
143*7e63c127SSorin Basca  overwritten with the execution of every test.
144*7e63c127SSorin Basca</p>
145*7e63c127SSorin Basca
146*7e63c127SSorin Basca<p>
147*7e63c127SSorin Basca  The coverage task must wrap exactly one task. While it typically works without
148*7e63c127SSorin Basca  any configuration, the behavior can be adjusted with some optional attributes:
149*7e63c127SSorin Basca</p>
150*7e63c127SSorin Basca
151*7e63c127SSorin Basca<table class="coverage">
152*7e63c127SSorin Basca  <thead>
153*7e63c127SSorin Basca    <tr>
154*7e63c127SSorin Basca      <td>Attribute</td>
155*7e63c127SSorin Basca      <td>Description</td>
156*7e63c127SSorin Basca      <td>Default</td>
157*7e63c127SSorin Basca    </tr>
158*7e63c127SSorin Basca  </thead>
159*7e63c127SSorin Basca  <tbody>
160*7e63c127SSorin Basca    <tr>
161*7e63c127SSorin Basca      <td><code>enabled</code></td>
162*7e63c127SSorin Basca      <td>If set to <code>true</code> coverage data will be collected for the contained task.</td>
163*7e63c127SSorin Basca      <td><code>true</code></td>
164*7e63c127SSorin Basca    </tr>
165*7e63c127SSorin Basca    <tr>
166*7e63c127SSorin Basca      <td><code>destfile</code></td>
167*7e63c127SSorin Basca      <td>Path to the output file for execution data.</td>
168*7e63c127SSorin Basca      <td><code>jacoco.exec</code></td>
169*7e63c127SSorin Basca    </tr>
170*7e63c127SSorin Basca    <tr>
171*7e63c127SSorin Basca      <td><code>append</code></td>
172*7e63c127SSorin Basca      <td>If set to <code>true</code> and the execution data file already
173*7e63c127SSorin Basca          exists, coverage data is appended to the existing file. If set to
174*7e63c127SSorin Basca          <code>false</code>, an existing execution data file will be replaced.
175*7e63c127SSorin Basca      </td>
176*7e63c127SSorin Basca      <td><code>true</code></td>
177*7e63c127SSorin Basca    </tr>
178*7e63c127SSorin Basca    <tr>
179*7e63c127SSorin Basca      <td><code>includes</code></td>
180*7e63c127SSorin Basca      <td>A list of class names that should be included in execution analysis.
181*7e63c127SSorin Basca          The list entries are separated by a colon (<code>:</code>) and
182*7e63c127SSorin Basca          may use wildcard characters (<code>*</code> and <code>?</code>).
183*7e63c127SSorin Basca          Except for performance optimization or technical corner cases this
184*7e63c127SSorin Basca          option is normally not required.
185*7e63c127SSorin Basca      </td>
186*7e63c127SSorin Basca      <td><code>*</code> (all classes)</td>
187*7e63c127SSorin Basca    </tr>
188*7e63c127SSorin Basca    <tr>
189*7e63c127SSorin Basca      <td><code>excludes</code></td>
190*7e63c127SSorin Basca      <td>A list of class names that should be excluded from execution analysis.
191*7e63c127SSorin Basca          The list entries are separated by a colon (<code>:</code>) and
192*7e63c127SSorin Basca          may use wildcard characters (<code>*</code> and <code>?</code>).
193*7e63c127SSorin Basca          Except for performance optimization or technical corner cases this
194*7e63c127SSorin Basca          option is normally not required. If you want to exclude classes from
195*7e63c127SSorin Basca          the report please configure the <code>report</code> task accordingly.
196*7e63c127SSorin Basca      </td>
197*7e63c127SSorin Basca      <td><i>empty</i> (no excluded classes)</td>
198*7e63c127SSorin Basca    </tr>
199*7e63c127SSorin Basca    <tr>
200*7e63c127SSorin Basca      <td><code>exclclassloader</code></td>
201*7e63c127SSorin Basca      <td>A list of class loader names, that should be excluded from execution
202*7e63c127SSorin Basca          analysis. The list entries are separated by a colon
203*7e63c127SSorin Basca          (<code>:</code>) and may use wildcard characters (<code>*</code> and
204*7e63c127SSorin Basca          <code>?</code>). This option might be required in case of special
205*7e63c127SSorin Basca          frameworks that conflict with JaCoCo code instrumentation, in
206*7e63c127SSorin Basca          particular class loaders that do not have access to the Java runtime
207*7e63c127SSorin Basca          classes.
208*7e63c127SSorin Basca      </td>
209*7e63c127SSorin Basca      <td><code>sun.reflect.DelegatingClassLoader</code></td>
210*7e63c127SSorin Basca    </tr>
211*7e63c127SSorin Basca    <tr>
212*7e63c127SSorin Basca      <td><code>inclbootstrapclasses</code></td>
213*7e63c127SSorin Basca      <td>Specifies whether also classes from the bootstrap classloader should
214*7e63c127SSorin Basca          be instrumented. Use this feature with caution, it needs heavy
215*7e63c127SSorin Basca          includes/excludes tuning.
216*7e63c127SSorin Basca      </td>
217*7e63c127SSorin Basca      <td><code>false</code></td>
218*7e63c127SSorin Basca    </tr>
219*7e63c127SSorin Basca    <tr>
220*7e63c127SSorin Basca      <td><code>inclnolocationclasses</code></td>
221*7e63c127SSorin Basca      <td>Specifies whether also classes without a source location should be
222*7e63c127SSorin Basca          instrumented. Normally such classes are generated at runtime e.g. by
223*7e63c127SSorin Basca          mocking frameworks and are therefore excluded by default.
224*7e63c127SSorin Basca      </td>
225*7e63c127SSorin Basca      <td><code>false</code></td>
226*7e63c127SSorin Basca    </tr>
227*7e63c127SSorin Basca    <tr>
228*7e63c127SSorin Basca      <td><code>sessionid</code></td>
229*7e63c127SSorin Basca      <td>A session identifier that is written with the execution data. Without
230*7e63c127SSorin Basca          this parameter a random identifier is created by the agent.
231*7e63c127SSorin Basca      </td>
232*7e63c127SSorin Basca      <td><i>auto-generated</i></td>
233*7e63c127SSorin Basca    </tr>
234*7e63c127SSorin Basca    <tr>
235*7e63c127SSorin Basca      <td><code>dumponexit</code></td>
236*7e63c127SSorin Basca      <td>If set to <code>true</code> coverage data will be written on VM
237*7e63c127SSorin Basca          shutdown.
238*7e63c127SSorin Basca      </td>
239*7e63c127SSorin Basca      <td><code>true</code></td>
240*7e63c127SSorin Basca    </tr>
241*7e63c127SSorin Basca    <tr>
242*7e63c127SSorin Basca      <td><code>output</code></td>
243*7e63c127SSorin Basca      <td>Output method to use for writing coverage data. Valid options are:
244*7e63c127SSorin Basca        <ul>
245*7e63c127SSorin Basca          <li><code>file</code>: At VM termination execution data is written to
246*7e63c127SSorin Basca              the file specified in the <code>destfile</code> attribute.</li>
247*7e63c127SSorin Basca          <li><code>tcpserver</code>: The agent listens for incoming connections
248*7e63c127SSorin Basca              on the TCP port specified by the <code>address</code> and
249*7e63c127SSorin Basca              <code>port</code> attribute. Execution data is written to this
250*7e63c127SSorin Basca              TCP connection.</li>
251*7e63c127SSorin Basca          <li><code>tcpclient</code>: At startup the agent connects to the TCP
252*7e63c127SSorin Basca              port specified by the <code>address</code> and <code>port</code>
253*7e63c127SSorin Basca              attribute. Execution data is written to this TCP connection.</li>
254*7e63c127SSorin Basca          <li><code>none</code>: Do not produce any output.</li>
255*7e63c127SSorin Basca        </ul>
256*7e63c127SSorin Basca      </td>
257*7e63c127SSorin Basca      <td><code>file</code></td>
258*7e63c127SSorin Basca    </tr>
259*7e63c127SSorin Basca    <tr>
260*7e63c127SSorin Basca      <td><code>address</code></td>
261*7e63c127SSorin Basca      <td>IP address or hostname to bind to when the output method is
262*7e63c127SSorin Basca          <code>tcpserver</code> or connect to when the output method is
263*7e63c127SSorin Basca          <code>tcpclient</code>.  In <code>tcpserver</code> mode the value
264*7e63c127SSorin Basca          "<code>*</code>" causes the agent to accept connections on any local
265*7e63c127SSorin Basca          address.
266*7e63c127SSorin Basca      </td>
267*7e63c127SSorin Basca      <td><i>loopback interface</i></td>
268*7e63c127SSorin Basca    </tr>
269*7e63c127SSorin Basca    <tr>
270*7e63c127SSorin Basca      <td><code>port</code></td>
271*7e63c127SSorin Basca      <td>Port to bind to when the output method is <code>tcpserver</code> or
272*7e63c127SSorin Basca          connect to when the output method is <code>tcpclient</code>. In
273*7e63c127SSorin Basca          <code>tcpserver</code> mode the port must be available, which means
274*7e63c127SSorin Basca          that if multiple JaCoCo agents should run on the same machine,
275*7e63c127SSorin Basca          different ports have to be specified.
276*7e63c127SSorin Basca      </td>
277*7e63c127SSorin Basca      <td><code>6300</code></td>
278*7e63c127SSorin Basca    </tr>
279*7e63c127SSorin Basca    <tr>
280*7e63c127SSorin Basca      <td><code>classdumpdir</code></td>
281*7e63c127SSorin Basca      <td>Location relative to the working directory where all class files seen
282*7e63c127SSorin Basca          by the agent are dumped to. This can be useful for debugging purposes
283*7e63c127SSorin Basca          or in case of dynamically created classes for example when scripting
284*7e63c127SSorin Basca          engines are used.
285*7e63c127SSorin Basca      </td>
286*7e63c127SSorin Basca      <td><i>no dumps</i></td>
287*7e63c127SSorin Basca    </tr>
288*7e63c127SSorin Basca    <tr>
289*7e63c127SSorin Basca      <td><code>jmx</code></td>
290*7e63c127SSorin Basca      <td>If set to <code>true</code> the agent exposes
291*7e63c127SSorin Basca          <a href="./api/org/jacoco/agent/rt/IAgent.html">functionality</a> via
292*7e63c127SSorin Basca          JMX under the name <code>org.jacoco:type=Runtime</code>.
293*7e63c127SSorin Basca      </td>
294*7e63c127SSorin Basca      <td><code>false</code></td>
295*7e63c127SSorin Basca    </tr>
296*7e63c127SSorin Basca  </tbody>
297*7e63c127SSorin Basca</table>
298*7e63c127SSorin Basca
299*7e63c127SSorin Basca
300*7e63c127SSorin Basca<h2><a name="agent">Task <code>agent</code></a></h2>
301*7e63c127SSorin Basca
302*7e63c127SSorin Basca<p>
303*7e63c127SSorin Basca  If the <code>coverage</code> task is not suitable for your launch target, you
304*7e63c127SSorin Basca  might alternatively use the <code>agent</code> task to create the
305*7e63c127SSorin Basca  <a href="agent.html">Java agent</a> parameter. The following example defines a
306*7e63c127SSorin Basca  Ant property with the name <code>agentvmparam</code> that can be directly used
307*7e63c127SSorin Basca  as a Java VM parameter:
308*7e63c127SSorin Basca</p>
309*7e63c127SSorin Basca
310*7e63c127SSorin Basca<pre class="source lang-xml linenums">
311*7e63c127SSorin Basca&lt;jacoco:agent property="agentvmparam"/&gt;
312*7e63c127SSorin Basca</pre>
313*7e63c127SSorin Basca
314*7e63c127SSorin Basca<p>
315*7e63c127SSorin Basca  This task has the same attributes as the <code>coverage</code> task plus an
316*7e63c127SSorin Basca  additional property to specify the target property name:
317*7e63c127SSorin Basca</p>
318*7e63c127SSorin Basca
319*7e63c127SSorin Basca<table class="coverage">
320*7e63c127SSorin Basca  <thead>
321*7e63c127SSorin Basca    <tr>
322*7e63c127SSorin Basca      <td>Attribute</td>
323*7e63c127SSorin Basca      <td>Description</td>
324*7e63c127SSorin Basca      <td>Default</td>
325*7e63c127SSorin Basca    </tr>
326*7e63c127SSorin Basca  </thead>
327*7e63c127SSorin Basca  <tbody>
328*7e63c127SSorin Basca    <tr>
329*7e63c127SSorin Basca      <td><code>enabled</code></td>
330*7e63c127SSorin Basca      <td>When this variable is set to <code>false</code> the value of <code>property</code> will be set to an empty string, effectively
331*7e63c127SSorin Basca          disabling coverage instrumentation for any tasks that used the value.</td>
332*7e63c127SSorin Basca      <td><code>true</code></td>
333*7e63c127SSorin Basca    </tr>
334*7e63c127SSorin Basca    <tr>
335*7e63c127SSorin Basca      <td><code>property</code></td>
336*7e63c127SSorin Basca      <td>Name of the Ant property to set.</td>
337*7e63c127SSorin Basca      <td><i>none (required)</i></td>
338*7e63c127SSorin Basca    </tr>
339*7e63c127SSorin Basca    <tr>
340*7e63c127SSorin Basca      <td colspan="3"><i>All attributes of the <code>coverage</code> task.</i></td>
341*7e63c127SSorin Basca    </tr>
342*7e63c127SSorin Basca  </tbody>
343*7e63c127SSorin Basca</table>
344*7e63c127SSorin Basca
345*7e63c127SSorin Basca
346*7e63c127SSorin Basca<h2><a name="dump">Task <code>dump</code></a></h2>
347*7e63c127SSorin Basca
348*7e63c127SSorin Basca<p>
349*7e63c127SSorin Basca  This task allows to remotely collect execution data from another JVM without
350*7e63c127SSorin Basca  stopping it. For example:
351*7e63c127SSorin Basca</p>
352*7e63c127SSorin Basca
353*7e63c127SSorin Basca<pre class="source lang-xml linenums">
354*7e63c127SSorin Basca&lt;jacoco:dump address="server.example.com" reset="true" destfile="remote.exec"/&gt;
355*7e63c127SSorin Basca</pre>
356*7e63c127SSorin Basca
357*7e63c127SSorin Basca<p>
358*7e63c127SSorin Basca  Remote dumps are usefull for long running Java processes like application
359*7e63c127SSorin Basca  servers.
360*7e63c127SSorin Basca</p>
361*7e63c127SSorin Basca
362*7e63c127SSorin Basca<p class="hint">
363*7e63c127SSorin Basca  The target JVM needs to have a <a href="agent.html">JaCoCo agent</a>
364*7e63c127SSorin Basca  configured with <code>output</code> mode <code>tcpserver</code>. See
365*7e63c127SSorin Basca  <a href="#coverage"><code>coverage</code></a> and
366*7e63c127SSorin Basca  <a href="#agent"><code>agent</code></a> tasks above.
367*7e63c127SSorin Basca</p>
368*7e63c127SSorin Basca
369*7e63c127SSorin Basca<p>
370*7e63c127SSorin Basca  The <code>dump</code> task has the following attributes:
371*7e63c127SSorin Basca</p>
372*7e63c127SSorin Basca
373*7e63c127SSorin Basca<table class="coverage">
374*7e63c127SSorin Basca  <thead>
375*7e63c127SSorin Basca    <tr>
376*7e63c127SSorin Basca      <td>Attribute</td>
377*7e63c127SSorin Basca      <td>Description</td>
378*7e63c127SSorin Basca      <td>Default</td>
379*7e63c127SSorin Basca    </tr>
380*7e63c127SSorin Basca  </thead>
381*7e63c127SSorin Basca  <tbody>
382*7e63c127SSorin Basca    <tr>
383*7e63c127SSorin Basca      <td><code>address</code></td>
384*7e63c127SSorin Basca      <td>Target IP address or DNS name.</td>
385*7e63c127SSorin Basca      <td><code>localhost</code></td>
386*7e63c127SSorin Basca    </tr>
387*7e63c127SSorin Basca    <tr>
388*7e63c127SSorin Basca      <td><code>port</code></td>
389*7e63c127SSorin Basca      <td>Target TCP port.</td>
390*7e63c127SSorin Basca      <td><code>6300</code></td>
391*7e63c127SSorin Basca    </tr>
392*7e63c127SSorin Basca    <tr>
393*7e63c127SSorin Basca      <td><code>retryCount</code></td>
394*7e63c127SSorin Basca      <td>Number of retries which the goal will attempt to establish a
395*7e63c127SSorin Basca          connection. This can be used to wait until the target JVM is
396*7e63c127SSorin Basca          successfully launched.</td>
397*7e63c127SSorin Basca      <td><code>10</code></td>
398*7e63c127SSorin Basca    </tr>
399*7e63c127SSorin Basca    <tr>
400*7e63c127SSorin Basca      <td><code>dump</code></td>
401*7e63c127SSorin Basca      <td>Flag whether execution data should be dumped.</td>
402*7e63c127SSorin Basca      <td><code>true</code></td>
403*7e63c127SSorin Basca    </tr>
404*7e63c127SSorin Basca    <tr>
405*7e63c127SSorin Basca      <td><code>reset</code></td>
406*7e63c127SSorin Basca      <td>Flag whether execution data should be reset in the target agent after
407*7e63c127SSorin Basca          the dump.</td>
408*7e63c127SSorin Basca      <td><code>false</code></td>
409*7e63c127SSorin Basca    </tr>
410*7e63c127SSorin Basca    <tr>
411*7e63c127SSorin Basca      <td><code>destfile</code></td>
412*7e63c127SSorin Basca      <td>File location to write the collected execution data to.</td>
413*7e63c127SSorin Basca      <td><i>none (required if dump=true)</i></td>
414*7e63c127SSorin Basca    </tr>
415*7e63c127SSorin Basca    <tr>
416*7e63c127SSorin Basca      <td><code>append</code></td>
417*7e63c127SSorin Basca      <td>If set to <code>true</code> and the execution data file already
418*7e63c127SSorin Basca          exists, coverage data is appended to the existing file. If set to
419*7e63c127SSorin Basca          <code>false</code>, an existing execution data file will be replaced.
420*7e63c127SSorin Basca      </td>
421*7e63c127SSorin Basca      <td><code>true</code></td>
422*7e63c127SSorin Basca    </tr>
423*7e63c127SSorin Basca  </tbody>
424*7e63c127SSorin Basca</table>
425*7e63c127SSorin Basca
426*7e63c127SSorin Basca
427*7e63c127SSorin Basca<h2><a name="merge">Task <code>merge</code></a></h2>
428*7e63c127SSorin Basca
429*7e63c127SSorin Basca<p>
430*7e63c127SSorin Basca  This task can be used to merge the execution data from multiple test runs
431*7e63c127SSorin Basca  into a single data store.
432*7e63c127SSorin Basca</p>
433*7e63c127SSorin Basca
434*7e63c127SSorin Basca<pre class="source lang-xml linenums">
435*7e63c127SSorin Basca&lt;jacoco:merge destfile="merged.exec"&gt;
436*7e63c127SSorin Basca    &lt;fileset dir="executionData" includes="*.exec"/&gt;
437*7e63c127SSorin Basca&lt;/jacoco:merge&gt;
438*7e63c127SSorin Basca</pre>
439*7e63c127SSorin Basca
440*7e63c127SSorin Basca<p>
441*7e63c127SSorin Basca  The task definition can contain any number of resource collection types and
442*7e63c127SSorin Basca  has the following mandatory attribute:
443*7e63c127SSorin Basca</p>
444*7e63c127SSorin Basca
445*7e63c127SSorin Basca<table class="coverage">
446*7e63c127SSorin Basca  <thead>
447*7e63c127SSorin Basca    <tr>
448*7e63c127SSorin Basca      <td>Attribute</td>
449*7e63c127SSorin Basca      <td>Description</td>
450*7e63c127SSorin Basca      <td>Default</td>
451*7e63c127SSorin Basca    </tr>
452*7e63c127SSorin Basca  </thead>
453*7e63c127SSorin Basca  <tbody>
454*7e63c127SSorin Basca    <tr>
455*7e63c127SSorin Basca      <td><code>destfile</code></td>
456*7e63c127SSorin Basca      <td>File location to write the merged execution data to.</td>
457*7e63c127SSorin Basca      <td><i>none (required)</i></td>
458*7e63c127SSorin Basca    </tr>
459*7e63c127SSorin Basca  </tbody>
460*7e63c127SSorin Basca</table>
461*7e63c127SSorin Basca
462*7e63c127SSorin Basca
463*7e63c127SSorin Basca<h2><a name="report">Task <code>report</code></a></h2>
464*7e63c127SSorin Basca
465*7e63c127SSorin Basca<p>
466*7e63c127SSorin Basca  Finally different reports can be created with the <code>report</code> task.
467*7e63c127SSorin Basca  A report task declaration consists of different sections, two specify the
468*7e63c127SSorin Basca  input data, additional ones specify the output formats:
469*7e63c127SSorin Basca</p>
470*7e63c127SSorin Basca
471*7e63c127SSorin Basca<pre class="source lang-xml linenums">
472*7e63c127SSorin Basca&lt;jacoco:report&gt;
473*7e63c127SSorin Basca
474*7e63c127SSorin Basca    &lt;executiondata&gt;
475*7e63c127SSorin Basca        &lt;file file="jacoco.exec"/&gt;
476*7e63c127SSorin Basca    &lt;/executiondata&gt;
477*7e63c127SSorin Basca
478*7e63c127SSorin Basca    &lt;structure name="Example Project"&gt;
479*7e63c127SSorin Basca        &lt;classfiles&gt;
480*7e63c127SSorin Basca            &lt;fileset dir="classes"/&gt;
481*7e63c127SSorin Basca        &lt;/classfiles&gt;
482*7e63c127SSorin Basca        &lt;sourcefiles encoding="UTF-8"&gt;
483*7e63c127SSorin Basca            &lt;fileset dir="src"/&gt;
484*7e63c127SSorin Basca        &lt;/sourcefiles&gt;
485*7e63c127SSorin Basca    &lt;/structure&gt;
486*7e63c127SSorin Basca
487*7e63c127SSorin Basca    &lt;html destdir="report"/&gt;
488*7e63c127SSorin Basca
489*7e63c127SSorin Basca&lt;/jacoco:report&gt;
490*7e63c127SSorin Basca</pre>
491*7e63c127SSorin Basca
492*7e63c127SSorin Basca<p>
493*7e63c127SSorin Basca  As you can see from the example above the <code>report</code> task is based
494*7e63c127SSorin Basca  on several nested elements:
495*7e63c127SSorin Basca</p>
496*7e63c127SSorin Basca
497*7e63c127SSorin Basca<h3>Element <code>executiondata</code></h3>
498*7e63c127SSorin Basca
499*7e63c127SSorin Basca<p>
500*7e63c127SSorin Basca  Within this element Ant resources and resource collections can be specified,
501*7e63c127SSorin Basca  that represent JaCoCo execution data files. If more than one execution data
502*7e63c127SSorin Basca  file is specified, execution data is combined. A particular piece of code is
503*7e63c127SSorin Basca  considered executed when it is marked as such in any of the input files.
504*7e63c127SSorin Basca</p>
505*7e63c127SSorin Basca
506*7e63c127SSorin Basca<h3>Element <code>structure</code></h3>
507*7e63c127SSorin Basca
508*7e63c127SSorin Basca<p>
509*7e63c127SSorin Basca  This element defines the report structure. It might contain the following
510*7e63c127SSorin Basca  nested elements:
511*7e63c127SSorin Basca</p>
512*7e63c127SSorin Basca
513*7e63c127SSorin Basca<ul>
514*7e63c127SSorin Basca  <li><code>classfiles</code>: Container element for Ant resources and resource
515*7e63c127SSorin Basca    collections that can specify Java class files, archive files (jar, war, ear
516*7e63c127SSorin Basca    etc. or Pack200) or folders containing class files. Archives and folders are
517*7e63c127SSorin Basca    searched recursively for class files.</li>
518*7e63c127SSorin Basca  <li><code>sourcefiles</code>: Optional container element for Ant resources and
519*7e63c127SSorin Basca    resource collections that specify corresponding source files. If source
520*7e63c127SSorin Basca    files are specified, some report formats include highlighted source code.
521*7e63c127SSorin Basca    Source files can be specified as individual files or as source directories.</li>
522*7e63c127SSorin Basca</ul>
523*7e63c127SSorin Basca
524*7e63c127SSorin Basca<p>
525*7e63c127SSorin Basca  The <code>sourcefiles</code> element has these optional attributes:
526*7e63c127SSorin Basca</p>
527*7e63c127SSorin Basca
528*7e63c127SSorin Basca<table class="coverage">
529*7e63c127SSorin Basca  <thead>
530*7e63c127SSorin Basca    <tr>
531*7e63c127SSorin Basca      <td>Attribute</td>
532*7e63c127SSorin Basca      <td>Description</td>
533*7e63c127SSorin Basca      <td>Default</td>
534*7e63c127SSorin Basca    </tr>
535*7e63c127SSorin Basca  </thead>
536*7e63c127SSorin Basca  <tbody>
537*7e63c127SSorin Basca    <tr>
538*7e63c127SSorin Basca      <td><code>encoding</code></td>
539*7e63c127SSorin Basca      <td>Character encoding of the source files.</td>
540*7e63c127SSorin Basca      <td>Platform default encoding</td>
541*7e63c127SSorin Basca    </tr>
542*7e63c127SSorin Basca    <tr>
543*7e63c127SSorin Basca      <td><code>tabwidth</code></td>
544*7e63c127SSorin Basca      <td>Number of whitespace characters that represent a tab character.</td>
545*7e63c127SSorin Basca      <td>4 characters</td>
546*7e63c127SSorin Basca    </tr>
547*7e63c127SSorin Basca  </tbody>
548*7e63c127SSorin Basca</table>
549*7e63c127SSorin Basca
550*7e63c127SSorin Basca<p class="hint">
551*7e63c127SSorin Basca  <b>Important:</b> Source file resources must always be specified relative to
552*7e63c127SSorin Basca  the respective source folder. If directory resources are given, they must
553*7e63c127SSorin Basca  directly point to source folders. Otherwise source lookup will not succeed.
554*7e63c127SSorin Basca</p>
555*7e63c127SSorin Basca
556*7e63c127SSorin Basca<p>
557*7e63c127SSorin Basca  Note that the <code>classfiles</code> and <code>sourcefiles</code> elements
558*7e63c127SSorin Basca  accept any
559*7e63c127SSorin Basca  <a href="http://ant.apache.org/manual/Types/resources.html#collection">Ant
560*7e63c127SSorin Basca  resource collection</a>. Therefore also filtering the class file set is
561*7e63c127SSorin Basca  possible and allows to narrow the scope of the report, for example:
562*7e63c127SSorin Basca</p>
563*7e63c127SSorin Basca
564*7e63c127SSorin Basca<pre class="source lang-xml linenums">
565*7e63c127SSorin Basca&lt;classfiles&gt;
566*7e63c127SSorin Basca    &lt;fileset dir="classes"&gt;
567*7e63c127SSorin Basca        &lt;include name="org/jacoco/examples/important/**/*.class"/&gt;
568*7e63c127SSorin Basca    &lt;/fileset&gt;
569*7e63c127SSorin Basca&lt;/classfiles&gt;
570*7e63c127SSorin Basca</pre>
571*7e63c127SSorin Basca
572*7e63c127SSorin Basca<p class="hint">
573*7e63c127SSorin Basca  <b>Performance Warning:</b> Although it is technically possible and sometimes
574*7e63c127SSorin Basca  convenient to use Ant's <code>zipfileset</code> to specify class or source
575*7e63c127SSorin Basca  files, this resource type has poor performance characteristics and comes with
576*7e63c127SSorin Basca  an huge memory overhead especially for large scale projects.
577*7e63c127SSorin Basca</p>
578*7e63c127SSorin Basca
579*7e63c127SSorin Basca<p>
580*7e63c127SSorin Basca  The structure can be refined with a hierarchy of <code>group</code> elements.
581*7e63c127SSorin Basca  This way the coverage report can reflect different modules of a software
582*7e63c127SSorin Basca  project. For each group element the corresponding class and source files can
583*7e63c127SSorin Basca  be specified separately. For example:
584*7e63c127SSorin Basca</p>
585*7e63c127SSorin Basca
586*7e63c127SSorin Basca<pre class="source lang-xml linenums">
587*7e63c127SSorin Basca&lt;structure name="Example Project"&gt;
588*7e63c127SSorin Basca    &lt;group name="Server"&gt;
589*7e63c127SSorin Basca        &lt;classfiles&gt;
590*7e63c127SSorin Basca            &lt;fileset dir="${workspace.dir}/org.jacoco.example.server/classes"/&gt;
591*7e63c127SSorin Basca        &lt;/classfiles&gt;
592*7e63c127SSorin Basca        &lt;sourcefiles&gt;
593*7e63c127SSorin Basca            &lt;fileset dir="${workspace.dir}/org.jacoco.example.server/src"/&gt;
594*7e63c127SSorin Basca        &lt;/sourcefiles&gt;
595*7e63c127SSorin Basca    &lt;/group&gt;
596*7e63c127SSorin Basca    &lt;group name="Client"&gt;
597*7e63c127SSorin Basca        &lt;classfiles&gt;
598*7e63c127SSorin Basca            &lt;fileset dir="${workspace.dir}/org.jacoco.example.client/classes"/&gt;
599*7e63c127SSorin Basca        &lt;/classfiles&gt;
600*7e63c127SSorin Basca        &lt;sourcefiles&gt;
601*7e63c127SSorin Basca            &lt;fileset dir="${workspace.dir}/org.jacoco.example.client/src"/&gt;
602*7e63c127SSorin Basca        &lt;/sourcefiles&gt;
603*7e63c127SSorin Basca    &lt;/group&gt;
604*7e63c127SSorin Basca
605*7e63c127SSorin Basca    ...
606*7e63c127SSorin Basca
607*7e63c127SSorin Basca&lt;/structure&gt;
608*7e63c127SSorin Basca</pre>
609*7e63c127SSorin Basca
610*7e63c127SSorin Basca<p>
611*7e63c127SSorin Basca  Both <code>structure</code> and <code>group</code> elements have the following
612*7e63c127SSorin Basca  mandatory attribute:
613*7e63c127SSorin Basca</p>
614*7e63c127SSorin Basca
615*7e63c127SSorin Basca<table class="coverage">
616*7e63c127SSorin Basca  <thead>
617*7e63c127SSorin Basca    <tr>
618*7e63c127SSorin Basca      <td>Attribute</td>
619*7e63c127SSorin Basca      <td>Description</td>
620*7e63c127SSorin Basca      <td>Default</td>
621*7e63c127SSorin Basca    </tr>
622*7e63c127SSorin Basca  </thead>
623*7e63c127SSorin Basca  <tbody>
624*7e63c127SSorin Basca    <tr>
625*7e63c127SSorin Basca      <td><code>name</code></td>
626*7e63c127SSorin Basca      <td>Name of the structure or group.</td>
627*7e63c127SSorin Basca      <td><i>none (required)</i></td>
628*7e63c127SSorin Basca    </tr>
629*7e63c127SSorin Basca  </tbody>
630*7e63c127SSorin Basca</table>
631*7e63c127SSorin Basca
632*7e63c127SSorin Basca<h3>Element <code>html</code></h3>
633*7e63c127SSorin Basca
634*7e63c127SSorin Basca<p>
635*7e63c127SSorin Basca  Create a multi-page report in HTML format. The report can either be written as
636*7e63c127SSorin Basca  multiple files into a directory or compressed into a single ZIP file.
637*7e63c127SSorin Basca</p>
638*7e63c127SSorin Basca
639*7e63c127SSorin Basca<table class="coverage">
640*7e63c127SSorin Basca  <thead>
641*7e63c127SSorin Basca    <tr>
642*7e63c127SSorin Basca      <td>Attribute</td>
643*7e63c127SSorin Basca      <td>Description</td>
644*7e63c127SSorin Basca      <td>Default</td>
645*7e63c127SSorin Basca    </tr>
646*7e63c127SSorin Basca  </thead>
647*7e63c127SSorin Basca  <tbody>
648*7e63c127SSorin Basca    <tr>
649*7e63c127SSorin Basca      <td><code>destdir</code></td>
650*7e63c127SSorin Basca      <td>Directory to create the report in. Either this property or
651*7e63c127SSorin Basca        <code>destfile</code> has to be supplied.</td>
652*7e63c127SSorin Basca      <td><i>none (required)</i></td>
653*7e63c127SSorin Basca    </tr>
654*7e63c127SSorin Basca    <tr>
655*7e63c127SSorin Basca      <td><code>destfile</code></td>
656*7e63c127SSorin Basca      <td>Zip file to create the report in.  Either this property or
657*7e63c127SSorin Basca        <code>destdir</code> has to be supplied.</td>
658*7e63c127SSorin Basca      <td><i>none (required)</i></td>
659*7e63c127SSorin Basca    </tr>
660*7e63c127SSorin Basca    <tr>
661*7e63c127SSorin Basca      <td><code>footer</code></td>
662*7e63c127SSorin Basca      <td>Footer text for each report page.</td>
663*7e63c127SSorin Basca      <td><i>no footer</i></td>
664*7e63c127SSorin Basca    </tr>
665*7e63c127SSorin Basca    <tr>
666*7e63c127SSorin Basca      <td><code>encoding</code></td>
667*7e63c127SSorin Basca      <td>Character encoding of generated HTML pages.</td>
668*7e63c127SSorin Basca      <td><code>UTF-8</code></td>
669*7e63c127SSorin Basca    </tr>
670*7e63c127SSorin Basca    <tr>
671*7e63c127SSorin Basca      <td><code>locale</code></td>
672*7e63c127SSorin Basca      <td>Locale specified as ISO code (en, fr, jp, ...) used for number
673*7e63c127SSorin Basca      formatting. Locale country and variant can be separated with an underscore
674*7e63c127SSorin Basca      (de_CH).</td>
675*7e63c127SSorin Basca      <td><i>platform locale</i></td>
676*7e63c127SSorin Basca    </tr>
677*7e63c127SSorin Basca  </tbody>
678*7e63c127SSorin Basca</table>
679*7e63c127SSorin Basca
680*7e63c127SSorin Basca<h3>Element <code>xml</code></h3>
681*7e63c127SSorin Basca
682*7e63c127SSorin Basca<p>
683*7e63c127SSorin Basca  Create a single-file report in XML format.
684*7e63c127SSorin Basca</p>
685*7e63c127SSorin Basca
686*7e63c127SSorin Basca<table class="coverage">
687*7e63c127SSorin Basca  <thead>
688*7e63c127SSorin Basca    <tr>
689*7e63c127SSorin Basca      <td>Attribute</td>
690*7e63c127SSorin Basca      <td>Description</td>
691*7e63c127SSorin Basca      <td>Default</td>
692*7e63c127SSorin Basca    </tr>
693*7e63c127SSorin Basca  </thead>
694*7e63c127SSorin Basca  <tbody>
695*7e63c127SSorin Basca    <tr>
696*7e63c127SSorin Basca      <td><code>destfile</code></td>
697*7e63c127SSorin Basca      <td>Location to write the report file to.</td>
698*7e63c127SSorin Basca      <td><i>none (required)</i></td>
699*7e63c127SSorin Basca    </tr>
700*7e63c127SSorin Basca    <tr>
701*7e63c127SSorin Basca      <td><code>encoding</code></td>
702*7e63c127SSorin Basca      <td>Encoding of the generated XML document.</td>
703*7e63c127SSorin Basca      <td><code>UTF-8</code></td>
704*7e63c127SSorin Basca    </tr>
705*7e63c127SSorin Basca  </tbody>
706*7e63c127SSorin Basca</table>
707*7e63c127SSorin Basca
708*7e63c127SSorin Basca<h3>Element <code>csv</code></h3>
709*7e63c127SSorin Basca
710*7e63c127SSorin Basca<p>
711*7e63c127SSorin Basca  Create single-file report in CSV format.
712*7e63c127SSorin Basca</p>
713*7e63c127SSorin Basca
714*7e63c127SSorin Basca<table class="coverage">
715*7e63c127SSorin Basca  <thead>
716*7e63c127SSorin Basca    <tr>
717*7e63c127SSorin Basca      <td>Attribute</td>
718*7e63c127SSorin Basca      <td>Description</td>
719*7e63c127SSorin Basca      <td>Default</td>
720*7e63c127SSorin Basca    </tr>
721*7e63c127SSorin Basca  </thead>
722*7e63c127SSorin Basca  <tbody>
723*7e63c127SSorin Basca    <tr>
724*7e63c127SSorin Basca      <td><code>destfile</code></td>
725*7e63c127SSorin Basca      <td>Location to write the report file to.</td>
726*7e63c127SSorin Basca      <td><i>none (required)</i></td>
727*7e63c127SSorin Basca    </tr>
728*7e63c127SSorin Basca    <tr>
729*7e63c127SSorin Basca      <td><code>encoding</code></td>
730*7e63c127SSorin Basca      <td>Encoding of the generated CSV document.</td>
731*7e63c127SSorin Basca      <td><code>UTF-8</code></td>
732*7e63c127SSorin Basca    </tr>
733*7e63c127SSorin Basca  </tbody>
734*7e63c127SSorin Basca</table>
735*7e63c127SSorin Basca
736*7e63c127SSorin Basca<h3>Element <code>check</code></h3>
737*7e63c127SSorin Basca
738*7e63c127SSorin Basca<p>
739*7e63c127SSorin Basca  This report type does not actually create a report. It checks coverage
740*7e63c127SSorin Basca  counters and reports violations of configured rules. Every rule is applied to
741*7e63c127SSorin Basca  elements of a given type (class, package, bundle, etc.) and has a list of
742*7e63c127SSorin Basca  limits which are checked for every element. The following example checks that
743*7e63c127SSorin Basca  for every package the line coverage is at least 80% and no class is missed:
744*7e63c127SSorin Basca</p>
745*7e63c127SSorin Basca
746*7e63c127SSorin Basca<pre class="source lang-xml linenums">
747*7e63c127SSorin Basca&lt;check&gt;
748*7e63c127SSorin Basca    &lt;rule element="PACKAGE"&gt;
749*7e63c127SSorin Basca        &lt;limit counter="LINE" value="COVEREDRATIO" minimum="80%"/&gt;
750*7e63c127SSorin Basca        &lt;limit counter="CLASS" value="MISSEDCOUNT" maximum="0"/&gt;
751*7e63c127SSorin Basca    &lt;/rule&gt;
752*7e63c127SSorin Basca&lt;/check&gt;
753*7e63c127SSorin Basca</pre>
754*7e63c127SSorin Basca
755*7e63c127SSorin Basca<p>
756*7e63c127SSorin Basca  The <code>check</code> element has the following attributes:
757*7e63c127SSorin Basca</p>
758*7e63c127SSorin Basca
759*7e63c127SSorin Basca<table class="coverage">
760*7e63c127SSorin Basca  <thead>
761*7e63c127SSorin Basca    <tr>
762*7e63c127SSorin Basca      <td>Attribute</td>
763*7e63c127SSorin Basca      <td>Description</td>
764*7e63c127SSorin Basca      <td>Default</td>
765*7e63c127SSorin Basca    </tr>
766*7e63c127SSorin Basca  </thead>
767*7e63c127SSorin Basca  <tbody>
768*7e63c127SSorin Basca    <tr>
769*7e63c127SSorin Basca      <td><code>rules</code></td>
770*7e63c127SSorin Basca      <td>List of rules to check.</td>
771*7e63c127SSorin Basca      <td><i>none</i></td>
772*7e63c127SSorin Basca    </tr>
773*7e63c127SSorin Basca    <tr>
774*7e63c127SSorin Basca      <td><code>failonviolation</code></td>
775*7e63c127SSorin Basca      <td>Specifies whether build should fail in case of rule violations.</td>
776*7e63c127SSorin Basca      <td><code>true</code></td>
777*7e63c127SSorin Basca    </tr>
778*7e63c127SSorin Basca    <tr>
779*7e63c127SSorin Basca      <td><code>violationsproperty</code></td>
780*7e63c127SSorin Basca      <td>The name of an Ant property which is filled with the violation
781*7e63c127SSorin Basca          messages.</td>
782*7e63c127SSorin Basca      <td><i>none</i></td>
783*7e63c127SSorin Basca    </tr>
784*7e63c127SSorin Basca  </tbody>
785*7e63c127SSorin Basca</table>
786*7e63c127SSorin Basca
787*7e63c127SSorin Basca<p>
788*7e63c127SSorin Basca  Within the <code>check</code> element any number of <code>rule</code> elements
789*7e63c127SSorin Basca  can be nested:
790*7e63c127SSorin Basca</p>
791*7e63c127SSorin Basca
792*7e63c127SSorin Basca<table class="coverage">
793*7e63c127SSorin Basca  <thead>
794*7e63c127SSorin Basca    <tr>
795*7e63c127SSorin Basca      <td>Attribute</td>
796*7e63c127SSorin Basca      <td>Description</td>
797*7e63c127SSorin Basca      <td>Default</td>
798*7e63c127SSorin Basca    </tr>
799*7e63c127SSorin Basca  </thead>
800*7e63c127SSorin Basca  <tbody>
801*7e63c127SSorin Basca    <tr>
802*7e63c127SSorin Basca      <td><code>element</code></td>
803*7e63c127SSorin Basca      <td>The elements this rule applies to. Possible values are
804*7e63c127SSorin Basca          <code>BUNDLE</code>, <code>PACKAGE</code>, <code>CLASS</code>,
805*7e63c127SSorin Basca          <code>SOURCEFILE</code> and <code>METHOD</code>.</td>
806*7e63c127SSorin Basca      <td><code>BUNDLE</code></td>
807*7e63c127SSorin Basca    </tr>
808*7e63c127SSorin Basca    <tr>
809*7e63c127SSorin Basca      <td><code>includes</code></td>
810*7e63c127SSorin Basca      <td>A list of element names that should be checked. The list entries are
811*7e63c127SSorin Basca          separated by a colon (:) and may use wildcard characters (* and ?).</td>
812*7e63c127SSorin Basca      <td><code>*</code></td>
813*7e63c127SSorin Basca    </tr>
814*7e63c127SSorin Basca    <tr>
815*7e63c127SSorin Basca      <td><code>excludes</code></td>
816*7e63c127SSorin Basca      <td>A list of element names that should not be checked. The list entries
817*7e63c127SSorin Basca          are separated by a colon (:) and may use wildcard characters (* and ?).</td>
818*7e63c127SSorin Basca      <td><i>empty (no excludes)</i></td>
819*7e63c127SSorin Basca    </tr>
820*7e63c127SSorin Basca    <tr>
821*7e63c127SSorin Basca      <td><code>limits</code></td>
822*7e63c127SSorin Basca      <td>List of limits to check.</td>
823*7e63c127SSorin Basca      <td><i>none</i></td>
824*7e63c127SSorin Basca    </tr>
825*7e63c127SSorin Basca  </tbody>
826*7e63c127SSorin Basca</table>
827*7e63c127SSorin Basca
828*7e63c127SSorin Basca<p>
829*7e63c127SSorin Basca  Within the <code>rule</code> element any number of <code>limit</code> elements
830*7e63c127SSorin Basca  can be nested:
831*7e63c127SSorin Basca</p>
832*7e63c127SSorin Basca
833*7e63c127SSorin Basca<table class="coverage">
834*7e63c127SSorin Basca  <thead>
835*7e63c127SSorin Basca    <tr>
836*7e63c127SSorin Basca      <td>Attribute</td>
837*7e63c127SSorin Basca      <td>Description</td>
838*7e63c127SSorin Basca      <td>Default</td>
839*7e63c127SSorin Basca    </tr>
840*7e63c127SSorin Basca  </thead>
841*7e63c127SSorin Basca  <tbody>
842*7e63c127SSorin Basca    <tr>
843*7e63c127SSorin Basca      <td><code>counter</code></td>
844*7e63c127SSorin Basca      <td>The <a href="counters.html">counter</a> which should be checked.
845*7e63c127SSorin Basca          Possible options are <code>INSTRUCTION</code>, <code>LINE</code>,
846*7e63c127SSorin Basca          <code>BRANCH</code>, <code>COMPLEXITY</code>, <code>METHOD</code> and
847*7e63c127SSorin Basca          <code>CLASS</code>.</td>
848*7e63c127SSorin Basca      <td><code>INSTRUCTION</code></td>
849*7e63c127SSorin Basca    </tr>
850*7e63c127SSorin Basca    <tr>
851*7e63c127SSorin Basca      <td><code>value</code></td>
852*7e63c127SSorin Basca      <td>The counter value that should be checked. Possible options are
853*7e63c127SSorin Basca      <code>TOTALCOUNT</code>, <code>MISSEDCOUNT</code>,
854*7e63c127SSorin Basca      <code>COVEREDCOUNT</code>, <code>MISSEDRATIO</code> and
855*7e63c127SSorin Basca      <code>COVEREDRATIO</code>.</td>
856*7e63c127SSorin Basca      <td><code>COVEREDRATIO</code></td>
857*7e63c127SSorin Basca    </tr>
858*7e63c127SSorin Basca    <tr>
859*7e63c127SSorin Basca      <td><code>minimum</code></td>
860*7e63c127SSorin Basca      <td>Expected minimum value. If the minimum refers to a ratio it must be
861*7e63c127SSorin Basca          in the range from 0.0 to 1.0 where the number of decimal places will
862*7e63c127SSorin Basca          also determine the precision in error messages. A limit ratio may
863*7e63c127SSorin Basca          optionally be declared as a percentage where 0.80 and 80% represent
864*7e63c127SSorin Basca          the same value.</td>
865*7e63c127SSorin Basca      <td><i>none</i></td>
866*7e63c127SSorin Basca    </tr>
867*7e63c127SSorin Basca    <tr>
868*7e63c127SSorin Basca      <td><code>maximum</code></td>
869*7e63c127SSorin Basca      <td>Expected maximum value, see <code>minimum</code> for details.</td>
870*7e63c127SSorin Basca      <td><i>none</i></td>
871*7e63c127SSorin Basca    </tr>
872*7e63c127SSorin Basca  </tbody>
873*7e63c127SSorin Basca</table>
874*7e63c127SSorin Basca
875*7e63c127SSorin Basca<h2><a name="instrument">Task <code>instrument</code></a></h2>
876*7e63c127SSorin Basca
877*7e63c127SSorin Basca<p class="hint">
878*7e63c127SSorin Basca  <b>Warning:</b> The preferred way for code coverage analysis with JaCoCo is
879*7e63c127SSorin Basca  on-the-fly instrumentation. Offline instrumentation has several drawbacks and
880*7e63c127SSorin Basca  should only be used if a specific scenario explicitly requires this mode.
881*7e63c127SSorin Basca  Please consult <a href="offline.html">documentation</a> about offline
882*7e63c127SSorin Basca  instrumentation before using this mode.
883*7e63c127SSorin Basca</p>
884*7e63c127SSorin Basca
885*7e63c127SSorin Basca<p>
886*7e63c127SSorin Basca  This task is used for <a href="offline.html">offline instrumentation</a> of
887*7e63c127SSorin Basca  class files. The task takes a set of files and writes instrumented
888*7e63c127SSorin Basca  versions to a specified location. The task takes any file type as input. Java
889*7e63c127SSorin Basca  class files are instrumented. Archives (jar, war, ear etc. or Pack200) are
890*7e63c127SSorin Basca  searched recursively for class files which then get instrumented. All other
891*7e63c127SSorin Basca  files are copied without modification.
892*7e63c127SSorin Basca</p>
893*7e63c127SSorin Basca
894*7e63c127SSorin Basca<pre class="source lang-xml linenums">
895*7e63c127SSorin Basca&lt;jacoco:instrument destdir="target/classes-instr"&gt;
896*7e63c127SSorin Basca    &lt;fileset dir="target/classes" includes="**/*.class"/&gt;
897*7e63c127SSorin Basca&lt;/jacoco:instrument&gt;
898*7e63c127SSorin Basca</pre>
899*7e63c127SSorin Basca
900*7e63c127SSorin Basca<p>
901*7e63c127SSorin Basca  The task definition can contain any number of resource collection types and
902*7e63c127SSorin Basca  has the following mandatory attribute:
903*7e63c127SSorin Basca</p>
904*7e63c127SSorin Basca
905*7e63c127SSorin Basca<table class="coverage">
906*7e63c127SSorin Basca  <thead>
907*7e63c127SSorin Basca    <tr>
908*7e63c127SSorin Basca      <td>Attribute</td>
909*7e63c127SSorin Basca      <td>Description</td>
910*7e63c127SSorin Basca      <td>Default</td>
911*7e63c127SSorin Basca    </tr>
912*7e63c127SSorin Basca  </thead>
913*7e63c127SSorin Basca  <tbody>
914*7e63c127SSorin Basca    <tr>
915*7e63c127SSorin Basca      <td><code>destdir</code></td>
916*7e63c127SSorin Basca      <td>Directory location to write the instrumented files to.</td>
917*7e63c127SSorin Basca      <td><i>none (required)</i></td>
918*7e63c127SSorin Basca    </tr>
919*7e63c127SSorin Basca    <tr>
920*7e63c127SSorin Basca      <td><code>removesignatures</code></td>
921*7e63c127SSorin Basca      <td>If set to <code>true</code> all signature related information is
922*7e63c127SSorin Basca          stripped from JARs. This is typically necessary as instrumentation
923*7e63c127SSorin Basca          breaks the signatures of the original class files.</td>
924*7e63c127SSorin Basca      <td><code>true</code></td>
925*7e63c127SSorin Basca    </tr>
926*7e63c127SSorin Basca  </tbody>
927*7e63c127SSorin Basca</table>
928*7e63c127SSorin Basca
929*7e63c127SSorin Basca</div>
930*7e63c127SSorin Basca<div class="footer">
931*7e63c127SSorin Basca  <span class="right"><a href="${jacoco.home.url}">JaCoCo</a> ${qualified.bundle.version}</span>
932*7e63c127SSorin Basca  <a href="license.html">Copyright</a> &copy; ${copyright.years} Mountainminds GmbH &amp; Co. KG and Contributors
933*7e63c127SSorin Basca</div>
934*7e63c127SSorin Basca
935*7e63c127SSorin Basca</body>
936*7e63c127SSorin Basca</html>
937