Building Hibernate From Source (3.5)

Hibernate 3.5 is built using Maven.  As a  first step, if not already, download and install Maven.

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.

Environment

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

 

Maven settings.xml

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.

 

Note about documentation

 

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:

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

 

Release Process

 

See - Hibernate Release (3.5 w/ Maven)