Maven Guide

A reference for building GeoServer with Maven.

Installing Maven

See Tools.

Running Maven

Maven provides a wide range of commands used to do everything from compiling a module to generating test coverage reports. Most maven commands can be run from the root the source tree, or from a particular module.

Note

When attempting to run a maven command from the root of the source tree remember to change directory from the root the checkout into the src directory.

When running a command from the root of the source tree, or from a directory that contains other modules the command will be run for all modules. When running the command from a single module, it is run only for that module.

Building

The most commonly maven command used with GeoServer is the install command:

mvn clean install

While the clean command is not necessary, it is recommented. Running this command does the following:

  • compiles source code
  • runs unit tests
  • installs artifacts into the local maven repository

Skipping tests

Often it is useful to skip unit tests when performing a build. Adding the flag -DskipTests to the build command will only compile unit tests, but not run them:

mvn -DskipTests clean install

Building offline

Maven automatically downloads dependencies declared by modules being built. In the case of SNAPSHOT dependencies, Maven downloads updates each time it performs the first build of the day.

GeoServer depends on SNAPSHOT versions of the GeoTools library. The automatic download can result in lengthy build time while Maven downloads updated GeoTools modules. If GeoTools was built locally, these downloads are unecessary.

Also, if GeoTools is being modified locally, then the local versions rather than SNAPSHOT versions of modules should be used.

This can be remedied by running maven in “offline mode”:

mvn -o clean install

In offline mode Maven will not download external dependencies, and will not update SNAPSHOT dependencies.

Building extensions

By default, extensions are not included in the build. They are added to the build explicitly via profiles. For example the following command adds the restconfig extension to the build:

mvn clean install -P restconfig

Multiple extensions can be enabled simultaneously:

mvn clean install -P restconfig,oracle

A special profile named allExtensions enables all extensions:

mvn clean install -P allExtensions

Recover Build

  • After fixing a test failure; you can “resume” from a specific point in the build:

    mvn install -rf extension/wps
  • Recover from a 301 Redirect

    A long standing bug in Maven from 2.0.10 handling of 301 errors when a artifact has been moved. The work around is to run Maven with the option:

    mvn install -Dmaven.wagon.provider.http=httpclient

    This is not a common issue.

Profiles

Additional profiles are defined in the pom.xml files providing optional build steps. Profiles are directly enabled with the -P flag, others are automatically activated based on platform used or a -D property being defined.

To build the release module as part of your build:

-Drelease

To include remote tests:

-PremoteOwsTests

Profiles are also used manage optional extensions community plugins:

-Pproxy
-Poracle
-Pupload
-Pwps

Additional profiles are defined in the pom.xml files providing optional build steps. Profiles are directly enabled with the -P flag, others are automatically activated based on platform used or a -D property being defined.

To build javadocs with UML graph:

-Duml

To build the release module as part of your build:

-Drelease

To include the legacy moduled:

-Plegacy

To include remote tests:

-PremoteOwsTests

Profiles are also used manage several of the optional community plugins:

-Pupload
-Pwps
-Pproxy

Eclipse

The maven eclipse plugin is used to generate eclipse projects for a set of modules:

mvn eclipse:eclipse

After which the modules can be imported into an eclipse workspace.

A useful feature of the plugin is the ability to download associated source code for third party dependencies. This is done with the downloadSources flag:

mvn -DdownloadSources eclipse:eclipse

Warning

The first time you enable the downloadSources flag the build will take a long time as it will attempt to download the sources for every single library GeoServer depends on.

Building the web module

When the web module is installed, it does so with a particular configuration built in. By default this is the minimal configuration. However this can be customized to build in any configuration via the configId and configDirectory flags. For example:

mvn clean install -DconfigId=release -DconfigDirectory=/home/jdeolive/geoserver_1.7.x/data

The above command builds the web module against the release configuration that is shipped with GeoServer. The configId is the name of the configuration directory to include, and the configDirectory is the parent directory of the configuration directory to include. The configDirectory can either be specified as an absolute path like in the above example, or it can be specified relative to the web module itself:

mvn clean install -DconfigId=release -DconfigDirectory=../../../data

The above command does the same as the first, however references the configDirectory relative to the web module. This path, ../../../data, can be used if the GeoServer checkout has the standard layout.

Running the web module with Jetty

The maven jetty plugin can be used to run modules which are web based in an embedded Jetty container:

cd geoserver_2.0.x/src/web/app
mvn jetty:run

Note

This command must be run from the web/app module, it will fail if run from elsewhere.

The above command will run GeoServer with the built in data directory. To specify a different data directory the GEOSERVER_DATA_DIR flag is used:

mvn -DGEOSERVER_DATA_DIR=/path/to/datadir jetty:run

Installing the Oracle module

To configure GeoServer to include the Oracle datastore extension module, do the following:

Obtain the appropriate Oracle JDBC driver (possibly by downloading from Oracle or from the Geoserver ORACLE-extension on http://geoserver.org/display/GEOS/Stable). Install it in the Maven repository using the command:

mvn install:install-file -Dfile=ojdbc14.jar -DgroupId=com.oracle -DartifactId=ojdbc14 -Dversion=10.2.0.3.0 -Dpackaging=jar -DgeneratePom=true

Configure the Eclipse project using:

mvn -P oracle,oracleDriver eclipse:eclipse

(The oracle profile includes the GeoServer Oracle module, while the oracleDriver profile includes the proprietary Oracle JDBC driver. These are separate because there are situations where the Oracle JDBC JAR should not be included with the build.)

Finally, in Eclipse import the oracle module project. Refresh the web-app project to configure the dependency on the oracle project.

When GeoServer is run, Oracle should be provided as a Vector Data Source on the New Data source page

Previous: Quickstart