Building GeoTools

本文档提供从源代码构建 GeoTools 的说明。它涵盖先决条件、构建方法和常见构建配置,以帮助开发人员使用 GeoTools 代码库。有关发布流程的信息,请参阅 Release Process。

先决条件

在构建 GeoTools 之前,您需要使用以下组件设置开发环境:

Java Development Kit (JDK)

GeoTools 具有特定的 JDK 要求:

Java 11 - GeoTools 21.x 及更高版本的最低要求
Java 17 - GeoTools 27.x 及更高版本所需(已测试 OpenJDK)

开发 GeoTools 时,配置您的环境以:

在 IDE 中生成 Java 11 兼容代码
使用 source=11 配合 Maven

100%

Maven

Maven 是用于 GeoTools 的构建系统。至少需要 Maven 3.x 来构建项目。

安装先决条件

提供多种安装选项:

SDKMAN! (推荐用于 Linux/macOS)

# 安装 JDK 11
sdk install java 11.0.20.1-tem

# 安装 Maven
sdk install maven

包管理器

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

直接下载
- 从 Adoptium 下载 JDK
- 从 maven.apache.org 下载 Maven
- 为两者设置环境变量

获取源代码

要构建 GeoTools,首先需要获取源代码:

# 克隆存储库
git clone https://github.com/geotools/geotools.git
cd geotools

存储库包含这些分支:

main - 当前开发版本
x.y 分支(例如 27.x, 28.x) - 稳定和维护版本

构建 GeoTools

基本构建

对于您的第一次构建,运行:

mvn install

此命令:

下载所需的依赖项(仅第一次)
编译代码
运行测试
将构件安装到本地 Maven 存储库(~/.m2/repository)

成功构建将显示:

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

注意:第一次构建需要更长时间(20-30 分钟),因为需要下载依赖项。

常见构建命令

以下是 GeoTools 常用的 Maven 命令:

命令	描述
`mvn install`	构建并将所有模块安装到本地存储库
`mvn install -Dall`	构建所有模块,包括实验性模块
`mvn install -DskipTests`	构建而不运行测试(更快)
`mvn clean install`	构建前清理(完全重新构建)
`mvn -o install`	以离线模式构建(首次构建后更快)
`mvn install -T 2C`	使用并行线程构建(每个核心 2 个线程)

构建特定模块

要构建单个模块:

# 更改到模块目录
cd modules/library/main

# 仅构建此模块
mvn install

只要您之前进行了完整构建,使依赖项可用,这就可以工作。

Maven 配置文件和构建选项

100%

构建所有模块

GeoTools 包含默认不构建的"不受支持"的实验性模块。要构建所有内容:

mvn install -Dall

-Dall 开关启用几个配置文件:

配置文件	描述	包含在 `-Dall` 中
`-Ppending`	实验性模块	✓
`-Praster`	Coverage 工具	✓
`-Pgeometry`	ISO 19107 几何实现	✓
`-Pswing`	Swing 组件	✓
`-Pwps`	WPS 客户端	✓
`-Pprocess`	几何、栅格和要素处理	✓
`-Parchive`	不再工作的模块	✗

更快的构建

为了更快的开发迭代:

并行构建 - 使用多个 CPU 核心:

mvn install -T 2C  # 每个核心使用 2 个线程

跳过测试 - 构建测试但不运行它们:
```
mvn install -DskipTests
```
1
离线模式 - 避免检查远程存储库:
```
mvn -o install
```
1
最快构建 - 结合所有优化:
```
mvn install -DskipTests -o -T 2C
```
1

恢复失败的构建

如果构建失败,您可以从特定模块恢复:

mvn install -rf modules/library/data

这将继续从指定模块,而不重新构建成功的模块。

测试

运行测试

要为模块运行测试:

cd modules/library/main
mvn test

要运行单个测试:

mvn -Dtest=Rendering2DTest test

特殊测试类别

GeoTools 有几个特殊的测试类别:

类别	命令	描述
在线测试	`mvn test -P online`	需要网络连接的测试
图像测试	`mvn test -P interactive.image`	具有视觉确认的测试
交互式测试	`mvn test -P interactive.tests`	具有 GUI 组件的测试
压力测试	`mvn test -P stress`	长时间运行的性能测试

在线测试可能需要 ~/.geotools/ 目录中的配置文件。

故障排除常见构建问题

Maven Javadoc 插件问题

如果您看到缺少 org.geotools.maven:javadoc:jar 的错误,请手动构建它:

cd build/maven/javadoc
mvn install

然后返回根目录并继续您的构建。

Windows 文件删除错误

Windows 索引服务可能与 Maven 冲突。如果您看到"无法删除目录"错误,请为您的 GeoTools 目录禁用 Windows 索引服务。

内存问题

增加 Maven 的内存分配:

# Windows
set MAVEN_OPTS=-Xmx512M

# Linux/macOS
export MAVEN_OPTS="-Xmx512M"

构建分发包

GeoTools 可以为发布构建几个分发包:

100%

要构建分发包:

cd release
mvn assembly:single

这将在 target 目录中创建:

geotools-[version]-bin.zip - 包含所有 JAR 的二进制分发包
geotools-[version]-userguide.zip - 用户指南文档
geotools-[version]-src.zip - 源代码分发包

您可以使用以下内容测试二进制分发包:

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

创建可执行应用程序

对于使用 GeoTools 创建独立应用程序,请使用 Maven Shade Plugin 而不是 Assembly Plugin。Shade Plugin 正确合并 GeoTools 所需的 META-INF/services 文件。

构建可执行 JAR 的 POM 配置示例:

<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>
                <!-- 筛选已签名的 JAR -->
                <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>
                    <!-- 设置主类 -->
                    <transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
                        <mainClass>org.geotools.demo.Quickstart</mainClass>
                    </transformer>
                    <!-- 合并服务文件 -->
                    <transformer implementation="org.apache.maven.plugins.shade.resource.ServicesResourceTransformer"/>
                </transformers>
            </configuration>
        </execution>
    </executions>
</plugin>

获取帮助

如果您在构建 GeoTools 时遇到问题:

查看 GeoTools 用户指南
在 geotools-users 邮件列表上提问
加入 Matrix/Gitter 上的开发者聊天

有关商业支持选项,请参阅支持页面了解详情。

Building GeoTools ​

先决条件 ​

Java Development Kit (JDK) ​

Maven ​

安装先决条件 ​

获取源代码 ​

构建 GeoTools ​

基本构建 ​

常见构建命令 ​

构建特定模块 ​

Maven 配置文件和构建选项 ​

构建所有模块 ​

更快的构建 ​

恢复失败的构建 ​

测试 ​

运行测试 ​

特殊测试类别 ​

故障排除常见构建问题 ​

Maven Javadoc 插件问题 ​

Windows 文件删除错误 ​

内存问题 ​

构建分发包 ​

创建可执行应用程序 ​

获取帮助 ​

Building GeoTools

先决条件

Java Development Kit (JDK)

Maven

安装先决条件

获取源代码

构建 GeoTools

基本构建

常见构建命令

构建特定模块

Maven 配置文件和构建选项

构建所有模块

更快的构建

恢复失败的构建

测试

运行测试

特殊测试类别

故障排除常见构建问题

Maven Javadoc 插件问题

Windows 文件删除错误

内存问题

构建分发包

创建可执行应用程序

获取帮助