Note: this page is out of date, for up to date information, see Maven Getting Started
This guide will serve as a tutorial for setting up a build of a JBoss project using maven2.
Build Creation steps
-
Determine project needs
Project Inputs
Determine which dependencies are required for your project
Ensure that the dependencies exist in the repository Maven2 repository
Project Outputs
Project output policy T.B.D
Project build needs
Each project will have a unique set of builds needs (e.g. Compilation, RMIC, idl compilation, aop compilation, retroweaving)
Determine if plugin exists for each need, request plugin if it does not
-
The pom file
The build instructions for a maven file are contained in file called pom.xml.
While poms can always define the same information, for our purposes we will make a distinction between two type of poms
Top level Pom
This is any pom whose defintions are inherited by another project (e.g. /jboss/build/pom.xml)
The top level pom can define build instructions which are picked up by child level builds. It is in this pom where you will define things such as
A list of modules to build
Common properties
Common build procedures (e.g. compiling manifests)
Version numbers of plugins and dependencies
A list of repositories to search for plugins and dependencies
<!-- Example top level pom -->
<project>
<!-- Build project description -->
<modelVersion>4.0.0</modelVersion>
<groupId>jboss</groupId>
<version>5.0-SNAPSHOT</version>
<artifactId>jbossas</artifactId>
<name>JBoss Top Level Build</name>
<packaging>pom</packaging>
<!-- properties can be defined in this fashion -->
<properties>
<specification.title>JBoss</specification.title>
</properties>
<!-- you can define a list of modules to build for your project -->
<modules>
<module>../module1</module>
<module>../module2</module>
</modules>
<!-- describe the build process -->
<build>
<!-- define src and output directories, this is inherited by child builds -->
<sourceDirectory>src/main</sourceDirectory>
<outputDirectory>output/classes</outputDirectory>
<!--a plugin is how achieve a unit of work, a build is made up a series of plugins -->
<plugins>
<!-- define a custom clean plugin and configure it to include the cleaning
of an additional directory
Because this is a top level build, the plugins we define here will be inherited
by the builds in the child modules -->
<plugin>
<artifactId>maven-clean-plugin</artifactId>
<configuration>
<filesets>
<fileset>
<directory>${basedir}/output</directory>
</fileset>
</filesets>
</configuration>
</plugin>
<!-- define how we want compilation to take place
here, we accept most of the defaults but say that we want the
optimization flag set, and define the source and target to be 1.4,
these setting will be inherited by child projects -->
<plugin>
<artifactId>maven-compiler-plugin</artifactId>
<version>2.0</version>
<configuration>
<optimize>true</optimize>
<source>1.4</source>
<target>1.4</target>
</configuration>
</plugin>
<!-- define that we wish to create src jars -->
<plugin>
<artifactId>maven-source-plugin</artifactId>
<inherited>true</inherited>
<executions>
<execution>
<goals>
<goal>jar</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
<!-- This section defines plugins which will be used in the build.
Placing plugin descriptions here will give them default values, but
will not dictate that they will be used by child builds.
This section allows us to lock down plugin versions which are used. -->
<pluginManagement>
<plugins>
<plugin>
<artifactId>maven-compiler-plugin</artifactId>
<version>2.0</version>
</plugin>
<plugin>
<artifactId>maven-clean-plugin</artifactId>
<version>2.1</version>
</plugin>
</plugins>
</pluginManagement>
</build>
<!-- define a repository used to retrieve dependencies from -->
<repositories>
<repository>
<id>central</id>
<name>JBoss Repository</name>
<url>http://repository.jboss.com/maven2</url>
<layout>default</layout>
</repository>
</repositories>
<!-- define the plugin repository we wish to use -->
<pluginRepositories>
<pluginRepository>
<id>central</id>
<name>jboss plugin repository</name>
<url>http://repository.jboss.com/maven2</url>
<layout>default</layout>
<snapshots>
<enabled>true</enabled>
<updatePolicy>never</updatePolicy>
</snapshots>
</pluginRepository>
<pluginRepository>
<id>lsu.edu</id>
<name>LSU maven2 mirror</name>
<url>http://ibiblio.lsu.edu/main/pub/packages/maven2</url>
<layout>default</layout>
<snapshots>
<enabled>false</enabled>
<updatePolicy>never</updatePolicy>
</snapshots>
</pluginRepository>
</pluginRepositories>
<!-- the dependencyManagement section allows us to define dependencies
which may be used by subprojects, we specify the version here, this does
not however dictate that the subproject will use the dependency, they must
request it -->
<dependencyManagement>
<dependencies>
<dependency>
<groupId>dom4j</groupId>
<artifactId>dom4j</artifactId>
<version>1.5</version>
</dependency>
</dependencies>
</dependencyManagement>
</project>
-
Child Level Pom
The child level pom generally should define which dependencies are needed to build, any custom build procedures (e.g. rmic) and how to build the output artifact The following is a template pom.xml:
<project>
<modelVersion>4.0.0</modelVersion>
<groupId>jboss</groupId>
<artifactId>outputArtifactName</artifactId>
<packaging>jar</packaging>
<name>The name of your project</name>
<description>The description of your project</description>
<!-- add a reference to the parent pom, works in OO fashion -->
<parent>
<artifactId>app</artifactId>
<groupId>jboss</groupId>
<version>5.0-SNAPSHOT</version>
</parent>
<build>
<plugins>
<!--define how the rmic should take place -->
<plugin>
<artifactId>maven-rmic-plugin</artifactId>
<executions>
<execution>
<phase>compile</phase>
<configuration>
<outputClasses>${basedir}/output/classes</outputClasses>
<classPath>${basedir}/output/classes</classPath>
<iiop>true</iiop>
<remoteClasses>
<remoteClass>javax.ejb.EJBObject</remoteClass>
<remoteClass>javax.ejb.EJBHome</remoteClass>
</remoteClasses>
</configuration>
<goals>
<goal>process-classes</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
<!--define the dependencies required to build common -->
<dependencies>
<dependency>
<groupId>dom4j</groupId>
<artifactId>dom4j</artifactId>
</dependency>
</dependencies>
</project>
-
Developer steps
So for each project, to create a build file, you will do the following:
Create a pom.xml from the child pom template
Add the appopriate thirdparty dependencies
Add the appropriate project dependencies
Add and configure any additional plugins as needed.
-
How do I use maven?
Once you have created a pom file you will want to build your project. We now need to understand the concept of the maven lifecycle. For each build maven has a lifecycle. This lifecycle is divided into stages (e.g. validate, compile, tests, packaging).
Please see maven build lifecyle for a complete listing.
The general method is execute "mvn LIFECYCLE". This will execute each phase of the lifecyle up to and including the one you specify.
Here are some examples:
mvn install //this will compile your project, create the outputs and install them into you local repository
mvn compile //compile your project
mvn -X compile //compile your project and print the build debug information
Maven Release Procedure
The release of a maven based project requires:
Set all the versions to the release version
Run the following command to check dependencies are consistent: mvn project-info-reports:dependencies
Tag and Release
Update the versions in trunk to the next development version
Eclipse Integration
There is an eclipse plugin Eclipse Plugin Overview that helps with project/classpath maintence. Common tasks include:
Creating the eclipse project files from your POM you execute the following command:
mvn eclipse:eclipse
Eclipse needs to know the path to the local maven repository. Therefore the classpath variable M2_REPO has to be set. Execute the following command:
mvn -Declipse.workspace=<path-to-eclipse-workspace> eclipse:add-maven-repo
-
External Resources
General User Information
Maven pom description - describes all pom files
Maven FAQ - commonly asked questions
Maven Users List - best source of information, searchable archive
Plugins
Official plugins - default maven plugins
User created plugins - plugins submitted by community members
-
JBoss work on maven.
The initial work for JBoss was done in a labs project.
https://svn.labs.jboss.org/labs/jbossbuild/trunk/projects/
There are two things here: a jboss distribution with pom files (now out of date)
and a directory called plugins. These plugins are maven plugins which I wrote or grabbed from different places.
-
Comments