MavenBuildCreation

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

  1. Project Inputs

    1. Determine which dependencies are required for your project

    2. Ensure that the dependencies exist in the repository Maven2 repository

  2. Project Outputs

    1. Project output policy T.B.D

  3. Project build needs

    1. Each project will have a unique set of builds needs (e.g. Compilation, RMIC, idl compilation, aop compilation, retroweaving)

    2. Determine if plugin exists for each need, request plugin if it does not

-


The pom file

  1. The build instructions for a maven file are contained in file called pom.xml.

  2. 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)

  1. 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

    1. A list of modules to build

    2. Common properties

    3. Common build procedures (e.g. compiling manifests)

    4. Version numbers of plugins and dependencies

    5. 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:

  1. Create a pom.xml from the child pom template

  2. Add the appopriate thirdparty dependencies

  3. Add the appropriate project dependencies

  4. 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:

  1. mvn install   //this will compile your project, create the outputs and install them into you local repository

  2. mvn compile  //compile your project

  3. mvn -X compile  //compile your project and print the build debug information

 

Maven Release Procedure

The release of a maven based project requires:

  1. Set all the versions to the release version

  2. Run the following command to check dependencies are consistent: mvn project-info-reports:dependencies

  3. Tag and Release

  4. 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

Plugins

 

 

-


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.

 

-


UnitTestsWithMaven2