Building GeoTools

This document provides instructions for building GeoTools from source code. It covers prerequisites, building methods, and common build configurations to help developers work with the GeoTools codebase. For information about the release process, see Release Process.

Prerequisites

Before you can build GeoTools, you'll need to set up your development environment with the following components:

Java Development Kit (JDK)

GeoTools has specific JDK requirements:

• Java 11 - Minimum required for GeoTools 21.x and above
• Java 17 - Required for GeoTools 27.x and above (OpenJDK tested)

When developing GeoTools, configure your environment to:

• Produce Java 11 compliant code in your IDE
• Use source=11 with Maven

100%

Maven

Maven is the build system used for GeoTools. A minimum of Maven 3.x is required to build the project.

Installing Prerequisites

Multiple installation options are available:

1. SDKMAN! (Recommended for Linux/macOS)

   # Install JDK 11
   sdk install java 11.0.20.1-tem
   
   # Install Maven
   sdk install maven

2. Package Manager

   # Ubuntu example
   sudo apt-get update
   sudo apt-get install openjdk-11-jdk maven

3. Direct Download

   • Download JDK from Adoptium
   • Download Maven from maven.apache.org
   • Setup environment variables for both

Getting the Source Code

To build GeoTools, you first need to obtain the source code:

# Clone the repository
git clone https://github.com/geotools/geotools.git
cd geotools

The repository contains these branches:

• main - Current development version
• x.y branches (e.g., 27.x, 28.x) - Stable and maintenance versions

Building GeoTools

Basic Build

For your first build, run:

mvn install

This command:

1. Downloads required dependencies (first time only)
2. Compiles the code
3. Runs tests
4. Installs artifacts to your local Maven repository (~/.m2/repository)

A successful build will show:

[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------

Note: The first build takes longer (20-30 minutes) due to dependency downloads.

Common Build Commands

Here are frequently used Maven commands for GeoTools:

Command	Description
mvn install	Build and install all modules to local repository
mvn install -Dall	Build all modules, including experimental ones
mvn install -DskipTests	Build without running tests (faster)
mvn clean install	Clean before building (complete rebuild)
mvn -o install	Build in offline mode (faster after first build)
mvn install -T 2C	Build with parallel threads (2 threads per core)

Building Specific Modules

To build an individual module:

# Change to the module directory
cd modules/library/main

# Build just this module
mvn install

This works as long as you've previously done a full build so dependencies are available.

Maven Profiles and Build Options

100%

Building All Modules

GeoTools contains "unsupported" experimental modules not built by default. To build everything:

mvn install -Dall

The -Dall switch enables several profiles:

Profile	Description	Included with -Dall
-Ppending	Experimental modules	✓
-Praster	Coverage tools	✓
-Pgeometry	ISO 19107 geometry implementations	✓
-Pswing	Swing components	✓
-Pwps	WPS client	✓
-Pprocess	Geometry, raster and feature processes	✓
-Parchive	Modules that no longer work	✗

Faster Builds

For faster development iterations:

1. Parallel Builds - Use multiple CPU cores:

   mvn install -T 2C  # Use 2 threads per core

2. Skip Tests - Build tests but don't run them:

   mvn install -DskipTests

3. Offline Mode - Avoid checking remote repositories:

   mvn -o install

4. Fastest Build - Combine all optimizations:

   mvn install -DskipTests -o -T 2C

Resuming a Failed Build

If your build fails, you can resume from a specific module:

mvn install -rf modules/library/data

This continues from the specified module without rebuilding successful ones.

Testing

Running Tests

To run tests for a module:

cd modules/library/main
mvn test

To run a single test:

mvn -Dtest=Rendering2DTest test

Special Test Categories

GeoTools has several special test categories:

Category	Command	Description
Online tests	mvn test -P online	Tests requiring network connections
Image tests	mvn test -P interactive.image	Tests with visual confirmation
Interactive tests	mvn test -P interactive.tests	Tests with GUI components
Stress tests	mvn test -P stress	Long-running performance tests

Online tests may require configuration files in ~/.geotools/ directory.

Troubleshooting Common Build Issues

Maven Javadoc Plugin Issues

If you see an error about missing org.geotools.maven:javadoc:jar, build it manually:

cd build/maven/javadoc
mvn install

Then return to the root directory and continue your build.

Windows File Deletion Errors

Windows Indexing Service can conflict with Maven. If you see "unable to delete directory" errors, disable Windows Indexing Service for your GeoTools directory.

Memory Issues

Increase Maven's memory allocation:

# Windows
set MAVEN_OPTS=-Xmx512M

# Linux/macOS
export MAVEN_OPTS="-Xmx512M"

Building Distribution Packages

GeoTools can build several distribution packages for releases:

100%

To build the distribution packages:

cd release
mvn assembly:single

This creates in the target directory:

• geotools-[version]-bin.zip - Binary distribution with all JARs
• geotools-[version]-userguide.zip - User guide documentation
• geotools-[version]-src.zip - Source code distribution

You can test the binary distribution with:

unzip target/geotools-*-bin.zip
cd geotools-*/
java -cp "lib/*" org.geotools.util.factory.GeoTools

Creating Executable Applications

For creating standalone applications with GeoTools, use the Maven Shade Plugin rather than the Assembly Plugin. The Shade Plugin correctly merges the META-INF/services files needed by GeoTools.

Example POM configuration for building an executable JAR:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-shade-plugin</artifactId>
    <version>3.5.1</version>
    <executions>
        <execution>
            <phase>package</phase>
            <goals>
                <goal>shade</goal>
            </goals>
            <configuration>
                <!-- Filter signed JARs -->
                <filters>
                    <filter>
                        <artifact>*:*</artifact>
                        <excludes>
                            <exclude>META-INF/*.SF</exclude>
                            <exclude>META-INF/*.DSA</exclude>
                            <exclude>META-INF/*.RSA</exclude>
                        </excludes>
                    </filter>
                </filters>
                <shadedArtifactAttached>true</shadedArtifactAttached>
                <transformers>
                    <!-- Set main class -->
                    <transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
                        <mainClass>org.geotools.demo.Quickstart</mainClass>
                    </transformer>
                    <!-- Merge service files -->
                    <transformer implementation="org.apache.maven.plugins.shade.resource.ServicesResourceTransformer"/>
                </transformers>
            </configuration>
        </execution>
    </executions>
</plugin>

Getting Help

If you encounter problems building GeoTools:

1. Check the GeoTools User Guide
2. Ask on the geotools-users mailing list
3. Join the developer chat on Matrix/Gitter

For commercial support options, see the support page for details.