Clover for Ant Best Practices

This section describes some recommended practices when integrating Clover into your Ant build. For a great list of general Ant best practices, see http://www.onjava.com/pub/a/onjava/2003/12/17/ant_bestpractices.html

1. Let Clover automatically choose the database location
   In Clover 1.x, the Clover database needed to be specified, via the initstring attribute on the <clover-setup> task. Clover 2 makes the initstring attribute optional. If not supplied, Clover will automatically create a special directory for the Clover coverage database. There are several advantages in letting Clover use the default location. Clover tasks can find the database more easily, and build files become more portable. If left to the default setting, there is no need to have Clover reporting targets depend on the the Clover setup target.

   Note

   If you want to specify the initstring explicity, it is strongly recommended that you give Clover its own direct directory, because a Coverage run can result in many files being written to the database.

2. Use the <clover-clean> task
   Once you have generated the reports or history points you require from a Coverage run, use <clover-clean> to delete the database so that it will be freshly created for the next build. This is easily achieved by adding the <clover-clean> task to any existing clean target.
3. Avoid setting the compiler or executable attributes on the <javac> task
   Setting either of these attributes makes your build less portable. It may also prevent Clover from installing correctly in your build.
4. Set the source attribute on the <javac> task
   Setting the source attribute increases the portability of your build by explicitly defining the language level of the project. If you don't set it, the language level is determined by whatever underlying compiler is found by Ant.
5. Use Target dependencies in preference to <ant> and <antcall>
   Ant's target dependencies are an efficient way to manage build dependencies. You should always strive to use this mechanism over the more 'procedural' style of explicitly calling targets. By explicitly calling Ant tasks, you miss out on Ant's powerful dependency management where up-to-date targets are skipped. You also introduce significant memory overhead (particularly if fork="true" is set). Excessive use of <antcall> can also make a build file less readable, because it can be difficult to trace which properties and references are valid for a given target.
   
   If you must use <ant> and <antcall>, be aware that you must set inheritrefs to "true" if you are calling <clover-setup> in an upper-level project.
   
   Below, we demonstrate an alternative. Instead of this:

   <!-- BAD. References wont be passed (References from <clover-setup/> would be lost). -->
   <target name="all">
   <antcall target="clean">
   <antcall target="compile">
   <antcall target="dist">
   <antcall target="test">
   </target>
   

   it is much better to use something like this:

   <!-- GOOD -->
   <target name="all" depends="clean, compile, dist, test"/>
   

6. If using the <junit> task, consider using fork="true" forkmode="once"
   Setting these attributes means that your JUnit tests will run in a single, separate JVM. This isolates the unit tests from the Ant JVM, and means that no special flushing is required to have Clover coverage data written to disk when the tests end.