Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / jacoco / ab73b7be34dfced3da8219152c075b5497c0713d / . / org.jacoco.doc / docroot / doc / ant.html
blob: 9056c96910f42a005bc63d130e9ce2bb6f366bdf [file] [log] [blame]
Marc R. Hoffmannf7d17522009-08-07 11:21:23 +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 - Ant Tasks</title>
8</head>
9<body>
10
11<div class="breadcrumb">
12 <a href="../index.html" class="el_session">JaCoCo</a> &gt;
13 <a href="index.html" class="el_group">Documentation</a> &gt;
14 <span class="el_source">Ant Tasks</span>
15</div>
16
17<h1>Ant Tasks</h1>
18
19<p>
20 JaCoCo comes with Ant tasks to launch Java programs with execution recording
21 and for creating coverage reports from the recorded data. All tasks are
22 defined in <code>jacocoant.jar</code> and can be included in your Ant scripts
23 with the usual <code>taskdef</code> declaration:
24</p>
25
26<pre class="source">
27<span class="nr"> 1</span>&lt;project name="Example" xmlns:jacoco="antlib:org.jacoco.ant"&gt;
28<span class="nr"> 2</span>
29<span class="nr"> 3</span> &lt;taskdef uri="antlib:org.jacoco.ant" resource="org/jacoco/ant/antlib.xml"&gt;
30<span class="nr"> 4</span> &lt;classpath&gt;
31<span class="nr"> 5</span> &lt;file file="<i>path_to_jacoco</i>/lib/jacocoant.jar"/&gt;
32<span class="nr"> 6</span> &lt;/classpath&gt;
33<span class="nr"> 7</span> &lt;/taskdef&gt;
34<span class="nr"> 8</span>
35<span class="nr"> 9</span> ...
36<span class="nr"> 10</span>
37<span class="nr"> 11</span>&lt;/project&gt;
38</pre>
39
40<p>
Marc R. Hoffmanndb3e7d02009-08-12 10:57:39 +0000[diff] [blame]41 Alternatively you might also place the <code>jacocoant.jar</code> in your
42 Ant <code><i>ANT_HOME</i>/lib</code> folder. If you use the name space URI
43 <code>antlib:org.jacoco.ant</code> for JaCoCo tasks Ant will find them
44 automatically without the <code>taskdef</code> declaration above.
45</p>
46
47<p>
Marc R. Hoffmannf7d17522009-08-07 11:21:23 +0000[diff] [blame]48 Declaring a XML namespace for JaCoCo tasks is optional but always recommended
49 if you mix tasks from different libraries. All subsequent examples use the
50 <code>jacoco</code> prefix declared above.
51</p>
52
53
54<h2>Task <code>coverage</code></h2>
55
56<p>
57 The standard Ant tasks to launch Java programs are <code>java</code> and
58 <code>junit</code>. To add code coverage recording to these tasks they can
59 simply be wrapped with the <code>coverage</code> task as shown in the
60 following examples:
61</p>
62
63<pre class="source">
64<span class="nr"> 1</span>&lt;jacoco:coverage>
65<span class="nr"> 2</span> &lt;java classname="org.jacoco.examples.HelloJaCoCo" fork="true"&gt;
66<span class="nr"> 3</span> &lt;classpath&gt;
67<span class="nr"> 4</span> &lt;pathelement location="./bin"/&gt;
68<span class="nr"> 5</span> &lt;/classpath&gt;
69<span class="nr"> 6</span> &lt;/java&gt;
70<span class="nr"> 7</span>&lt;/jacoco:coverage&gt;
71<span class="nr"> 8</span>
72<span class="nr"> 9</span>
73<span class="nr"> 10</span>&lt;jacoco:coverage>
74<span class="nr"> 11</span> &lt;junit fork="true" forkmode="once"&gt;
75<span class="nr"> 12</span> &lt;test name="org.jacoco.examples.HelloJaCoCoTest"/&gt;
76<span class="nr"> 13</span> &lt;classpath&gt;
77<span class="nr"> 14</span> &lt;pathelement location="./bin"/&gt;
78<span class="nr"> 15</span> &lt;/classpath&gt;
79<span class="nr"> 16</span> &lt;/junit&gt;
80<span class="nr"> 17</span>&lt;/jacoco:coverage>
81</pre>
82
83<p>
84 As a result coverage information is collected during execution and written
85 to a file when the process terminates. Note the <code>fork</code> attribute in
86 wrapped <code>java</code> task.
87</p>
88
89<p class="hint">
90 The nested task always has to declare <code>fork="true"</code>, otherwise the
91 <code>coverage</code> task can't record coverage information and will fail.
92 In addition the <code>junit</code> task should declare
93 <code>forkmode="once"</code> to avoid starting a new JVM for every single test
94 case and decreasing execution performance dramatically (unless this is
95 required by the nature of the test cases).
96</p>
97
98<p>
99 The coverage task must wrap exactly one task. While it typically works without
100 any configuration, the behavior can be adjusted with some optional attributes:
101</p>
102
103<table class="coverage">
104 <thead>
105 <tr>
106 <td>Attribute</td>
107 <td>Description</td>
108 <td>Default</td>
109 </tr>
110 </thead>
111 <tbody>
112 <tr>
113 <td><code>file</code></td>
114 <td>Path to the output file for execution data.</td>
115 <td><code>jacoco.exec</code></td>
116 </tr>
117 <tr>
118 <td><code>merge</code></td>
119 <td>If set to <code>true</code> and the execution data file already
120 exists, coverage data is merged to the existing file. If set to
121 <code>false</code>, an existing execution data file will be replaced.
122 </td>
123 <td><code>true</code></td>
124 </tr>
125 <tr>
126 <td><code>exclclassloader</code></td>
Marc R. Hoffmann2a6b5bf2009-08-11 12:54:36 +0000[diff] [blame]127 <td>A list of class loader names, that should be excluded from execution
128 analysis. The list entries are separated by a vertical bar
129 (<code>|</code>) and may use wildcard characters (<code>*</code> and
130 <code>?</code>). This option might be required in case of special
Marc R. Hoffmannf7d17522009-08-07 11:21:23 +0000[diff] [blame]131 frameworks that conflict with JaCoCo code instrumentation, e.g. class
132 loaders that do not have access to the Java runtime classes.
133 </td>
134 <td><code>sun.reflect.DelegatingClassLoader</code></td>
135 </tr>
136 </tbody>
137</table>
138
139
140<h2>Task <code>agent</code></h2>
141
Marc R. Hoffmannd519add2009-08-11 11:09:29 +0000[diff] [blame]142<p>
143 If the <code>coverage</code> task is not suitable for your launch target, you
144 might alternatively use the <code>agent</code> task to create the Java agent
145 parameter. The following example defines a Ant property with the name
146 <code>agentvmparam</code> that can be directly used as Java VM parameter:
147</p>
148
149<pre class="source">
150<span class="nr"> 1</span>&lt;jacoco:agent property="agentvmparam"/>
151</pre>
152
153<p>
154 This task has the same attributes as the <code>coverage</code> task plus an
155 additional property to specify the target property name:
156</p>
157
158<table class="coverage">
159 <thead>
160 <tr>
161 <td>Attribute</td>
162 <td>Description</td>
163 <td>Default</td>
164 </tr>
165 </thead>
166 <tbody>
167 <tr>
168 <td><code>property</code></td>
169 <td>Name of the Ant property to set.</td>
170 <td><i>none (required)</i></td>
171 </tr>
172 </tbody>
173</table>
174
Marc R. Hoffmannf7d17522009-08-07 11:21:23 +0000[diff] [blame]175<h2>Task <code>report</code></h2>
176
177
178<div class="footer">
179 <div class="versioninfo"><a href="@HOMEURL@">JaCoCo</a> @VERSION@</div>
180 <a href="license.html">Copyright</a> &copy; 2009 Mountainminds GmbH &amp; Co. KG and Contributors
181</div>
182
183</body>
184</html>