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 |
target.name |
Name of the target environment to run the build against. | default |
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. A target_*.xml
file is included in the main
build file to define 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
org.jacoco.build/target_${target.name}.xml
org.jacoco.build/buildbundle.xml
:<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:
- Task
randomid
: Creates a short random string which is a valid Java identifier. This task is used to define unique package names for all classes of the Java agent avoiding name clashes at runtime. - Type
deepclassfileset
: Analyzes class file dependencies recursively to select a subset of class files from a given file set. This type is used to package small all-in JARs for the Java agent and the JaCoCo Ant library. - Type
renamedclassfileset
: Renames class files and their dependencies to other class files based on a set of mapping rules. This type is used to rename the classes for the Java agent.