Set property svn:eol-style to native
diff --git a/org.jacoco.doc/docroot/doc/ant.html b/org.jacoco.doc/docroot/doc/ant.html
index dc3c6dd..be51247 100644
--- a/org.jacoco.doc/docroot/doc/ant.html
+++ b/org.jacoco.doc/docroot/doc/ant.html
@@ -1,687 +1,687 @@
-<?xml version="1.0" encoding="ISO-8859-1" ?>
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml" lang="en">
-<head>
- <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" />
- <link rel="stylesheet" href=".resources/doc.css" charset="ISO-8859-1" type="text/css" />
- <link rel="stylesheet" href="../coverage/.resources/prettify.css" charset="ISO-8859-1" type="text/css" />
- <link rel="shortcut icon" href=".resources/report.gif" type="image/gif" />
- <script type="text/javascript" src="../coverage/.resources/prettify.js"></script>
- <title>JaCoCo - Ant Tasks</title>
-</head>
-<body onload="prettyPrint()">
-
-<div class="breadcrumb">
- <a href="../index.html" class="el_report">JaCoCo</a> >
- <a href="index.html" class="el_group">Documentation</a> >
- <span class="el_source">Ant Tasks</span>
-</div>
-<div id="content">
-
-<h1>Ant Tasks</h1>
-
-<p>
- JaCoCo comes with Ant tasks to launch Java programs with execution recording
- and for creating coverage reports from the recorded data. Execution data can
- be collected and managed with the tasks
- <a href="#coverage"><code>coverage</code></a>,
- <a href="#agent"><code>agent</code></a>,
- <a href="#dump"><code>dump</code></a> and
- <a href="#merge"><code>merge</code></a>. Reports in different formats are
- creates with the <a href="#report"><code>report</code></a> task.
-</p>
-
-<p class="hint">
- If you want to have line number information included in the coverage reports
- or you want source code highlighting the class files of the test target must
- be compiled with debug information.
-</p>
-
-<h2>Example</h2>
-
-<p>
- The JaCoCo distribution contains a simple example how code coverage can be
- added to a Ant based build. The
- <a href="examples/ant/build.xml">build script</a> compiles Java sources, runs
- the test program and creates a coverage report. The complete example is
- located in the <code>./doc/examples/ant</code> folder of the distribution.
-</p>
-
-
-<h2>Prerequisites</h2>
-
-<p>
- The JaCoCo Ant tasks require
-</p>
-
-<ul>
- <li>Ant 1.7.0 or higher and</li>
- <li>Java 1.5 or higher (for both, the Ant runner and the test executor).</li>
-</ul>
-
-
-<p>All tasks are defined in <code>jacocoant.jar</code> (which is part of the
- distribution) and can be included in your Ant scripts with the usual
- <code>taskdef</code> declaration:
-</p>
-
-<pre class="source lang-xml linenums">
-<project name="Example" xmlns:jacoco="antlib:org.jacoco.ant">
-
- <taskdef uri="antlib:org.jacoco.ant" resource="org/jacoco/ant/antlib.xml">
- <classpath path="<i>path_to_jacoco</i>/lib/jacocoant.jar"/>
- </taskdef>
-
- ...
-
-</project>
-</pre>
-
-<p>
- Alternatively you might also place the <code>jacocoant.jar</code> in your
- Ant <code><i>ANT_HOME</i>/lib</code> folder. If you use the name space URI
- <code>antlib:org.jacoco.ant</code> for JaCoCo tasks Ant will find them
- automatically without the <code>taskdef</code> declaration above.
-</p>
-
-<p class="hint">
- Declaring a XML namespace for JaCoCo tasks is optional but always recommended
- if you mix tasks from different libraries. All subsequent examples use the
- <code>jacoco</code> prefix declared above. If you don't declare a separate
- namespace the <code>jacoco</code> prefix must be removed from the following
- examples.
-</p>
-
-<h2><a name="coverage">Task <code>coverage</code></a></h2>
-
-<p>
- The standard Ant tasks to launch Java programs are <code>java</code>, <code>junit</code> and
- <code>testng</code>. To add code coverage recording to these tasks they can
- simply be wrapped with the <code>coverage</code> task as shown in the
- following examples:
-</p>
-
-<pre class="source lang-xml linenums">
-<jacoco:coverage>
- <java classname="org.jacoco.examples.HelloJaCoCo" fork="true">
- <classpath>
- <pathelement location="./bin"/>
- </classpath>
- </java>
-</jacoco:coverage>
-
-
-<jacoco:coverage>
- <junit fork="true" forkmode="once">
- <test name="org.jacoco.examples.HelloJaCoCoTest"/>
- <classpath>
- <pathelement location="./bin"/>
- </classpath>
- </junit>
-</jacoco:coverage>
-</pre>
-
-<p>
- Resulting coverage information is collected during execution and written
- to a file when the process terminates. Note the <code>fork</code> attribute
- above in the wrapped <code>java</code> task.
-</p>
-
-<p class="hint">
- The nested task always has to declare <code>fork="true"</code>, otherwise the
- <code>coverage</code> task can't record coverage information and will fail.
- In addition the <code>junit</code> task should declare
- <code>forkmode="once"</code> to avoid starting a new JVM for every single test
- case and decreasing execution performance dramatically (unless this is
- required by the nature of the test cases).
-</p>
-
-<p>
- The coverage task must wrap exactly one task. While it typically works without
- any configuration, the behavior can be adjusted with some optional attributes:
-</p>
-
-<table class="coverage">
- <thead>
- <tr>
- <td>Attribute</td>
- <td>Description</td>
- <td>Default</td>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td><code>enabled</code></td>
- <td>If set to <code>true</code> coverage data will be collected for the contained task.</td>
- <td><code>true</code></td>
- </tr>
- <tr>
- <td><code>destfile</code></td>
- <td>Path to the output file for execution data.</td>
- <td><code>jacoco.exec</code></td>
- </tr>
- <tr>
- <td><code>append</code></td>
- <td>If set to <code>true</code> and the execution data file already
- exists, coverage data is appended to the existing file. If set to
- <code>false</code>, an existing execution data file will be replaced.
- </td>
- <td><code>true</code></td>
- </tr>
- <tr>
- <td><code>includes</code></td>
- <td>A list of class names that should be included in execution analysis.
- The list entries are separated by a colon (<code>:</code>) and
- may use wildcard characters (<code>*</code> and <code>?</code>).
- Except for performance optimization or technical corner cases this
- option is normally not required.
- </td>
- <td><code>*</code> (all classes)</td>
- </tr>
- <tr>
- <td><code>excludes</code></td>
- <td>A list of class names that should be excluded from execution analysis.
- The list entries are separated by a colon (<code>:</code>) and
- may use wildcard characters (<code>*</code> and <code>?</code>).
- Except for performance optimization or technical corner cases this
- option is normally not required.
- </td>
- <td><i>empty</i> (no excluded classes)</td>
- </tr>
- <tr>
- <td><code>exclclassloader</code></td>
- <td>A list of class loader names, that should be excluded from execution
- analysis. The list entries are separated by a colon
- (<code>:</code>) and may use wildcard characters (<code>*</code> and
- <code>?</code>). This option might be required in case of special
- frameworks that conflict with JaCoCo code instrumentation, in
- particular class loaders that do not have access to the Java runtime
- classes.
- </td>
- <td><code>sun.reflect.DelegatingClassLoader</code></td>
- </tr>
- <tr>
- <td><code>sessionid</code></td>
- <td>A session identifier that is written with the execution data. Without
- this parameter a random identifier is created by the agent.
- </td>
- <td><i>auto-generated</i></td>
- </tr>
- <tr>
- <td><code>dumponexit</code></td>
- <td>If set to <code>true</code> coverage data will be written on VM
- shutdown.
- </td>
- <td><code>true</code></td>
- </tr>
- <tr>
- <td><code>output</code></td>
- <td>Output method to use for writing coverage data. Valid options are:
- <ul>
- <li><code>file</code>: At VM termination execution data is written to
- the file specified in the <code>destfile</code> attribute.</li>
- <li><code>tcpserver</code>: The agent listens for incoming connections
- on the TCP port specified by the <code>address</code> and
- <code>port</code> attribute. Execution data is written to this
- TCP connection.</li>
- <li><code>tcpclient</code>: At startup the agent connects to the TCP
- port specified by the <code>address</code> and <code>port</code>
- attribute. Execution data is written to this TCP connection.</li>
- <li><code>mbean</code>: The agent registers an JMX MBean under the
- name <code>org.jacoco:type=Runtime</code>.</li>
- </ul>
- </td>
- <td><code>file</code></td>
- </tr>
- <tr>
- <td><code>address</code></td>
- <td>IP address or hostname to bind to when the output method is
- <code>tcpserver</code> or connect to when the output method is
- <code>tcpclient</code>. In <code>tcpserver</code> mode the value
- "<code>*</code>" causes the agent to accept connections on any local
- address.
- </td>
- <td><i>loopback interface</i></td>
- </tr>
- <tr>
- <td><code>port</code></td>
- <td>Port to bind to when the output method is <code>tcpserver</code> or
- connect to when the output method is <code>tcpclient</code>. In
- <code>tcpserver</code> mode the port must be available, which means
- that if multiple JaCoCo agents should run on the same machine,
- different ports have to be specified.
- </td>
- <td><code>6300</code></td>
- </tr>
- </tbody>
-</table>
-
-
-<h2><a name="agent">Task <code>agent</code></a></h2>
-
-<p>
- If the <code>coverage</code> task is not suitable for your launch target, you
- might alternatively use the <code>agent</code> task to create the
- <a href="agent.html">Java agent</a> parameter. The following example defines a
- Ant property with the name <code>agentvmparam</code> that can be directly used
- as a Java VM parameter:
-</p>
-
-<pre class="source lang-xml linenums">
-<jacoco:agent property="agentvmparam"/>
-</pre>
-
-<p>
- This task has the same attributes as the <code>coverage</code> task plus an
- additional property to specify the target property name:
-</p>
-
-<table class="coverage">
- <thead>
- <tr>
- <td>Attribute</td>
- <td>Description</td>
- <td>Default</td>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td><code>enabled</code></td>
- <td>When this variable is set to <code>false</code> the value of <code>property</code> will be set to an empty string, effectively
- disabling coverage instrumentation for any tasks that used the value.</td>
- <td><code>true</code></td>
- </tr>
- <tr>
- <td><code>property</code></td>
- <td>Name of the Ant property to set.</td>
- <td><i>none (required)</i></td>
- </tr>
- <tr>
- <td colspan="3"><i>All attributes of the <code>coverage</code> task.</i></td>
- </tr>
- </tbody>
-</table>
-
-
-<h2><a name="dump">Task <code>dump</code></a></h2>
-
-<p>
- This task allows to remotely collect execution data from another JVM without
- stopping it. For example:
-</p>
-
-<pre class="source lang-xml linenums">
-<jacoco:dump address="server.example.com" reset="true" destfile="remote.exec"/>
-</pre>
-
-<p>
- Remote dumps are usefull for long running Java processes like application
- servers.
-</p>
-
-<p class="hint">
- The target JVM needs to have a <a href="agent.html">JaCoCo agent</a>
- configured with <code>output</code> mode <code>tcpserver</code>. See
- <a href="#coverage"><code>coverage</code></a> and
- <a href="#agent"><code>agent</code></a> tasks above.
-</p>
-
-<p>
- The <code>dump</code> task has the following attributes:
-</p>
-
-<table class="coverage">
- <thead>
- <tr>
- <td>Attribute</td>
- <td>Description</td>
- <td>Default</td>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td><code>address</code></td>
- <td>Target IP address or DNS name.</td>
- <td><code>localhost</code></td>
- </tr>
- <tr>
- <td><code>port</code></td>
- <td>Target TCP port.</td>
- <td><code>6300</code></td>
- </tr>
- <tr>
- <td><code>dump</code></td>
- <td>Flag whether execution data should be dumped.</td>
- <td><code>true</code></td>
- </tr>
- <tr>
- <td><code>reset</code></td>
- <td>Flag whether execution data should be reset in the target agent after
- the dump.</td>
- <td><code>false</code></td>
- </tr>
- <tr>
- <td><code>destfile</code></td>
- <td>File location to write the collected execution data to.</td>
- <td><i>none (required if dump=true)</i></td>
- </tr>
- <tr>
- <td><code>append</code></td>
- <td>If set to <code>true</code> and the execution data file already
- exists, coverage data is appended to the existing file. If set to
- <code>false</code>, an existing execution data file will be replaced.
- </td>
- <td><code>true</code></td>
- </tr>
- </tbody>
-</table>
-
-
-<h2><a name="merge">Task <code>merge</code></a></h2>
-
-<p>
- This task can be used to merge the execution data from multiple test runs
- into a single data store.
-</p>
-
-<pre class="source lang-xml linenums">
-<jacoco:merge destfile="merged.exec">
- <fileset dir="executionData" includes="*.exec"/>
-</jacoco:merge>
-</pre>
-
-<p>
- The task definition can contain any number of resource collection types and
- has the following mandatory attribute:
-</p>
-
-<table class="coverage">
- <thead>
- <tr>
- <td>Attribute</td>
- <td>Description</td>
- <td>Default</td>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td><code>destfile</code></td>
- <td>File location to write the merged execution data to.</td>
- <td><i>none (required)</i></td>
- </tr>
- </tbody>
-</table>
-
-
-<h2><a name="report">Task <code>report</code></a></h2>
-
-<p>
- Finally different reports can be created with the <code>report</code> task.
- A report task declaration consists of different sections, two specify the
- input data, additional ones specify the output formats:
-</p>
-
-<pre class="source lang-xml linenums">
-<jacoco:report>
-
- <executiondata>
- <file file="jacoco.exec"/>
- </executiondata>
-
- <structure name="Example Project">
- <classfiles>
- <fileset dir="classes"/>
- </classfiles>
- <sourcefiles encoding="UTF-8">
- <fileset dir="src"/>
- </sourcefiles>
- </structure>
-
- <html destdir="report"/>
-
-</jacoco:report>
-</pre>
-
-<p>
- As you can see from the example above the <code>report</code> task is based
- on several nested elements:
-</p>
-
-<h3>Element <code>executiondata</code></h3>
-
-<p>
- Within this element Ant resources and resource collections can be specified,
- that represent JaCoCo execution data files. If more than one execution data
- file is specified, execution data is combined. A particular piece of code is
- considered executed when it is marked as such in any of the input files.
-</p>
-
-<h3>Element <code>structure</code></h3>
-
-<p>
- This element defines the report structure. It might contain the following
- nested elements:
-</p>
-
-<ul>
- <li><code>classfiles</code>: Container element for Ant resources and resource
- collections that can specify Java class files, ZIP archive files (jar, war,
- ear etc.) or folders containing class files. Archives and folders are
- searched recursively for class files.</li>
- <li><code>sourcefiles</code>: Optional container element for Ant resources and
- resource collections that specify corresponding source files. If source
- files are specified, some report formats include highlighted source code.</li>
-</ul>
-
-<p>
- The <code>sourcefiles</code> element has these optional attributes:
-</p>
-
-<table class="coverage">
- <thead>
- <tr>
- <td>Attribute</td>
- <td>Description</td>
- <td>Default</td>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td><code>encoding</code></td>
- <td>Character encoding of the source files.</td>
- <td>Platform default encoding</td>
- </tr>
- <tr>
- <td><code>tabwidth</code></td>
- <td>Number of whitespace characters that represent a tab character.</td>
- <td>4 characters</td>
- </tr>
- </tbody>
-</table>
-
-<p>
- Note that the <code>classfiles</code> and <code>sourcefiles</code> elements
- accept any
- <a href="http://ant.apache.org/manual/Types/resources.html#collection">Ant
- resource collection</a>. Therefore also filtering the class file set is
- possible and allows to narrow the scope of the report, for example:
-</p>
-
-<pre class="source lang-xml linenums">
-<classfiles>
- <fileset dir="classes">
- <include name="org/jacoco/examples/important/**/*.class"/>
- </fileset>
-</classfiles>
-</pre>
-
-<p class="hint">
- <b>Performance Warning:</b> Although it is technically possible and sometimes
- convenient to use Ant's <code>zipfileset</code> to specify class or source
- files, this resource type has poor performance characteristics and comes with
- an huge memory overhead especially for large scale projects.
-</p>
-
-<p>
- The structure can be refined with a hierarchy of <code>group</code> elements.
- This way the coverage report can reflect different modules of a software
- project. For each group element the corresponding class and source files can
- be specified separately. For example:
-</p>
-
-<pre class="source lang-xml linenums">
-<structure name="Example Project">
- <group name="Server">
- <classfiles>
- <fileset dir="${workspace.dir}/org.jacoco.example.server/classes"/>
- </classfiles>
- <sourcefiles>
- <fileset dir="${workspace.dir}/org.jacoco.example.server/src"/>
- </sourcefiles>
- </group>
- <group name="Client">
- <classfiles>
- <fileset dir="${workspace.dir}/org.jacoco.example.client/classes"/>
- </classfiles>
- <sourcefiles>
- <fileset dir="${workspace.dir}/org.jacoco.example.client/src"/>
- </sourcefiles>
- </group>
-
- ...
-
-</structure>
-</pre>
-
-<p>
- Both <code>structure</code> and <code>group</code> elements have the following
- mandatory attribute:
-</p>
-
-<table class="coverage">
- <thead>
- <tr>
- <td>Attribute</td>
- <td>Description</td>
- <td>Default</td>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td><code>name</code></td>
- <td>Name of the structure or group.</td>
- <td><i>none (required)</i></td>
- </tr>
- </tbody>
-</table>
-
-<h3>Element <code>html</code></h3>
-
-<p>
- Create a multi-page report in HTML format. The report can either be written as
- multiple files into a directory or compressed into a single ZIP file.
-</p>
-
-<table class="coverage">
- <thead>
- <tr>
- <td>Attribute</td>
- <td>Description</td>
- <td>Default</td>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td><code>destdir</code></td>
- <td>Directory to create the report in. Either this property or
- <code>destfile</code> has to be supplied.</td>
- <td><i>none (required)</i></td>
- </tr>
- <tr>
- <td><code>destfile</code></td>
- <td>Zip file to create the report in. Either this property or
- <code>destdir</code> has to be supplied.</td>
- <td><i>none (required)</i></td>
- </tr>
- <tr>
- <td><code>footer</code></td>
- <td>Footer text for each report page.</td>
- <td><i>no footer</i></td>
- </tr>
- <tr>
- <td><code>encoding</code></td>
- <td>Character encoding of generated HTML pages.</td>
- <td><code>UTF-8</code></td>
- </tr>
- <tr>
- <td><code>locale</code></td>
- <td>Locale specified as ISO code (en, fr, jp, ...) used for number formating.</td>
- <td><i>platform locale</i></td>
- </tr>
- </tbody>
-</table>
-
-<h3>Element <code>xml</code></h3>
-
-<p>
- Create a single-file report in XML format.
-</p>
-
-<table class="coverage">
- <thead>
- <tr>
- <td>Attribute</td>
- <td>Description</td>
- <td>Default</td>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td><code>destfile</code></td>
- <td>Location to write the report file to.</td>
- <td><i>none (required)</i></td>
- </tr>
- <tr>
- <td><code>encoding</code></td>
- <td>Encoding of the generated XML document.</td>
- <td><code>UTF-8</code></td>
- </tr>
- </tbody>
-</table>
-
-<h3>Element <code>csv</code></h3>
-
-<p>
- Create single-file report in CSV format.
-</p>
-
-<table class="coverage">
- <thead>
- <tr>
- <td>Attribute</td>
- <td>Description</td>
- <td>Default</td>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td><code>destfile</code></td>
- <td>Location to write the report file to.</td>
- <td><i>none (required)</i></td>
- </tr>
- <tr>
- <td><code>encoding</code></td>
- <td>Encoding of the generated CSV document.</td>
- <td><code>UTF-8</code></td>
- </tr>
- </tbody>
-</table>
-
-</div>
-<div class="footer">
- <span class="right"><a href="@jacoco.home.url@">JaCoCo</a> @qualified.bundle.version@</span>
- <a href="license.html">Copyright</a> © @copyright.years@ Mountainminds GmbH & Co. KG and Contributors
-</div>
-
-</body>
-</html>
\ No newline at end of file
+<?xml version="1.0" encoding="ISO-8859-1" ?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" lang="en">
+<head>
+ <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" />
+ <link rel="stylesheet" href=".resources/doc.css" charset="ISO-8859-1" type="text/css" />
+ <link rel="stylesheet" href="../coverage/.resources/prettify.css" charset="ISO-8859-1" type="text/css" />
+ <link rel="shortcut icon" href=".resources/report.gif" type="image/gif" />
+ <script type="text/javascript" src="../coverage/.resources/prettify.js"></script>
+ <title>JaCoCo - Ant Tasks</title>
+</head>
+<body onload="prettyPrint()">
+
+<div class="breadcrumb">
+ <a href="../index.html" class="el_report">JaCoCo</a> >
+ <a href="index.html" class="el_group">Documentation</a> >
+ <span class="el_source">Ant Tasks</span>
+</div>
+<div id="content">
+
+<h1>Ant Tasks</h1>
+
+<p>
+ JaCoCo comes with Ant tasks to launch Java programs with execution recording
+ and for creating coverage reports from the recorded data. Execution data can
+ be collected and managed with the tasks
+ <a href="#coverage"><code>coverage</code></a>,
+ <a href="#agent"><code>agent</code></a>,
+ <a href="#dump"><code>dump</code></a> and
+ <a href="#merge"><code>merge</code></a>. Reports in different formats are
+ creates with the <a href="#report"><code>report</code></a> task.
+</p>
+
+<p class="hint">
+ If you want to have line number information included in the coverage reports
+ or you want source code highlighting the class files of the test target must
+ be compiled with debug information.
+</p>
+
+<h2>Example</h2>
+
+<p>
+ The JaCoCo distribution contains a simple example how code coverage can be
+ added to a Ant based build. The
+ <a href="examples/ant/build.xml">build script</a> compiles Java sources, runs
+ the test program and creates a coverage report. The complete example is
+ located in the <code>./doc/examples/ant</code> folder of the distribution.
+</p>
+
+
+<h2>Prerequisites</h2>
+
+<p>
+ The JaCoCo Ant tasks require
+</p>
+
+<ul>
+ <li>Ant 1.7.0 or higher and</li>
+ <li>Java 1.5 or higher (for both, the Ant runner and the test executor).</li>
+</ul>
+
+
+<p>All tasks are defined in <code>jacocoant.jar</code> (which is part of the
+ distribution) and can be included in your Ant scripts with the usual
+ <code>taskdef</code> declaration:
+</p>
+
+<pre class="source lang-xml linenums">
+<project name="Example" xmlns:jacoco="antlib:org.jacoco.ant">
+
+ <taskdef uri="antlib:org.jacoco.ant" resource="org/jacoco/ant/antlib.xml">
+ <classpath path="<i>path_to_jacoco</i>/lib/jacocoant.jar"/>
+ </taskdef>
+
+ ...
+
+</project>
+</pre>
+
+<p>
+ Alternatively you might also place the <code>jacocoant.jar</code> in your
+ Ant <code><i>ANT_HOME</i>/lib</code> folder. If you use the name space URI
+ <code>antlib:org.jacoco.ant</code> for JaCoCo tasks Ant will find them
+ automatically without the <code>taskdef</code> declaration above.
+</p>
+
+<p class="hint">
+ Declaring a XML namespace for JaCoCo tasks is optional but always recommended
+ if you mix tasks from different libraries. All subsequent examples use the
+ <code>jacoco</code> prefix declared above. If you don't declare a separate
+ namespace the <code>jacoco</code> prefix must be removed from the following
+ examples.
+</p>
+
+<h2><a name="coverage">Task <code>coverage</code></a></h2>
+
+<p>
+ The standard Ant tasks to launch Java programs are <code>java</code>, <code>junit</code> and
+ <code>testng</code>. To add code coverage recording to these tasks they can
+ simply be wrapped with the <code>coverage</code> task as shown in the
+ following examples:
+</p>
+
+<pre class="source lang-xml linenums">
+<jacoco:coverage>
+ <java classname="org.jacoco.examples.HelloJaCoCo" fork="true">
+ <classpath>
+ <pathelement location="./bin"/>
+ </classpath>
+ </java>
+</jacoco:coverage>
+
+
+<jacoco:coverage>
+ <junit fork="true" forkmode="once">
+ <test name="org.jacoco.examples.HelloJaCoCoTest"/>
+ <classpath>
+ <pathelement location="./bin"/>
+ </classpath>
+ </junit>
+</jacoco:coverage>
+</pre>
+
+<p>
+ Resulting coverage information is collected during execution and written
+ to a file when the process terminates. Note the <code>fork</code> attribute
+ above in the wrapped <code>java</code> task.
+</p>
+
+<p class="hint">
+ The nested task always has to declare <code>fork="true"</code>, otherwise the
+ <code>coverage</code> task can't record coverage information and will fail.
+ In addition the <code>junit</code> task should declare
+ <code>forkmode="once"</code> to avoid starting a new JVM for every single test
+ case and decreasing execution performance dramatically (unless this is
+ required by the nature of the test cases).
+</p>
+
+<p>
+ The coverage task must wrap exactly one task. While it typically works without
+ any configuration, the behavior can be adjusted with some optional attributes:
+</p>
+
+<table class="coverage">
+ <thead>
+ <tr>
+ <td>Attribute</td>
+ <td>Description</td>
+ <td>Default</td>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td><code>enabled</code></td>
+ <td>If set to <code>true</code> coverage data will be collected for the contained task.</td>
+ <td><code>true</code></td>
+ </tr>
+ <tr>
+ <td><code>destfile</code></td>
+ <td>Path to the output file for execution data.</td>
+ <td><code>jacoco.exec</code></td>
+ </tr>
+ <tr>
+ <td><code>append</code></td>
+ <td>If set to <code>true</code> and the execution data file already
+ exists, coverage data is appended to the existing file. If set to
+ <code>false</code>, an existing execution data file will be replaced.
+ </td>
+ <td><code>true</code></td>
+ </tr>
+ <tr>
+ <td><code>includes</code></td>
+ <td>A list of class names that should be included in execution analysis.
+ The list entries are separated by a colon (<code>:</code>) and
+ may use wildcard characters (<code>*</code> and <code>?</code>).
+ Except for performance optimization or technical corner cases this
+ option is normally not required.
+ </td>
+ <td><code>*</code> (all classes)</td>
+ </tr>
+ <tr>
+ <td><code>excludes</code></td>
+ <td>A list of class names that should be excluded from execution analysis.
+ The list entries are separated by a colon (<code>:</code>) and
+ may use wildcard characters (<code>*</code> and <code>?</code>).
+ Except for performance optimization or technical corner cases this
+ option is normally not required.
+ </td>
+ <td><i>empty</i> (no excluded classes)</td>
+ </tr>
+ <tr>
+ <td><code>exclclassloader</code></td>
+ <td>A list of class loader names, that should be excluded from execution
+ analysis. The list entries are separated by a colon
+ (<code>:</code>) and may use wildcard characters (<code>*</code> and
+ <code>?</code>). This option might be required in case of special
+ frameworks that conflict with JaCoCo code instrumentation, in
+ particular class loaders that do not have access to the Java runtime
+ classes.
+ </td>
+ <td><code>sun.reflect.DelegatingClassLoader</code></td>
+ </tr>
+ <tr>
+ <td><code>sessionid</code></td>
+ <td>A session identifier that is written with the execution data. Without
+ this parameter a random identifier is created by the agent.
+ </td>
+ <td><i>auto-generated</i></td>
+ </tr>
+ <tr>
+ <td><code>dumponexit</code></td>
+ <td>If set to <code>true</code> coverage data will be written on VM
+ shutdown.
+ </td>
+ <td><code>true</code></td>
+ </tr>
+ <tr>
+ <td><code>output</code></td>
+ <td>Output method to use for writing coverage data. Valid options are:
+ <ul>
+ <li><code>file</code>: At VM termination execution data is written to
+ the file specified in the <code>destfile</code> attribute.</li>
+ <li><code>tcpserver</code>: The agent listens for incoming connections
+ on the TCP port specified by the <code>address</code> and
+ <code>port</code> attribute. Execution data is written to this
+ TCP connection.</li>
+ <li><code>tcpclient</code>: At startup the agent connects to the TCP
+ port specified by the <code>address</code> and <code>port</code>
+ attribute. Execution data is written to this TCP connection.</li>
+ <li><code>mbean</code>: The agent registers an JMX MBean under the
+ name <code>org.jacoco:type=Runtime</code>.</li>
+ </ul>
+ </td>
+ <td><code>file</code></td>
+ </tr>
+ <tr>
+ <td><code>address</code></td>
+ <td>IP address or hostname to bind to when the output method is
+ <code>tcpserver</code> or connect to when the output method is
+ <code>tcpclient</code>. In <code>tcpserver</code> mode the value
+ "<code>*</code>" causes the agent to accept connections on any local
+ address.
+ </td>
+ <td><i>loopback interface</i></td>
+ </tr>
+ <tr>
+ <td><code>port</code></td>
+ <td>Port to bind to when the output method is <code>tcpserver</code> or
+ connect to when the output method is <code>tcpclient</code>. In
+ <code>tcpserver</code> mode the port must be available, which means
+ that if multiple JaCoCo agents should run on the same machine,
+ different ports have to be specified.
+ </td>
+ <td><code>6300</code></td>
+ </tr>
+ </tbody>
+</table>
+
+
+<h2><a name="agent">Task <code>agent</code></a></h2>
+
+<p>
+ If the <code>coverage</code> task is not suitable for your launch target, you
+ might alternatively use the <code>agent</code> task to create the
+ <a href="agent.html">Java agent</a> parameter. The following example defines a
+ Ant property with the name <code>agentvmparam</code> that can be directly used
+ as a Java VM parameter:
+</p>
+
+<pre class="source lang-xml linenums">
+<jacoco:agent property="agentvmparam"/>
+</pre>
+
+<p>
+ This task has the same attributes as the <code>coverage</code> task plus an
+ additional property to specify the target property name:
+</p>
+
+<table class="coverage">
+ <thead>
+ <tr>
+ <td>Attribute</td>
+ <td>Description</td>
+ <td>Default</td>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td><code>enabled</code></td>
+ <td>When this variable is set to <code>false</code> the value of <code>property</code> will be set to an empty string, effectively
+ disabling coverage instrumentation for any tasks that used the value.</td>
+ <td><code>true</code></td>
+ </tr>
+ <tr>
+ <td><code>property</code></td>
+ <td>Name of the Ant property to set.</td>
+ <td><i>none (required)</i></td>
+ </tr>
+ <tr>
+ <td colspan="3"><i>All attributes of the <code>coverage</code> task.</i></td>
+ </tr>
+ </tbody>
+</table>
+
+
+<h2><a name="dump">Task <code>dump</code></a></h2>
+
+<p>
+ This task allows to remotely collect execution data from another JVM without
+ stopping it. For example:
+</p>
+
+<pre class="source lang-xml linenums">
+<jacoco:dump address="server.example.com" reset="true" destfile="remote.exec"/>
+</pre>
+
+<p>
+ Remote dumps are usefull for long running Java processes like application
+ servers.
+</p>
+
+<p class="hint">
+ The target JVM needs to have a <a href="agent.html">JaCoCo agent</a>
+ configured with <code>output</code> mode <code>tcpserver</code>. See
+ <a href="#coverage"><code>coverage</code></a> and
+ <a href="#agent"><code>agent</code></a> tasks above.
+</p>
+
+<p>
+ The <code>dump</code> task has the following attributes:
+</p>
+
+<table class="coverage">
+ <thead>
+ <tr>
+ <td>Attribute</td>
+ <td>Description</td>
+ <td>Default</td>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td><code>address</code></td>
+ <td>Target IP address or DNS name.</td>
+ <td><code>localhost</code></td>
+ </tr>
+ <tr>
+ <td><code>port</code></td>
+ <td>Target TCP port.</td>
+ <td><code>6300</code></td>
+ </tr>
+ <tr>
+ <td><code>dump</code></td>
+ <td>Flag whether execution data should be dumped.</td>
+ <td><code>true</code></td>
+ </tr>
+ <tr>
+ <td><code>reset</code></td>
+ <td>Flag whether execution data should be reset in the target agent after
+ the dump.</td>
+ <td><code>false</code></td>
+ </tr>
+ <tr>
+ <td><code>destfile</code></td>
+ <td>File location to write the collected execution data to.</td>
+ <td><i>none (required if dump=true)</i></td>
+ </tr>
+ <tr>
+ <td><code>append</code></td>
+ <td>If set to <code>true</code> and the execution data file already
+ exists, coverage data is appended to the existing file. If set to
+ <code>false</code>, an existing execution data file will be replaced.
+ </td>
+ <td><code>true</code></td>
+ </tr>
+ </tbody>
+</table>
+
+
+<h2><a name="merge">Task <code>merge</code></a></h2>
+
+<p>
+ This task can be used to merge the execution data from multiple test runs
+ into a single data store.
+</p>
+
+<pre class="source lang-xml linenums">
+<jacoco:merge destfile="merged.exec">
+ <fileset dir="executionData" includes="*.exec"/>
+</jacoco:merge>
+</pre>
+
+<p>
+ The task definition can contain any number of resource collection types and
+ has the following mandatory attribute:
+</p>
+
+<table class="coverage">
+ <thead>
+ <tr>
+ <td>Attribute</td>
+ <td>Description</td>
+ <td>Default</td>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td><code>destfile</code></td>
+ <td>File location to write the merged execution data to.</td>
+ <td><i>none (required)</i></td>
+ </tr>
+ </tbody>
+</table>
+
+
+<h2><a name="report">Task <code>report</code></a></h2>
+
+<p>
+ Finally different reports can be created with the <code>report</code> task.
+ A report task declaration consists of different sections, two specify the
+ input data, additional ones specify the output formats:
+</p>
+
+<pre class="source lang-xml linenums">
+<jacoco:report>
+
+ <executiondata>
+ <file file="jacoco.exec"/>
+ </executiondata>
+
+ <structure name="Example Project">
+ <classfiles>
+ <fileset dir="classes"/>
+ </classfiles>
+ <sourcefiles encoding="UTF-8">
+ <fileset dir="src"/>
+ </sourcefiles>
+ </structure>
+
+ <html destdir="report"/>
+
+</jacoco:report>
+</pre>
+
+<p>
+ As you can see from the example above the <code>report</code> task is based
+ on several nested elements:
+</p>
+
+<h3>Element <code>executiondata</code></h3>
+
+<p>
+ Within this element Ant resources and resource collections can be specified,
+ that represent JaCoCo execution data files. If more than one execution data
+ file is specified, execution data is combined. A particular piece of code is
+ considered executed when it is marked as such in any of the input files.
+</p>
+
+<h3>Element <code>structure</code></h3>
+
+<p>
+ This element defines the report structure. It might contain the following
+ nested elements:
+</p>
+
+<ul>
+ <li><code>classfiles</code>: Container element for Ant resources and resource
+ collections that can specify Java class files, ZIP archive files (jar, war,
+ ear etc.) or folders containing class files. Archives and folders are
+ searched recursively for class files.</li>
+ <li><code>sourcefiles</code>: Optional container element for Ant resources and
+ resource collections that specify corresponding source files. If source
+ files are specified, some report formats include highlighted source code.</li>
+</ul>
+
+<p>
+ The <code>sourcefiles</code> element has these optional attributes:
+</p>
+
+<table class="coverage">
+ <thead>
+ <tr>
+ <td>Attribute</td>
+ <td>Description</td>
+ <td>Default</td>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td><code>encoding</code></td>
+ <td>Character encoding of the source files.</td>
+ <td>Platform default encoding</td>
+ </tr>
+ <tr>
+ <td><code>tabwidth</code></td>
+ <td>Number of whitespace characters that represent a tab character.</td>
+ <td>4 characters</td>
+ </tr>
+ </tbody>
+</table>
+
+<p>
+ Note that the <code>classfiles</code> and <code>sourcefiles</code> elements
+ accept any
+ <a href="http://ant.apache.org/manual/Types/resources.html#collection">Ant
+ resource collection</a>. Therefore also filtering the class file set is
+ possible and allows to narrow the scope of the report, for example:
+</p>
+
+<pre class="source lang-xml linenums">
+<classfiles>
+ <fileset dir="classes">
+ <include name="org/jacoco/examples/important/**/*.class"/>
+ </fileset>
+</classfiles>
+</pre>
+
+<p class="hint">
+ <b>Performance Warning:</b> Although it is technically possible and sometimes
+ convenient to use Ant's <code>zipfileset</code> to specify class or source
+ files, this resource type has poor performance characteristics and comes with
+ an huge memory overhead especially for large scale projects.
+</p>
+
+<p>
+ The structure can be refined with a hierarchy of <code>group</code> elements.
+ This way the coverage report can reflect different modules of a software
+ project. For each group element the corresponding class and source files can
+ be specified separately. For example:
+</p>
+
+<pre class="source lang-xml linenums">
+<structure name="Example Project">
+ <group name="Server">
+ <classfiles>
+ <fileset dir="${workspace.dir}/org.jacoco.example.server/classes"/>
+ </classfiles>
+ <sourcefiles>
+ <fileset dir="${workspace.dir}/org.jacoco.example.server/src"/>
+ </sourcefiles>
+ </group>
+ <group name="Client">
+ <classfiles>
+ <fileset dir="${workspace.dir}/org.jacoco.example.client/classes"/>
+ </classfiles>
+ <sourcefiles>
+ <fileset dir="${workspace.dir}/org.jacoco.example.client/src"/>
+ </sourcefiles>
+ </group>
+
+ ...
+
+</structure>
+</pre>
+
+<p>
+ Both <code>structure</code> and <code>group</code> elements have the following
+ mandatory attribute:
+</p>
+
+<table class="coverage">
+ <thead>
+ <tr>
+ <td>Attribute</td>
+ <td>Description</td>
+ <td>Default</td>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td><code>name</code></td>
+ <td>Name of the structure or group.</td>
+ <td><i>none (required)</i></td>
+ </tr>
+ </tbody>
+</table>
+
+<h3>Element <code>html</code></h3>
+
+<p>
+ Create a multi-page report in HTML format. The report can either be written as
+ multiple files into a directory or compressed into a single ZIP file.
+</p>
+
+<table class="coverage">
+ <thead>
+ <tr>
+ <td>Attribute</td>
+ <td>Description</td>
+ <td>Default</td>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td><code>destdir</code></td>
+ <td>Directory to create the report in. Either this property or
+ <code>destfile</code> has to be supplied.</td>
+ <td><i>none (required)</i></td>
+ </tr>
+ <tr>
+ <td><code>destfile</code></td>
+ <td>Zip file to create the report in. Either this property or
+ <code>destdir</code> has to be supplied.</td>
+ <td><i>none (required)</i></td>
+ </tr>
+ <tr>
+ <td><code>footer</code></td>
+ <td>Footer text for each report page.</td>
+ <td><i>no footer</i></td>
+ </tr>
+ <tr>
+ <td><code>encoding</code></td>
+ <td>Character encoding of generated HTML pages.</td>
+ <td><code>UTF-8</code></td>
+ </tr>
+ <tr>
+ <td><code>locale</code></td>
+ <td>Locale specified as ISO code (en, fr, jp, ...) used for number formating.</td>
+ <td><i>platform locale</i></td>
+ </tr>
+ </tbody>
+</table>
+
+<h3>Element <code>xml</code></h3>
+
+<p>
+ Create a single-file report in XML format.
+</p>
+
+<table class="coverage">
+ <thead>
+ <tr>
+ <td>Attribute</td>
+ <td>Description</td>
+ <td>Default</td>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td><code>destfile</code></td>
+ <td>Location to write the report file to.</td>
+ <td><i>none (required)</i></td>
+ </tr>
+ <tr>
+ <td><code>encoding</code></td>
+ <td>Encoding of the generated XML document.</td>
+ <td><code>UTF-8</code></td>
+ </tr>
+ </tbody>
+</table>
+
+<h3>Element <code>csv</code></h3>
+
+<p>
+ Create single-file report in CSV format.
+</p>
+
+<table class="coverage">
+ <thead>
+ <tr>
+ <td>Attribute</td>
+ <td>Description</td>
+ <td>Default</td>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td><code>destfile</code></td>
+ <td>Location to write the report file to.</td>
+ <td><i>none (required)</i></td>
+ </tr>
+ <tr>
+ <td><code>encoding</code></td>
+ <td>Encoding of the generated CSV document.</td>
+ <td><code>UTF-8</code></td>
+ </tr>
+ </tbody>
+</table>
+
+</div>
+<div class="footer">
+ <span class="right"><a href="@jacoco.home.url@">JaCoCo</a> @qualified.bundle.version@</span>
+ <a href="license.html">Copyright</a> © @copyright.years@ Mountainminds GmbH & Co. KG and Contributors
+</div>
+
+</body>
+</html>