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
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. Our KLay layouters library is built using Apache Ant. To implement our continuous integration builds, we use Atlassian Bamboo.
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.
Ant is a very popular Java build tool. While Maven wants to know metadata about a project and then knows what to do to build it, Ant works by specifying exactly what to do to build a project. These steps are configured in a build.xml
file. We try to avoid using Ant, but still have Ant build files around for jobs too specialized to be properly handled by Maven.
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!
This section describes how our POM files are distributed throughout the repository structure, and how you can trigger an automatic build of KIELER.
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, as well as about every kind of build configuration we have (for building the pragmatics repository, for building the KWebS product, etc.). In addition, the build
directory also contains a bunch of subdirectories. These also contain POM files that actually implement the different build configurations to produce p2 repositories and products we can deliver.
Using the KIELER Maven build requires knowledge about two aspects: necessary configuration / required libraries and invoking Maven.
KIELER needs to be built against a P2 repository generated from an Eclipse reference installation (the target platform). The command for doing that is described on this page. The target platform is available online so you don't have to worry about it when building KIELER on your local computer.
To actually build KIELER once all preliminaries are done, navigate to the /build/
directory and run the following command line:
. /home/java/java-env # Only necessary when working on our servers mvn clean package -P <profile> |
Once Maven has finished, the different build artifacts may be found in the /build/de.cau.cs.kieler.<profile>.repository/target
directories. The following build profiles are available in the KIELER Pragmatics repository:
There are some things that people need to be aware of to keep the build files in a valid state.
pom.xml
needs to be updated accordingly.de.cau.cs.kieler.core.product
) and have to be manually synchronized.We distribute our KLay layout algorithms in two library files: one that contains just our algorithms, and another one that also contains dependencies such as required EMF classes. To build the KLay libraries, navigate to the /build/de.cau.cs.kieler.klay.libraries
directory and do the following:
KIELER_REPOSITORY
environment variable to point to a local copy of a p2 repository of our pragmatics build.build.xml
file. This will produce both versions of the KLay layout library.There are basically three different build plans for each of the KIELER projects:
/home/kieler/public_html/files/nightly
. Update sites are published in /home/kieler/public_html/updatesite/nightly
. These plans are run once every night./home/kieler/public_html/rating
. This plan is run once every night.The Semantics project has an additional build plan:
Our automatic builds produce a bunch of so-called artifacts: redistributable applications as well as a number of update sites. This table lists all artifacts, the project or repository they belong to, the build file responsible for producing them, the Bamboo build plan that builds them, and the directory they are finally placed in.
Artifact | Repository | Build File | Bamboo Build Plan | Final Directory |
---|---|---|---|---|
KLay Layout Libraries | Pragmatics | ...klay.libraries/build.xml | KIELER Pragmatics -> Nightly KLay | /home/kieler/public_html/files/nightly/klay |
KLighDning RCA | Pragmatics | ...klighdning.repository/pom.xml | KIELER Pragmatics -> Nightly KLighDning | /home/kieler/public_html/files/nightly/klighning |
KWebS RCA | Pragmatics | ...kwebs.repository/pom.xml | KIELER Pragmatics -> Nightly Product | /home/kieler/public_html/files/nightly/kwebs |
KIELER Pragmatics Update Site | Pragmatics | ...pragmatics.repository/pom.xml | KIELER Pragmatics -> Nightly Product | /home/kieler/public_html/updatesite/nightly/pragmatics/ |
Papyrus Layout Update Site | Pragmatics | ...papyrus.repository/pom.xml | KIELER Pragmatics -> Nightly Product | /home/kieler/public_html/updatesite/nightly-papyrus/ |
KIELER RCA | Semantics | ...semantics.repository/pom.xml | KIELER Semantics -> Nightly Product | /home/kieler/public_html/files/nightly/ |
KIELER Semantics Update Site | Semantics | ...semantics.repository/pom.xml | KIELER Semantics -> Nightly Product | /home/kieler/public_html/updatesite/nightly/semantics/ |
Ptolemy Libraries Update Site | Ptolemy | ...ptolemy.repository/pom.xml | KIELER Semantics -> Ptolemy Update Site | /home/kieler/public_html/updatesite/ptolemy/ |