Maven Guide

Setting up Maven in your environment

Download and install Maven

If you don't already have Maven installed here are the steps needed:

Get Maven 2 from http://maven.apache.org/run-maven/index.html
If not already set, set your PATH to include maven2/bin (eg. export PATH=$PATH:/opt/maven2/bin)
If not already set, Set your JAVA_HOME to point to a JDK (e.g. export JAVA_HOME=$PATH:/opt/jdk-1.5.x)

JBoss Maven repository

Hibernate uses some custom Maven plugins in its build. Those plugins are hosted at the JBoss Maven repo (for the time being, at least). You'll need to account for this fact in your local Maven set up. The best way is via the ~/.m2/settings.xml file (you may need to create this file):

<settings>
    <profiles>
        <profile>
            <id>standard-extra-repos</id>
            <activation>
                <activeByDefault>true</activeByDefault>
            </activation>
            <repositories>
                <repository>
                    <id>jboss</id>
                    <url>http://repository.jboss.com/maven2</url>
                    <releases>
                        <enabled>true</enabled>
                    </releases>
                    <snapshots>
                        <enabled>false</enabled>
                    </snapshots>
                </repository>
                <repository>
                    <id>jboss-snapshot</id>
                    <url>http://snapshots.jboss.org/maven2</url>
                    <releases>
                        <enabled>true</enabled>
                    </releases>
                    <snapshots>
                        <enabled>true</enabled>
                    </snapshots>
                </repository>
            </repositories>
            <pluginRepositories>
                <pluginRepository>
                    <id>jboss-plugins</id>
                    <url>http://repository.jboss.com/maven2</url>
                    <releases>
                        <enabled>true</enabled>
                    </releases>
                    <snapshots>
                        <enabled>false</enabled>
                    </snapshots>
                </pluginRepository>
                <pluginRepository>
                    <id>jboss-snapshot-plugins</id>
                    <url>http://snapshots.jboss.org/maven2</url>
                    <releases>
                        <enabled>true</enabled>
                    </releases>
                    <snapshots>
                        <enabled>true</enabled>
                    </snapshots>
                </pluginRepository>
                 <!-- 20080306 added by emmanuel to make things work -->
                 <pluginRepository>
                     <id>codehaus-plugins-snapshots</id>
                     <url>http://snapshots.repository.codehaus.org/</url>
                     <snapshots>
                         <enabled>true</enabled>
                     </snapshots>
                     <releases>
                         <enabled>false</enabled>
                     </releases>
                 </pluginRepository>
            </pluginRepositories>
        </profile>
    </profiles>
</settings>

The above enables snapshot services from the JBoss Maven snapshot repo. Depending on your usage and the release, you may be able to get away with removing those entries; it may make the build slightly faster.

If everything works

mvn clean install

should be able to complete with no errors.

Setup Eclipse

There are several ways to use the new maven structure within eclipse each with its own set of advantages and disadvantages. The following paragraphs try to outline the most popular setupd. For general information integrating maven in eclipse see http://maven.apache.org/guides/mini/guide-ide-eclipse.html

maven-eclipse-plugin

Go to Window > Preferences > Classpath Variables and make sure you have an M2_REPO variable defined and pointing to your Maven repository (by default it is ~/.m2/repository).

If you are running with the Maven plugin this variable should be configured automatically.

Then you can run:

mvn eclipse:eclipse

and go to File > Import > Existing Projects into workspace and select the code directory. Eclipse will automatically pick up all the subprojects/modules and you should be ready to go.

For more information regarding the maven-eclipse-plugin see http://maven.apache.org/plugins/maven-eclipse-plugin/eclipse-mojo.html

m2eclipse

m2eclipse offers a more advanced maven integration than eclipse:eclipse. To install m2eclipse follow the instructions on the plugin's homepage - http://m2eclipse.codehaus.org/. Once installed make sure that you use the latest version on maven. You can configure the maven version used by the plugin under Preferences > Maven > Installations. Provided you have the source code already checked out you can now import all maven modules and submodules by selecting File > Import... > General > Maven Project. Point to the top level directory (the one containing the master POM).

Initially there might be several errors once Eclipse has build the workspace. The reason is that some of the java classes get generated by antlr and are initially not available. You can fix this by running an initial build and then adding target/generated-sources/antlr to the build path of the hibernate-core module. You can trigger your maven goals by selecting Run > Open Run Dialog > Maven Build. To trigger a recursive build of all modules select as base directory the top level directory of your checkout.

For more information about the m2eclipse plugin see http://m2eclipse.codehaus.org/

Setup Intellij

By far the best approach is to get Intellij 7 (still EAP as of writing this) and to use its Maven2 integration to load up the Hibernate project.

Directory Layout

(this is currently in flux...)

The main thing to understand is the project structure and its purpose. I don't mean the standard directory layout; here, I am talking about the layout of projects and sub-projects. At the root of the checkout you will find the main pom (Hibernate3/pom.xml) which is used for release builds and to define common values and settings. The pom defines two sub-projects: code and documentation.

code/

TBC...

documentation/

Blah, blah, blah

documentation/manual/

TBC...

documentation/tutorial/

TBC...

For Users

As users of Hibernate wanting simply to build Hibernate, there is actually very little you need to know about Maven. You will need to understand the basic Maven concepts of lifecycle and goals. Additionally, Hibernate uses some custom Maven plugins which are hosted at the JBoss Maven repository; you will need to account for that fact in your local Maven setup.

Maven basics: lifecycles and goals

The two best resources for understanding Maven concepts are the Maven book and the Maven website. In terms of learning what you need to work with the Hibernate build, two things I would recommend in particular are http://www.sonatype.com/book/lifecycle.html and http://maven.apache.org/guides/getting-started/maven-in-five-minutes.html. They both cover some of the same material, but are pretty quick reads and probably worth hitting both.

For Developers

Coming soon...

DocBook

The hope it to eventually merge this work with the DocBook plugin hosted at codehaus. But, for the time being it resides in Hibernate SVN under trunk/sandbox/maven-poc/plugins; it is currently published as org.jboss.maven.plugins:maven-jboss-docbook-plugin.

General road map for the docbook plugin is essentially driven by two requirements:

dedicated packaging type.
1. "docbook" seems the natural packaging name
2. proper attaching of produced artifacts, and proper handling of those attached artifacts
3. custom archetype for this "docbook" packaging
4. goal to build a deployable unit out of the built artifacts (war?)
get out of xslt maintenance.
1. work with the Red Hat documentation team regarding transitioning to use their xslt stylesheets for transformations.