Maven Introduction

To compile Maven project, run the following command:

mvn clean install -s settings.xml

This will execute the target "install" of the maven project which will compile, test and create a jar of the project.

NOTE: Don't forget the -s settings.xml option. This tells Maven where the dependencies of the MontiSim project are located (in the Nexus of the Software Engineering Chair).

Maven Projects

A maven project contains Java source code, tests, resources and a description file, the pom.xml file.

Project Structure

The project folder contains the pom.xml file. The maven commands must be run in the folder containing this file. Alongside this file is the src folder, containing all the code and resources. The src folder contains two sub-folders: main and test. These specify if the contents are for the final jar or if they are the sources and resources of the JUnit tests.

The main and test folders then in turn contain a java folder with all the .java files. The folder structure for the sources should match the java package structure even if maven does not care and will read any java source file as-is from this sub-folder.

Alongside the java folder can be a resource folder with files that will be packaged into the jar for the main target or be available to the test target.

The target folder is created by maven when building the project and contains all the temporary files. It can be deleted at any time and should not appear in the remote repository.

There can be any other folder alongside those mentioned here in the project folder. (Example: docs folder with documentation, graphics, ..., a scripts folder with various scripts, ...)

Pom file

The pom.xml file is what describes the details of the project to maven.

The following entries describe the group, id, version and name of the project:

<groupId>de.rwth-aachen.se.montisim.simulators</groupId>
<artifactId>basic-simulator</artifactId>
<version>1.1</version>
<name>basic-simulator</name>

The <properties> entry allows to define variables. Example:

<properties>
    <montisim.commons.version>1.0.9</montisim.commons.version>
    <java.version>1.8</java.version>
</properties>

Where the <montisim.commons.version>1.0.9</montisim.commons.version> entry can be used as follow in the rest of the pom: ${montisim.commons.version}. Generally the properties entries look as follow: <var_name>VALUE</var_name> and can be used as: ${var_name} and will resolve to VALUE.

The <dependencies> entry contains a list of project dependencies that will be used in the project. An example entry would be:

<dependencies>
    ...
    <dependency>
        <groupId>montisim</groupId>
        <artifactId>commons</artifactId>
        <version>${montisim.commons.version}</version>
    </dependency>
    ...
</dependencies>

More on the dependency system in the next section.

The pom.xml file also contains a list of plugins for the build process. This is the way of configuring the steps of the build process in maven. They are executed when running the mvn install ... command.

The plugin handling java compilation is maven-compiler-plugin, the plugin handling the testing is maven-surefire-plugin. The maven-shade-plugin plugin handles the creation of fat-jars (jar containing all the dependencies that can be executed as standalone).

The license-maven-plugin plugin will check that the content of a specified license file is at the top of all the files of the project. When adding new files to the project, it is good to run maven once before committing to include the license headers in the new files.

The <plugin> entries are used to specify which version of those plugins to use and to set their settings.

Finally the settings.xml file contains information about the remote maven repositories containing all the dependencies of MontiSim.

Maven dependency system

A dependency in the pom.xml describes a needed artifact for the project. When building, maven will do the following:

1. Look inside the local maven repository (%HOME_DIR%\.m2\repository) for the artifact with the given version.
2. If not found, look-up the different remote maven repositories for the artifact and download it to the local repository. The settings.xml file includes the nexus repository of the SE-chair, which contains the artifacts of all the master branches of the projects of the SE-GitLab (MontiSim, MontiCore, ...).

When running the install target of maven (mvn clean install ...), if the compilation and tests succeed, the resulting artifact will be placed in the local repository (overriding any artifact with the same id and version).

This means that to make local changes to a dependency of a project, the project of the dependency can be compiled locally and will be available to the other project through the local maven repository.