Building XWiki from sources

Error: Make sure you install Maven 2.0.9 or greater as there are issues with Maven 2.0.8 or lesser.

Understanding the directory structure

Before you start it's good to have some minimal understanding of how Maven2 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 used.

Checking out the sources

Use your favorite Subversion client to check out the sources.

You can check out the whole source tree or only a single module you wish to build. Maven2 is powerful enough in that it'll always try to download the required dependencies from the remote repositories you have defined, so that you don't have to build the whole project from sources.

Installing Maven

  • Install Maven 2.0.9 or greater. Create an M2_HOME environment variable pointing to where you have installed Maven. Add M2_HOME/bin to your PATH environment variable.
  • Make sure you give Maven's JVM enough memory. XWiki's build uses Aspects and GWT compilers which need lots of memory. A good value is to give the JVM 600MB. To do that set an environment variable named MAVEN_OPTS. For example on Unix add the following to your shell startup script:
MAVEN_OPTS=-Xmx600m

  • Create a ~/.m2/settings.xml file with the XWiki custom remote repository defined as shown below. If you are on Windows, create the directory .m2 in your home directory, e.g. C:\Documents and Settings\Administrator\.m2. If you cannot do this from Windows Explorer, open a commandline and use md .m2.
<settings>
  <profiles>
    <profile>
      <id>xwiki</id>
      <repositories>
        <repository>
          <id>xwiki-externals</id>
          <name>XWiki Maven2 Remote Repository for Third Party Dependencies</name>
          <url>http://maven.xwiki.org/externals</url>
          <releases>
            <enabled>true</enabled>
          </releases>
          <snapshots>
            <enabled>true</enabled>
          </snapshots>
        </repository>
        <repository>
          <id>xwiki-releases</id>
          <name>XWiki Maven2 Remote Repository for Releases</name>
          <url>http://maven.xwiki.org/releases</url>
          <releases>
            <enabled>true</enabled>
          </releases>
          <snapshots>
            <enabled>false</enabled>
          </snapshots>
        </repository>
        <repository>
          <id>xwiki-snapshots</id>
          <name>XWiki Maven2 Remote Repository for Snapshots</name>
          <url>http://maven.xwiki.org/snapshots</url>
          <releases>
            <enabled>false</enabled>
          </releases>
          <snapshots>
            <enabled>true</enabled>
          </snapshots>
        </repository>
      </repositories>
      <pluginRepositories>
        <pluginRepository>
          <id>xwiki-plugins-externals</id>
          <name>XWiki Maven2 Plugin Remote Repository for Third Party Plugins</name>
          <url>http://maven.xwiki.org/externals</url>
          <releases>
            <enabled>true</enabled>
          </releases>
          <snapshots>
            <enabled>true</enabled>
          </snapshots>
        </pluginRepository>
        <pluginRepository>
          <id>xwiki-plugins-releases</id>
          <name>XWiki Maven2 Plugin Remote Repository for Releases</name>
          <url>http://maven.xwiki.org/releases</url>
          <releases>
            <enabled>true</enabled>
          </releases>
          <snapshots>
            <enabled>false</enabled>
          </snapshots>
        </pluginRepository>
        <pluginRepository>
          <id>xwiki-plugins-snapshots</id>
          <name>XWiki Maven2 Plugin Remote Repository for Snapshots</name>
          <url>http://maven.xwiki.org/snapshots</url>
          <releases>
            <enabled>false</enabled>
          </releases>
          <snapshots>
            <enabled>true</enabled>
          </snapshots>
        </pluginRepository>
      </pluginRepositories>
    </profile>
  </profiles>
  <activeProfiles>
    <activeProfile>xwiki</activeProfile>
  </activeProfiles>
</settings>

Depending on your geographical location, you should to use closer maven repositories to speed up your build process. For more information refer Maven Mirror Settings Guide.

Building with Maven

Execute mvn install in any module you wish to build. This will build that module and all children modules. The build result is placed in two places:

  • the local maven repository, for making the module available to other projects or modules using maven (even other XWiki modules take the needed libraries from this repository, and not directly from a "neighbor" directory)
  • and in a subdirectory of that module, called target.
Warning: You might encounter an java.lang.OutOfMemoryError during aspectj:compile. You must increase the maximum memory used by maven, by setting MAVEN_OPTS=-Xmx512m (or a different amount of memory).

You'll find below some common build tasks.

Top level build profiles

Since the XWiki ecosystem contains several distinct products, building each module needed by such a project one by one is inefficient. For this, we have defined a few maven build profiles that ease the deployment of each XWiki product. Building such a product-profile is done by running mvn install -P<nameOfProfile> in the top level trunks directory. The available product profiles are:

  • all: for building everything;
  • xe: for building XWiki Enterprise; this is the default profile;
  • xem: for building XWiki Enterprise Manager;
  • curriki: for building Curriki.
For example, building all the modules needed for Curriki can be done using mvn install -Pcurriki. You can select more than one profile by separating them with commas, for example mvn install -Pxe,xem will build both XWiki Enterprise and XWiki Enterprise Manager. Read below to learn about other profiles that can be used for further customizing the build process.

Building everything

Go in trunks and type mvn install -Pall

