Build

The JaCoCo build is fully based on Apache Ant. The build can be locally executed on every machine with a proper environment setup. Basically the specified third party libraries and a proper JDK version have to be available. Total build time is typically around 1 minute. Developers are encouraged to run the build frequently to ensure consistency of the source tree.

Running the Build

The build can be started by executing the build file org.jacoco.build/build.xml with org.jacoco.build/ as the working directory. From Eclipse simply right-click the build.xml file and select Run As → Ant Build... The only mandatory property that has to be provided is target.plugins.dir, the location of the folder that contains the target bundles.

The following build targets can be selected:

Target Description
clean Delete all build artifacts including temporary files.
compile Compile all Java source files.
verify Run all regression tests.
package Create bundle JARs.
doc Generate documentation.
legal Verify license information in source headers.
build Compile, verify, package, verify license information and create documentation.
rebuild Clean and build (default target).
deliver Rebuild and create a ZIP archive with checksum.

By default the build output is created directly in the build project folder with the following structure. The dist folder contains all files of the distribution which will be packed into a ZIP archive if the deliver target was called.

  org.jacoco.build/
     result/
        dist/
        tmp/
        jacoco-<version>.zip
        jacoco-<version>.zip.MD5

If you edit the JaCoCo build files with the Eclipse Ant editor the file jacocoant.jar might become locked until you exit Eclipse. In this case subsequent builds will always fail as they can't write this file any more. The reason is the code assist function for user defined tasks. Please see the Eclipse reference on how to configure the Ant Editor to avoid these locks.

Customizing the Build

The build.xml file defines default values for several properties that can be overwritten from outside:

Property Description Default Value
workspace.dir Folder that contains the source of the JaCoCo bundles. ..
result.dir Folder where all build results are written to. ./result
result.dist.dir Folder where all build artifacts for distribution are written to. ${result.dir}/dist
result.tmp.dir Folder for temporary build files. ${result.dir}/tmp
build.qualifier Build qualifier that will be inserted into all bundle versions and documents. Current timestamp.
jacoco.home.url URL of the current home page for JaCoCo. http://www.eclemma.org/jacoco

The layout of the target platform might be customized in the target.xml file.

The file build.properties is part of the Eclipse PDE declarations and not (yet) used by the JaCoCo Ant build.

Internal Structure of the Build

JaCoCo is built by a set of custom Ant scripts that can be easily executed on different machines. While the modularization mechanism is based on OSGi bundles, the build does not (yet) use a build system like PDE build or Maven. The reason is that some JaCoCo artifacts like the jacocoagent.jar have very specific packaging requirements.

Structure of the Build Files

The main build.xml calls the buildbundle.xml script for each bundle. The target.xml file is included in the main build file and defines the structure of the target platform. Each bundle defines its specific requirements in a local buildhook.xml file which is included into the buildbundle.xml when the respective bundle is build.

org.jacoco.build/build.xml
include org.jacoco.build/target.xml
for each bundle:
call org.jacoco.build/buildbundle.xml:
include <bundleid>/buildhook.xml

Class Paths

The class paths of all bundles are defined as path instances with ids in the format bundle-<bundleid>. For the target platform the paths are explicitly defined by the target.xml file. For the JaCoCo bundles a respective path instance is automatically defined after each bundle has been built.

Dependencies

Dependencies are not automatically derived from declarations in the bundle manifests. Instead the buildhook.xml files compose a new path definition from the dependencies, for example:

    1<path id="dependencies">
    2    <path refid="bundle-org.jacoco.core"/>
    3    <path refid="bundle-org.objectweb.asm"/>
    4</path>

In addition source items from other bundles can be referenced through the property source.<bundleid>.dir which points to the root folder of the respective bundle. A suitable build order for the JaCoCo bundles is hard coded in the build.xml file.

Custom Build Tasks

The org.jacoco.build bundle implements a set of custom Ant tasks and types that primarily help to implement specific packaging requirements: