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 specific recommendations are http://www.sonatype.com/books/maven-book/reference/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.
Some specific environment setup you'll need:
- 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 5 (e.g. export JAVA_HOME=$PATH:/opt/jdk-1.5.x). JDK 6 will not work at the current time because of changes in JDBC interfaces, however be sure to see the section on Maven settings.
- It is most likely that you will need to increase the memorty available to Maven; the easiest option is to set MAVEN_OPTS -Xms128m -Xmx512m (e.g. export MAVEN_OPTS="-Xms128m -Xmx512m")
- See the Note about documentation section below
Hibernate, like most other JBoss projects, publishes its artifacts into the JBoss Maven repository. Additionally, Hibernate uses some custom Maven plugins in its build which are also hosted at the JBoss Maven repository. You'll need to account for these repositories in your local Maven setup.
Also, it was mentioned above that Hibernate needs JDK 1.5 to build, but that certain modules need access to JDK 1.6 as well. That is something else you will need to define locally.
The best way to define these needed pieces of information is via the ~/.m2/settings.xml file (be sure to replace the jdk16_home property with a path appropriate to your system).
<?xml version="1.0"?> <settings> <pluginGroups> <pluginGroup>org.jboss.maven.plugins</pluginGroup> </pluginGroups> <profiles> <profile> <id>repos</id> <properties> <!-- Here we point to our local JDK 1.6 home --> <jdk16_home>/opt/java/jdk-1.6</jdk16_home> </properties> <!-- Here we define the JBoss release and snapshot repos --> <repositories> <repository> <id>jboss</id> <url>https://repository.jboss.org/nexus/content/groups/public/</url> <releases> <enabled>true</enabled> <updatePolicy>never</updatePolicy> </releases> <snapshots> <enabled>true</enabled> <updatePolicy>never</updatePolicy> </snapshots> </repository> </repositories> <!-- Here we define the JBoss release and snapshot repos *for plugins* --> <pluginRepositories> <pluginRepository> <id>jboss-plugins</id> <url>https://repository.jboss.org/nexus/content/groups/public/</url> <releases> <enabled>true</enabled> <updatePolicy>never</updatePolicy> </releases> <snapshots> <enabled>true</enabled> <updatePolicy>never</updatePolicy> </snapshots> </pluginRepository> </pluginRepositories> </profile> </profiles> <!-- Here we add our profile defined in settings.xml to the active profiles --> <activeProfiles> <activeProfile>repos</activeProfile> </activeProfiles> </settings>
Be sure to see http://community.jboss.org/wiki/MavenGettingStarted-Users and http://community.jboss.org/wiki/MavenGettingStarted-Developers for the latest information on accessing the JBoss Maven repository.
Hibernate uses jDocBook to process its documentation. jDocBook uses an approach for handling translations based on GNU Gettext and specifically some utilities from the KDE documentation team for handling DocBook XML via Gettext's POT and PO files. As such it needs access to some system utilities from the KDE SDK loosely called poxml. It is made availavble in different formats depending upon your OS (and even differently in different Linux distros).
If you do not have these utlities available on your system, you may see errors from jDocBook when trying to build Hibernate; errors to the extent that po2xml (one particular utlitiy/command) cannot be found. If you encounter this error, you can choose to either:
- install the appropriate KDE SDK utilities for your system
- On Mac OS X you can install the required libraries via macports. Once you have macports installed, you run sudo port install kdesdk4. After that you have to add xml2pot and po2xml to your PATH variable. You find the executables under /Applications/MacPorts/KDE4/xml2pot.app/Contents/MacOS resp. /Applications/MacPorts/KDE4/po2xml.app/Contents/MacOS
- skip documentation processing by specifying -DdisableDistribution=true to (Maven)
Translating documentation into different languages
In order to start the translation of the master document into a new language you need the po files for the translation. First you need to make sure that the language you want to translate the documentation into is listed in the <translations> node of the jdocbook configuration in the maven pom. Once this is done you have to run:
mvn jdocbook:update-pot mvn jdocbook:update-po
Calling jdocbook targets directly like this requires that you add the following to your settings.xml:
<pluginGroups> <pluginGroup>org.jboss.maven.plugins</pluginGroup> </pluginGroups>
Without the plugin group definition you have to specify groupId, artifactId and version ofthe plugin you want to run. See also plugin groups.