Building a single module

Thanks to XWiki's Continuous Integration setup you can check out and build any module you wish without having to rebuild the other modules from source. Maven will pick the latest version of your module's dependencies from XWiki's Maven remote repositories. Of course if you have uncommitted changes in a dependent module, you'll want to build that module before.

Now some of the modules built by XWiki are very large (in the 40MB+ 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.

Building for a specific database

By default XWiki's Maven build will use Hypersonic SQL as the default database. If you wish to execute the build using a different database, you'll need to specify the correct database profile (-P). Right now we support 4 profiles:

  • hsqldb: Hypersonic SQL. This is the default
  • mysql: MySQL
  • pgsql: PostGreSQL
  • derby: Apache Derby
For example to build all modules for MySQL go in trunks and type mvn install -Pmysql.

Warning: Hypersonic and Derby are embedded database so you won't need anything setup to execute the build for them. However for MySQL and PostGreSQL you'll need to have the database installed, set up and running before you can run the build with their profiles.

A simple way to do this is to define the necessary properties within {HOME}/.m2/settings.xml as explained above when configuring the maven mirrors. Check the property names required by looking at the corresponding profiles section in the platform's top level pom.xml file

Building the XWiki Platform only

Go in xwiki-platform and type mvn install.

Building the XWiki Platform Core only

Go in xwiki-platform-core and type mvn install.

Building XWiki Enterprise only

Go in xwiki-product-enterprise and type mvn install. It'll build it with a default config for HSQL DB.

If you wish to build all the modules required for XWiki Enterprise and not the ones required by other products you can go at the top level and type mvn install

The functional tests are not executed by default as the take a long time to execute and are meant mostly to be executed by the Continuous Integration tool. However if you wish to run them you can execute mvn install -Pxe,ci

The installer builds are not executed by default (they are executed on the Continuous Integration server though). If you wish to run them you can execute mvn install -Pxe,ci or better, go in xwiki-product-enterprise/installers and run mvn install.

Executing the Automated Functional Tests for XWiki Enterprise

Go in xwiki-product-enterprise/distribution-test and type mvn install. By default they are executed in Firefox. To run them in a different browser, use a profile. For example to run them in IE, type mvn install -Piexplore.

See the Testing page for more details.

Executing the Standard Web WAR quickly in development mode

Go in xwiki-platform-web/standard and type mvn install -Pjettyrun. This will execute it on Jetty with a HSQLDB database located in xwiki-platform-web/standard/database (we need to improve the build to locate it elsewhere). So fi you want to have any content displayed you'll need to put a HSQLDB there or simply import a XAR.

If you wish to use another database like MySQL, run mvn install -Pjettyrun,mysql. See the section above on building XWiki for a specific database for more information.

Once the build has started Jetty, open your browser and point it to http://localhost:8080/xwiki.

To debug in this mode, run MAVEN_OPTS='-Xdebug -Xnoagent -Djava.compiler=NONE -Xrunjdwp:transport=dt_socket,address=5005,server=y,suspend=n' mvn install -Pjettyrun and attach you IDE to this process as in Debugging.

Note that this is a quick way of starting XWiki in development mode. However the real test is to start the XWiki Enterprise standalone distribution to ensure that everything works. This is achieved by running mvn install in xwiki-product-enterprise/.

Building XEclipse

Warning: You'll need Eclipse 3.3.x (or above) and an associated PDE (Plugin Development Environment) in order to build XEclipse from source.

This section is about building XEclipse with maven. For instructions on how to build XEclipse from right within the Eclipse IDE, you may refer to [Building in Eclipse]

Building XEclipse as an Eclipse plugin

Change directory to plugins/org.xwiki.eclipse
Run mvn install -DeclipseInstall=$ECLIPSE_DIR

Builing XEclipse as a standalone application

You will need the pde-maven-plugin. Once this maven plugin is installed, please refer to plugins/org.xwiki.eclipse.rcp/README for further information about building instructions.

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. For example for building XWiki Products - Curriki - Database one seems to need MAVEN_OPTS=-Xmx100m or higher.

Installer builds need maven 2.1 snapshot

The installer build need maven 2.1 snapshot and MAC for the icons to work fine.

Error in Windows installer build: Windres error

Launch4J is using a binary called Windres which requires that the environment is NOT set to use UTF-8. If you get the following error check your LANG environment variable:

Embedded error: net.sf.launch4j.BuilderException: net.sf.launch4j.ExecException: Exec failed(1): /var/tmp/installers/windows/target/dependency/bin/windres --preprocessor=cat -J rc -O coff -F pe-i386 /tmp/launch4j10018rc /tmp/launch4j10019o

Building behind a proxy.

If you are connecting to Internet through a proxy then you need to modify your 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>

Building in Eclipse

Building in IntelliJ IDEA

Version 28.1 last modified by LudovicDubost on 09/07/2008 at 22:09

Comments 0

No comments for this document

Attachments 1

ZIP
apache-maven-2.1-SNAPSHOT.zip 1.2
PostedBy: VincentMassol on 03/04/2008 (2Mb )

Creator: VincentMassol on 2007/11/26 17:16
This wiki is licensed under a Creative Commons license
1.4.1.10194