构建 PLC4X

PLC4X 使用 Apache Maven 构建，我们已尽力使构建过程尽可能简单。

然而，PLC4X 的目标是通过一套共享的 API 与多个厂商的 PLC 进行通信，同时还需支持多种不同的语言。

我们将构建过程划分成若干部分，以便只选择感兴趣的部分。这是通过选择所谓的 Maven profiles 来实现的。关于这些内容，本手册后文会有更多介绍。

为方便起见，我们还提供了一个 Maven-Wrapper，它应当只需 Java 11 或更高版本即可完成 PLC4X 的构建。

环境要求

构建 PLC4X 的要求应该只有：

Java 11 JDK（或更高版本）
Git（即使你构建的是源码发行版，Kafka 插件似乎也需要系统 PATH 上存在 git 可执行文件）
Apache Maven（3.6.0 或更高版本）（可选）（参见下一章）

使用 Maven Wrapper

所谓的 Maven-Wrapper 是通过调用 Maven Wrapper 脚本 mvnw（Mac 和 Linux）或 mvnw.cmd（Windows），而不是默认的 Maven 命令 mvn 和 mvn.cmd 来使用的。

这些辅助脚本会确保 Maven 至少以 .mvn/maven-wrapper.properties 中定义的版本可用。如果找不到合适的版本，它会自动下载并安装到项目旁边（这样就不必每次下载，并且每个项目都可以拥有自己专属的 Maven 版本）。

在脚本确认了合适的 Maven 版本可用之后，就会使用该版本，并将所有参数透明地传递给它。因此，只需在每个 Maven 命令前加上额外的 w，其效果就应与使用预安装的 Maven 版本完全相同。

使用 Maven

本文档无法为你提供上手 Maven 本身所需的全部细节，不过网上有很多优秀的文档。

Justin McLean 和 Christofer Dutz 前些时候甚至为另一个 Apache 项目录制了一段将近 2 小时的 Maven 培训视频。

它应当涵盖了理解 Maven 及其工作原理所需的所有细节。

2016 年 Apache Flex 的 Maven 培训录像

https://vimeo.com/167857327

使用 Maven 构建 PLC4X

特别是构建 C++ 和 C# 驱动程序时，需要构建一些第三方构件，这会大幅增加构建时间，并且需要安装一些额外的第三方工具，因此我们已将这些部分从默认的 Maven 构建中排除。

可以使用以下 profile：

with-c：构建所有与 C 相关的模块
with-dotnet：构建所有与 C# 和 .NET 相关的模块
with-go：构建所有与 Go 相关的模块
with-java：构建所有与 Java 相关的模块
with-python：构建所有与 Python 相关的模块
update-code-generation：根据 mspec 定义生成生成代码

	由于这些 profile 通常需要在您的开发机上进行一些准备和设置，请阅读准备您的计算机] 指南以获取详细说明。

最小化的 Apache PLC4X 构建将只构建基本的代码生成模块，不包含对任何语言的支持：

mvn install

因此，例如如果你只想构建 Java 相关的模块，可以使用以下命令：

mvn -P with-java install

如果你想跳过测试的运行（尽管不建议这样做），你可以将它们全部跳过。

mvn -P with-java -DskipTests install

所有 Apache PLC4X 模块均通过执行以下命令来构建：

mvn -P with-c,with-dotnet,with-go,with-java,with-python install

这不仅会构建各个构件并生成 jar 文件，还会运行所有的单元测试和集成测试。

如果你想跳过测试的运行（即使我们不鼓励这样做），你可以一次性跳过全部测试。

mvn -P with-c,with-dotnet,with-go,with-java,with-python install -DskipTests

不过，这并不会跳过测试的编译。

使用 Maven 构建 PLC4X 网站

PLC4X 的网站同样位于包含代码的同一个 GIT 仓库中，它也是通过 Maven 来构建的。

要构建该网站，执行以下命令即可：

mvn site

这只是网站生成的快速入门版本，如需完整的详细文档，请阅读 Website 文档页面。

一些特殊的 Maven Profile

Maven 支持所谓的 profiles，以便在特殊情况下自定义构建。我们已尽力将 profile 的数量保持在最低水平。目前只有一个 profile。

`apache-release` profile

该 profile 在发布构建时会自动启用，并会自动创建一些额外的构件：

JavaDoc 构件
源代码构件
源码分发装配包
每个构件的 SHA512 校验和文件
每个构件的 PGP 签名文件

通常，除非你对这些构件感兴趣，否则不需要启用该 profile。

`debug-pom` profile

尤其是对于 Maven 初学者来说，要理解某个模块为何采用特定的方式构建可能并不容易。Maven 包含大量用于继承和覆盖设置的概念。

debug-pom profile 会在模块的 target 目录中生成所谓的 effective pom。

该文件包含 Maven 执行时所使用的 100% 设置。所有设置都经过继承和覆盖，所有属性都已展开为 Maven 实际使用的值。

因此，每当 Maven 的行为不符合你的预期时，只需启用该 profile，它应该能帮助你找出问题所在。

`enable-all-checks` profile

PLC4X 项目的一些测试需要相当长的时间才能运行完成。因此我们决定在开发机上的常规构建中禁用这些测试。如果你希望在本地运行它们，而不依赖于 CI 服务器来执行，请启用 enable-all-checks profile。

使用 Gradle 使用编译好的库

按照此处所述编译库，会将新版本添加到本地 Maven 仓库中（在类 Linux 系统上通常位于 ~/.m2/repository）。如果你想在项目中使用 Gradle 作为构建工具，只需在 Gradle 的 build.gradle 文件中使用一个本地仓库即可。

以下是一个示例：

repositories {
    mavenCentral()
    mavenLocal()
}

dependencies {
    implementation group: 'org.apache.plc4x', name: 'plc4j-api', version: '1.0.0'
    implementation group: 'org.apache.plc4x', name: 'plc4j-driver-s7', version: '1.0.0'
    implementation group: 'org.apache.plc4x', name: 'plc4j-connection-pool', version: '1.0.0'
}