Documentation & Tutorials

Try a tutorial to get you started with Integrity, or read about some of the more advanced features.

Building Integrity

So you want to have a development environment in which you can build Integrity from scratch? Fine :-) just follow these steps to set it up! Note that I assume a certain familiarity with Eclipse, Git and Maven, which are the major tools used in Integrity development.

Prerequisites

You'll need an Eclipse 4.6 installation (for developing on the master branch; older branches may require older versions) with the following mandatory plugins:

    • m2e (Maven Integration for Eclipse)
    • Tycho Project Configurators
    • Eclipse RCP Development Tools
    • JAX-WS Tools (not actually because of the tools, but because of the dependency to org.jdom, which is used by Integrity - and it is easiest to just install JAX-WS tools into Eclipse to get org.jdom)
    • Xtext SDK

The easiest method to get a working Eclipse installation is to download the "Eclipse for Java and DSL Developers" package, which already includes m2e, the RCP tools and the Xtext SDK. You then just have to install the Tycho stuff (which can be easily done by opening one of the pom files and using the quick fix links shown at the errors) and JAX-WS Tools (can be found via "install new software", NOT via the Marketplace!).

Cloning the Git repository

Now you'll need to fetch the source from the Git repository. This is done by cloning the central repo to your local machine. You can do this either using the command-line Git tools, if you prefer, or completely from inside Eclipse using the EGit plugin.

Head over to GitHub to find the URL for the Integrity Test Framework source repository. Then do a "git clone" using that URL. If you've got a GitHub account, you might of course want to create a private fork of the main repository first and clone that one, so you'll be able to push changes.

Once you've cloned the repository to your local hard disk, you should see it in the Git repository view inside Eclipse. From there you can check out the "master" branch (which is the development mainline) or one of the version-specific maintenance branches and add all the projects in the "working directory" to your Eclipse workspace. Don't copy the projects into your workspace, just add them via reference - it is perfectly normal for Git-managed projects to reside outside of your actual workspace directory!

Fixing the weird build errors

After checking out and adding all the projects for the first time, you will probably get some weird build errors. The errors in the POMs most likely point to missing Tycho m2e plugins and can easily be fixed by following the quick fix links. If there are missing references to org.jdom classes, you have forgotten to install JAX-WS Tools into your Eclipse as described in the prerequisites - org.jdom unfortunately cannot be installed independently, but is a dependency of JAX-WS Tools, so the easiest way to get it is to install the JAX-WS Tools plugin.

The final errors in the "experimentation" projects are due to a missing classpath variable named INTEGRITY_EXPERIMENTATION_CP_ROOT. That variable must be created in the Eclipse preferences and should point to your workspace root folder.

Building

The actual build process is done by Maven. You shouldn't require any special configuration in your local settings.xml to build Integrity and install the resulting artifacts in your local Maven repository. For your convenience, there are some predefined Maven launch configurations in the "build" project, with the most important one probably being "Integrity Test Framework - Main Build", which triggers a build of all modules that the Integrity Test Framework consists of.

The two launch configs "Integrity Test Framework - Distribution Build" and "Integrity Test Framework - Update Site" package up the build results in a distribution zip file or an Eclipse update site. Note however that these require the artifacts to be already built and available in your local Maven repository, because they won't trigger a build process of their own, but use the results of a previous build.

All the fancy stuff: Checkstyle, Formatting etc.

If you consider contributing to the project, please do set up Checkstyle and the code formatting rules in your Eclipse workspace! You'll find a Checkstyle config file in the "build" project, within the "checkstyle" subdirectory. Go to your Eclipse preferences and set up a new Checkstyle configuration which looks like this:

checkstyle.png

Checkstyle should then warn you about problems like missing/empty Javadoc, variable names not matching the naming scheme used throughout the Integrity source base et cetera.

Code formatting and compiler settings are equally easy to set up: just choose "Import" in Eclipse and select "Preferences". Then browse to the file "codestyle_compiler_settings.epf" which is located in the "eclipse" subdirectory of the "build" project. You should then be able to import the settings with just a few more clicks!