Introduction

This document shortly introduces to the use of Maven for compiling jrawio. Maven is a tool for automating the software creation process, including compiling, running tests, performing static analysis on code, generating all the project artifacts and deploying them to a repository. Maven has been designed as a platform made of plugins, that are downloaded from the network on demand. That's why you'll see a lot of downloads the first time you use it, or the first time you perform a new task with it. Plugins are cached in the $HOME/.m2/repository directory.

Maven also manages the project dependencies, that is required libraries, that are downloaded from the network and cached on the disk in the same way as plugins. Every dependency can be versioned (and Tidalwave's policy is to explicitly version everything), so builds are reproducible.

Maven expects that projects are described in a specific file, the POM (Project Object Model), named pom.xml. While the syntax is in XML, it is completely different from an Ant script: while Ant is basically an interpreter of a scripting language that is in part rule-based and in part imperative, the POM is just a configuration. Maven uses a fixed sequence of operations to do, where plugin can attach. POMs can be inherited by modules - you'll see that jrawio has a "master POM" in the main directory, declaring all the required dependencies and extensions; jrawio and reajent have got their own POMs, which are smaller as they inherit the configuration from the master.

The POM also formally defines the project version - this information is used to automatically manage the release cycle.

Building from the command line

Maven can be run from the command line or from your favorite IDE. From the command line:

mvn -Dproperty1=value1 -Dproperty2=value2 goal1 goal2 ... goaln

There are two properties that are very important for correctly working with jrawio. While it's possible to build the project without them, not using them will cause the build process to last a very long time (hours):

-DskipTests=true

-Dtestset.cached.folder=/some/path

It's convenient to set the latter property in the Maven configuration ($HOME/.m2/settings.xml)

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
                      http://maven.apache.org/xsd/settings-1.0.0.xsd">
    <profiles>
        <profile>
            <id>fritz</id>
            <properties>
                <testset.cached.folder>/some/path</testset.cached.folder>
            </properties>
            <activation>
                <activeByDefault>true</activeByDefault>
            </activation>
        </profile>
    </profiles>

</settings>

Other properties can be used to control tests - please read the specific document about testing.

Main goals

Goals are labels defining what you might want to do: e.g. compile, test etc. Each goal gets translated into a sequence of phases that concur to the execution of the goal. The most important goals for jrawio are:

Most of goals can be run both from the main directory (this means that they apply to both jrawio and reajent) and from a single component directory.

Some common usages are:

mvn clean install -DskipTests=true

mvn clean install javadoc:javadoc \ 
    javadoc:aggregate -DskipTests=true

mvn clean install javadoc:javadoc \
    javadoc:aggregate assembly:assembly -DskipTests=true

Don't worry about running the whole set of tests. A Continuous Integration server runs them automatically, as well as all the static analysis tools.