In order to keep the KIELER code as stable as possible, we use automatic continuous integration builds. Once you push something into one of the KIELER repositories, you trigger the automatic build process. If the build fails for whatever reason – be it failed unit tests or simply compilation errors – you are notified of the problem.

This page describes the software and setup we use to implement all of this.

Content

Software We Use

To implement our automatic builds, we use the popular Maven tool in conjunction with Tycho, a set of Maven plug-ins that allow Maven to build Eclipse projects. To implement our continuous integration builds, we use Atlassian Bamboo.

Maven / Tycho

Maven is a build tool for Java projects. It takes care of dependency management, including in-build dependencies (the order in which packages are compiled) as well as dependencies to third-party libraries. The latter are automatically fetched from special Maven repositories. Without getting too technical, a Maven build consists of several phases, such as compile and package. Within each phase, several Maven plug-ins handle different tasks (or goals, as Maven calls them). The maven-compile-plugin for example compiles .java files into .class files.

To correctly compile a project, Maven needs to be told about the project. While the popular Ant build tool uses build.xml files to describe the steps to be executed for building a project, Maven uses pom.xml files to describe the project and figures out the steps for itself. The POM files may inherit settings from a parent POM file.

Tycho is a set of Maven plugins that handles compiling and dependency management as well as bundling of Eclipse plug-ins. Tycho understands Eclipse metadata files such as plugin.xml or feature.xml, provides dependency information extracted from those files, and provides an Eclipse instance for compiling and packaging Eclipse bundles.

Bamboo

While Maven and Tycho know how to compile KIELER, Bamboo knows when to compile KIELER and what to do with the compiled project. Bamboo has access to our source code repositories and triggers continuous integration builds every time someone pushes new code into a repository. It also does a full build every night and copies the results onto our nightly build update site to be accessed by people all around the world. And beyond. Tell your friends!

The Automatic Build Process

This section describes how our POM files are distributed throughout the repository structure, and how you can trigger an automatic build of KIELER.

POM Files

The basic structure of the POM files can be seen below:

Each plug-in and feature has a corresponding (usually rather small) POM file. The POM files in the features and plugins directories know about the different features and plug-ins. The parent POM file, which all other POM files copy basic configuration from, knows about the feature and plug-in POM files. In addition, the build directory also contains a bunch of subdirectories. These also contain POM files specialized for building the P2 repositories necessary to publish our Eclipse features.

Using the KIELER Maven Build

Using the KIELER Maven build requires knowledge about two aspects: necessary configuration / required libraries and invoking Maven.

Necessary Configuration

KIELER needs to be built against a P2 repository generated from our Eclipse reference installation. The path to this repository is found in the parent POM file and must be changed if the repository location changes. Also, when changing the reference installation, the repository has to be updated using the following magic command (adapted accordingly):

java -jar eclipse_3.8/plugins/org.eclipse.equinox.launcher_*.jar \
-application org.eclipse.equinox.p2.publisher.FeaturesAndBundlesPublisher \
-metadataRepository file:/home/java/repository/juno382 \
-artifactRepository file:/home/java/repository/juno382 \
-source /home/java/eclipse_3.8/ \
-publishArtifacts

Invoking Maven

To actually build KIELER once all preliminaries are done, navigate to the /build/de.cau.cs.kieler.parent directory and run the following command line:

mvn clean package -P <profile>   # For a list of available profiles, see parent pom.xml

If you are trying to build KIELER on our server, you first have to setup the Java environment, if you haven't already done so. The command line thus becomes:

. /home/java/java-env
mvn clean package -P <profile>   # For a list of available profiles, see parent pom.xml

Once Maven has finished, the different build artifacts may be found in the /build/de.cau.cs.kieler.*.repository/target directories.

What to Be Aware of

There are some things that people need to be aware of to keep the build files in a valid state.

1. Eclipse metadata and POM files are not synchronized. Thus, if the version of an Eclipse plug-in changes, its pom.xml needs to be updated accordingly.
2. The repository POM directories contain product files and product icons. These are copies of the files found in the corresponding branding plug-ing (such as de.cau.cs.kieler.core.product) and have to be manually synchronized.

Continuous and Nightly Builds

There are basically three different build plans for each of the KIELER projects:

1. Continuous Plugins – Compiles the plug-ins and runs the unit tests on them. None of the compiled artifacts are published anywhere. This plan is triggered by pushing stuff into the repositories, giving early feedback regarding whether committed changes break anything.
2. Nightly Product – Compiles the plug-ins and assembles distributable product files and update sites. Distributable files are published in the nightly build directory /home/kieler/public_html/files/nightly. Update sites are published in /home/kieler/public_html/updatesite/nightly. This plan is run once every night.
3. Nightly Rating – Compiles the plug-ins and runs our code quality rating doclet on them. The result is a website published at /home/kieler/public_html/rating. This plan is run once every night.

Different Nightly Product Builds

Since KIELER is divided into the Pragmatics and Semantics parts, the different Nightly Product builds produce different artifacts.

• KIELER Pragmatics
  
  • KLay layout library redistributables
  • KWebS redistributables
  • Papyrus Layout update site
• KIELER Semantics
  
  • KIELER redistributables
  • KIELER update site