PhenoTips » Developer Guide » Building PhenoTips

Building PhenoTips

Understanding the directory structure

Before you start it's good to have some minimal understanding of how Maven works. You probably won't need it if everything goes fine but you'll need that knowledge if something breaks!

The first thing to understand is the directory structure we use.

Checking out the sources

Use your favorite SCM client to check out the code.

Installing Maven

Install Maven 3.0 or greater. Create an M2_HOME environment variable pointing to where you have installed Maven. Add M2_HOME/bin to your PATH environment variable.

For more information on how to install Maven or how to use it check this excellent Maven book.

Building with Maven

Now that you have installed Maven and checked out the source code, you'll want to build it. To build a project with Maven just issue the command:

mvn clean install

Each project is made of modules. You can check out and build any single module (and its children) you wish without having to rebuild the other modules from source. Maven will pick the latest version of your module's dependencies from our Nexus/Maven remote repositories. Of course if you have uncommitted changes in a dependent module, you'll want to build that module before. The build result is placed in two places:

  • Your local maven repository, for making the module available to other projects or modules using maven (even other PhenoTips modules take the needed libraries from this repository, and not directly from a "neighbor" directory)
  • In a subdirectory of that module, called target.

After building successfully, you can run PhenoTips by unzipping the .zip artifact from distribution/standalone/target and executing the start.sh or start.bat script from it.

Some of the modules are very large (in the 200MB+ size) and sometimes you don't absolutely need the latest version to get downloaded as it'll take too long. In that case here's a tip: run Maven in 'no-snapshot-update' mode with mvn install -nsu.

Relationship between PhenoTips and XWiki

The XWiki Platform is a generic platform and API for building flexible extensible wikis and web applications. PhenoTips is an application built on top of the XWiki Platform. While compiling PhenoTips, you will notice Maven downloads many dependencies from the org.xwiki.* groups, and these are different parts of the XWiki platform that PhenoTips depends on.

For developers/contributors, this means that there are two different projects where a change could go into.

Since PhenoTips is just an application built on top of a larger platform/framework, most of the features are provided not by PhenoTips code, but by XWiki code. As such, many bugfixes and improvements will have to be submitted to the XWiki community, following their rules and practices. However, most of the PhenoTips developers are also XWiki committers, and have a long history in the XWiki Community, so they can help to facilitate the communication between the two communities, PhenoTips and XWiki.

Automatic Checks

The build performs some automated checks:

  • Style checks with Checkstyle (skip with: -Dcheckstyle.skip)
  • Verify header licenses (skip with: -Dlicense.skip)
  • Backward compatibility checks with CLIRR (skip with: -Dclirr.skip)
  • Verify that all Maven plugins have their versions specified

Troubleshooting

Dealing with Out-of-Memory Errors

If you get an OutOfMemoryError then increase the maximum heap space by setting the MAVEN_OPTS environment variable.

If you're getting a PermGen space error you need to increase the JVM PERMGEN. For example:

export MAVEN_OPTS="-Xmx2g -XX:MaxPermSize=256m"

Building behind a proxy

If you are connecting to the Internet through a proxy then you need to modify your /.m2/settings.xml file so that Maven knows it:

<settings>
 <proxies>
   <proxy>
     <active>true</active>
     <protocol>http</protocol>
     <host>host</host>
     <port>port</port>
     <username>uname</username>
     <password>password</password>
   </proxy>
 </proxies>
 <!--other tags-->
</settings>