GeoServer Development Setup
- Obtain a Git client
- SourceTree is recommended for Windows; it comes with a command-line interface
- Linux has
git for command-line and
gitk for graphical history display
- Configure your identity
git config --global user.name "Your Real Name"
git config --global user.email Your.Real.Name@example.org
- Configure your line ending settings
- (Optional) Make a GitHub account
Java 7 JDK
Apache Maven 3
- Obtain Apache Maven 3
- Avoid Linux distribution packages as these have been notoriously broken in the past (yes, Ubuntu, we mean you)
- A script or batch file on your path may ease command line use and avoid contaminating your global environment
- On Windows a batch file (
set JAVA_HOME=C:\Program Files\Java\jdk1.7.0_your_jdk_build_number_goes_here
set M2_HOME=C:\Program Files\maven3
set MAVEN_OPTS="-Xmx1024m -XX:MaxPermSize=128m"
mvn -llr %*
- On Linux (
export MAVEN_OPTS="-Xmx1024m -XX:MaxPermSize=128m"
exec mvn -llr "$@"
- Adjust for your memory/performance requirements
- Obtain a shell or command prompt
- Check that your correct Maven and JDK versions are shown with:
- Obtain Eclipse JEE
- JEE strongly recommended as it contains server debugging support and XML editors
- Eclipse Luna works
- Clone these Git repositories:
git clone -o geotools https://github.com/geotools/geotools
git clone -o geowebcache https://github.com/GeoWebCache/geowebcache
git clone -o geoserver https://github.com/geoserver/geoserver
- You can later fork these on GitHub and add your forks as new remotes:
git remote add yourgithubusername email@example.com:yourgithubusername/repositoryname.git
Build these projects sequentially, in this order.
-llr (in the script at the top) stops Maven from remembering from where it downloaded an artifact; this turns off a poorly thought-out feature of Maven
-B specified batch mode and prevents log-filling download progress information
-nsu stops Maven from downloading unwanted remote SNAPSHOTs that were built after your local build and also makes builds faster as SNAPSHOT require a remote resource check
-Djava.awt.headless=true ensures all interactivity is disabled
-Dtest.maxHeapSize=256m not strictly necessary unless unit tests fail by running out of heap in which case increase this limit
-Dtest.maxPermSize=128m not strictly necessary unless unit tests fail by running out of permgen in which case increase this limit
-DdownloadSources=true download source jars to make Eclipse debugging much, much better
-Dall build all GeoTools modules
-DconfigDirectory../../../data= combined with
-Prelease ensures that the release demo data is available when debugging GeoServer in Eclipse
-PallExtension build all GeoServer extensions
-Papp-schema add app-schema to the GeoServer
gs-web-app module path so the app-schema module is available in Eclipse
-Prelease build all modules required for a GeoServer release (required before running
mvn assembly:attached to build release bundles) and use the release data in Eclipse
- More information on the Jenkins page:
- Import the GeoTools formatter settings into Eclipse in Preferences / Java / Code Style / Formatter from the GeoTools working directory:
- These settings use four-space indenting and never tabs; they are otherwise very close to the Sun Java Code Conventions.
- Change your XML Editor preferences to use four-space indenting and never tabs.
Old sections yet be be refactored
Use Maven to build and configure Eclipse projects
Maven is used to retrieve the >140 jar dependencies and store them in a local repository. This will take some time. Maven must be run in a directory with a
file (for GeoServer this is a subdirectory).
Change into each of the directories and use the command for a full rebuild:
mvn -Dtest.maxHeapSize=768m -DdownloadSources=true -Dall -Pwebservice clean install eclipse:clean eclipse:eclipse
mvn -Dtest.maxHeapSize=768m -DdownloadSources=true -PallExtensions -Poracle -Papp-schema -Pwebservice clean install eclipse:clean eclipse:eclipse
- Maven goals are executed for each module in the order given. Eclipse goals are last to leave workspace alone if tests fail.
-Dtest.maxHeapSize=256m restricts unit test JVM heap size to 256m, for consistency with OpenGeo and Computational Geoscience continuous integration. Use this if you want your builds to behave the same way, so you are not surprised by an unexpected build failure when the build succeeds on your desktop. This option will also make unit tests fail on 64-bit JVMs.
-Dtest.maxHeapSize=1024m may be required to get some tests to pass under a 64-bit JVM. This might no longer be the case since Gabriel and Rini put app-schema on a diet. :-P
-Dall for GeoTools ensures all optional modules are built. This allows you to detect when any changes you make break an optional supported module. It also gives you access to the new generation of JDBC DataStores. You will need this later when you include Oracle support for GeoServer.
-Pwebservice in GeoTools enables the unsupported webservice module. This option can be left out by those who just want to use app-schema, but core app-schema developers should use this module to ensure they do not break the webservice module. (Our buildbot uses this option). The same option in GeoServer is used to build the community/app-schema/webservice-test module, which is the corresponding unit tests for the GeoTools webservice module.
-PallExtensions for GeoServer ensures all optional extensions are built. This allows you to detect when any changes you make break an optional supported extension.
-Poracle for GeoServer includes Oracle support in the web application.
-Papp-schema ensures app-schema support is included in Eclipse dependencies for the GeoServer
web-app module for debugging, and in the GeoServer deployment bundle.
-Psqlserver is required in GeoServer if you need Microsoft SQL Server support. See details at GeoserverMsSqlServerConnectivity.
-DdownloadSources=true is always optional. This downloads sources for dependencies, where available. Maven attaches source in Eclipse projects, allowing source browsing into dependencies. This is very useful for debugging in Eclipse. One downside is it will make Maven slower because it will check for updated source for every dependency, for every module. You may wish to use it only now and then.
- If no pom files or dependencies have changed, you can omit the
-Dorg.geotools.image.test.enabled=true may be specified if you want to perform optional perceptual diff tests for app-schema WMS support. These will only actually be performed if perceptual diff is in fact installed on your computer. This option is particularly recommended if you are (possibly) modifying the app-schema wms functionality.
-o can be added to run offline. This will make the build faster by not checking for updated remote artifacts. You can use this flag if you are rerunning a build shortly after running an online build.
-DskipTests=true can be added to skip tests, making the build process much, much faster. Tests are there to help you detect problems, so avoid skipping them. Never commit anything to the subversion repository without running all tests, or you risk breaking the build. Skipping tests will also cause test artifacts to not be built, and break dependencies on test artifacts.
- -Papp-schema-online-test enable online testing profile. Please read AppSchemaTestDatabase to prepare your databases for the app-schema online tests suite. More information can be found http://docs.geoserver.org/latest/en/developer/programming-guide/app-schema/index.html
GeoServer WAR built with application schema support
The Maven build process described above creates a GeoServer WAR file:
This WAR file is ready for deployment in a servlet context. It has a minimal (i.e. empty) configuration.
Add Maven repository to Eclipse build path
Eclipse needs to find the Maven-downloaded jars for compilation. Under Preferences > Java > Build Path > Classpath Variables I added an entry called
M2_REPO set to
.m2\repository directory in my home directory (this is my local Maven repository).
I created separate Eclipse workspaces for GeoServer and GeoTools called
When working with external tools it can be easier to have Eclipse automatically refresh its state to reflect filesystem changes.
- You can go to Preferences > General > Workspace and select Refresh automatically.
- To prevent Eclipse from fighting with Maven, shut down Eclipse during a Maven compile or Maven install, otherwise Maven pre-build clean will trigger a concurrent Eclipse build.
- During unit tests Subclipse will go insane trying to get revision history as the test modifies the filesystem. This annoyed me enough to turn off auto-refresh.
If you leave auto-refresh turned off, you need to select all projects and press F5 to get Eclipse to recognise changes.
A working set is a group of elements shown in the different Eclipse views. Working sets are used to clearly separating projects. This can become a very useful feature when you are working simultaneously in many non-directly related projects. Organising your different project groups in working sets will speed up the process of finding the desired elements and will decrease the view visual clutter.
To define a working set, click the Package Explorer
menu icon (the inverted triangle) and select Configure Working Set
. Here you will be able to create a new working set and to select its related resources, as well as to edit or remove existing working sets. Every available working set will be shown the next time you click on the view triangular icon.
To configure GeoServer
to use a single workspace (Optional), select a workspace (or create a new one) and create working sets for both GeoServer
respectively. Under Workspace content
, select and add the desired packages. Click Finish
to confirm the changes.
Notes: All packages from every project added will be listed and a good way to determine which packages are required would be to load the project in an new instance of Eclipse
. Under Navigator
view, take note of all the packages included and add them accordingly.
To "load" the working sets, navigate to Configure Working Set
once again, and select checkbox(es) to load the desired working set(s).
Set Java 7 as default JRE for Eclipse workspace
Under Window > Preferences > Java > Installed JREs I added
(browsing under Program Files) and made it the default for the workspace.
I set the default VM arguments to:
. I found this to be sufficient heap for my purposes. The
enables any assertions that might be present.
It should be fine to use the JRE instead of the JDK. One disadvantage of the JRE is that it does not come with source for the runtime, but it is easy to attach source from the JDK. In Eclipse:
- Press Ctrl-Shift-T and open type
- If you do not see the source, press button to attach source, and select the the
src.zip in the JDK root directory (for the JDK corresponding to the JRE).
- You might need to close
Math and restart Eclipse before it recognises the source attachment.
If you use the JDK, Eclipse will find the source automagically, so you will not need the above workaround.
Set Java compiler compliance for Eclipse workspaces
- Maven should set compliance for each Eclipse project it creates, so this step should not be necessary. I use it to be robust against misconfigured modules and to make any extra projects I add consistent.
- Compiler compliance level is set under Preferences > Java > Compiler.
- Set compliance level to 1.6.
Set code formatter to use GeoTools conventions
Use the GeoTools code conventions for both GeoTools and GeoServer. The GeoTools formatter profile for Eclipse is stored in your
Import this profile into each workspace using Preferences > Java > Code Style > Formatter.
For GeoTools, you can also set the Code Templates, which include automatic generation of the copyright header in new files.
See also the GeoTools style guide (Oracle Java, spaces not tabs, width 100):
Configure Eclipse XML formatting
Make your Eclipse XML formatting style consistent with the GeoTools / GeoServer Java coding style: 100 character line width with four-space indenting. This is not an official GeoTools / GeoServer rule, but app-schema developers use a lot of XML and we care.
In your Eclipse XML Editor settings (XML > XML Files > Editor) set:
- Line Width: 100
- Indent using spaces
- Indentation size: 4
Import projects into Eclipse
This step makes Eclipse recognise the project metadata generated by Maven. Use File > Import > General > Existing Projects into Workspace:
- Import all projects from
geoserver-trunk into the
- Import all projects from
geotools-trunk into the
- After importing, you might need to restart Eclipse to ensure directories are fully refreshed (e.g. by Subclipse). Your mileage may vary.
All projects should now compile in Eclipse. To test this:
- Use Project > Clean > Clean All Projects to delete all class files.
- I have Eclipse configured Preferences > General > Workspace with Build Automatically selected (this is the default), so it then recompiles everything.
GeoServer configurations can be exported or checked out from Subversion to external directories and referenced with the
Java VM argument.
Debugging GeoServer using embedded Jetty
- The embedded Jetty application main class is
org.geoserver.web.Start in the GeoServer
web-app module (in
- Use the Debug dialog to make Java Application launch configurations for this class.
- In each Java Application launch configuration, add a VM argument
-DGEOSERVER_DATA_DIR=/wherever pointing to the location of a GeoServer configuration.
- If you want to access an Oracle Spatial database, you need add an Oracle JDBC driver (e.g.
ojdbc5.jar) to your classpath.
- The driver can be obtained from either of:
- Copy the Oracle JDBC driver to a local directory or Eclipse project in your workspace.
ojdbc5.jar on the Classpath tab of your Eclipse launch configuration.
- If you want to access a Microsoft SQL Server database, you need add a SQLJDBC driver (e.g.
sqljdbc.jar) to your classpath.
- For more information about Microsoft SQL Server JDBC Driver see:
- Copy the Microsoft SQL Server JDBC Driver to a local directory or Eclipse project in your workspace.
sqljdbc.jar on the Classpath tab of your Eclipse launch configuration.
- Debug with this launch configuration.
- You can make WFS requests in a web browser with URLs like this:
Configurations can be set in eclipse using its vm arguments: