web-server/doc/en/developer/source/maven-guide/index.rst

.. _maven_guide:

Maven Guide
===========

A reference for building GeoServer with Maven.

Installing Maven
----------------

See :ref:`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 recommended. 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 not necessary.

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 :ref:`profiles <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

.. _profiles:

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 an 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 modules::

   -Plegacy
   
To include remote tests::

   -PremoteOwsTests

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

   -Pupload
   -Pwps
   -Pproxy

Generating test coverage reports
--------------------------------

Test coverage reports can be generated by running tests with the `jacoco` profile enabled::

   mvn test -Pjacoco

Coverage reports are generated in the `target/site/jacoco` directory of each module.

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

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=../../../data/release

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.

This can also be used when running the local jetty application server:

  mvn jetty:run -DconfigId=release -DconfigDirectory=../../../data/release

You may also use an absolute path, if you have a custom data directory you would like to use.