如何借助 Graalvm 和 Picocli 构建 Java 编写的原生 CLI 应用

阅读数:2 2020 年 3 月 26 日 16:25

如何借助Graalvm和Picocli构建Java编写的原生CLI应用

本文要点:

  • 开发人员想要以单个原生可执行性文件的形式分发其命令行应用。
  • GraalVM可以将 Java 应用编译为单个原生镜像,但是它有一些限制。
  • Picocli是一个在 JVM 之上编写 CLI 应用的现代库,它有助于克服 GraalVM 的局限性,包括在 Windows 上的局限性。
  • 在 Windows 上搭建 GraalVM 工具链以创建原生镜像的过程并没有很完善的文档。
如何借助Graalvm和Picocli构建Java编写的原生CLI应用

梦想:可执行的 Java

Go 已经成为编写命令行应用的流行编程语言。这可能会有很多的原因,但是 Go 特别棒的一点在于它能够将一个程序编译为单个原生的可执行文件。这使得程序更加易于分发。

长期以来,Java 程序都难以分发,这是因为它们需要在目标机器上安装一个 Java 虚拟机。我们可以将最新的 JVM 与应用捆绑在一起,但是这样的话,包的大小会增加近 200MB。但是,事情正在往好的方向发展:Java 9 引入了 Java 模块系统(Java Module System,JPMS),其中包括了 jlink 工具,它允许应用创建自定义的、最小化的 JRE,最小可以到 30 至 40MB。Java 14 将会包括 jpackage 工具,借助该工具可以创建一个安装器(installer),它能够将这个最小化的 JRE 和应用包含在一起。

不过,对于命令行应用来讲,安装器并不理想。理想情况下,我们希望将 CLI 工具分发为“真正的”原生可执行文件,而不需要打包运行时。借助 GraalVM,我们可以让 Java 编写的程序也实现这一点。

GraalVM

GraalVM 是一个通用的虚拟机,可以运行 JavaScript、Python、Ruby、R、基于 JVM 的语言(如 Java、Scala、Clojure、Kotlin)和基于 LLVM 的语言(如 C 和 C++)所编写的应用程序。GraalVM 很有意思的一个方面在于,它允许我们混合多种编程语言:程序中的一部分可能会使用 JavaScript、R、Python 或 Ruby 编写,这些组成部分可以通过 Java 进行调用,并且可以彼此共享数据。另一个特性是创建原生镜像的能力,这也是我们将在本文中探讨的内容。

GraalVM 原生镜像

GraalVM 原生镜像允许我们提前将 Java 代码编译为一个独立的可执行文件,称为原生镜像。这个可执行文件包含了应用、库、JDK,该文件不会运行在 Java VM 上,而是包含了来自另一个不同虚拟机的必要组件,如内存管理和线程调度,该虚拟机被称为“Substrate VM”。Substrate VM 是运行时组件的名称(如 deoptimizer、垃圾收集器、线程调度等等)。相对于 Java VM,这样形成的程序会有更快的启动时间和更低的运行时内存占用。

原生镜像的限制

为了保证实现的小巧和简洁,并实现积极的前期优化,原生镜像不支持 Java 的所有特性。完整的限制可以参考项目的 GitHub 页面。

其中,有两个限制需要特别注意:

简单来讲,为了创建一个自包含的二进制文件,原生镜像编译器需要预先知道应用的所有类、它们的依赖以及它们所使用的资源。反射和资源通常需要配置。我们随后将会看到一个这样的例子。

Picocli

Picocli 是一个现代库和框架,适用于在 JVM 上构建命令行应用。它支持 Java、Groovy、Kotlin 和 Scala。它推出的时间还不到 3 年,但是非常受欢迎,每月的下载量超过了 50 万次。Groovy 语言使用它来实现其CliBuilder DSL。

Picocli 致力于提供“最简便的方式来创建富命令行应用,这种应用可以在 JVM 上和 JVM 之外运行”。它提供了彩色输出、TAB 键自动完成、子命令,与其他的 JVM CLI 相比,它还提供了一些独特的特性,比如可否定选项、重复复合参数组、重复子命令和对引用参数的复杂处理。它的源代码在单个文件中,因此我们可以选择将其作为源代码包含进来,避免添加依赖项。Picocli 对其丰富和细致的文档颇感自豪。

如何借助Graalvm和Picocli构建Java编写的原生CLI应用

Picocli 用到了反射,因此很容易受到 GraalVM 的 Java 原生镜像的限制,但是它提供了一个注解处理器,该处理器会生成配置文件,从而解决了编译期的限制。

具体的例子

接下来,我们看一个命令行工具的具体样例,它将会使用 Java 编写并编译为单个原生可执行文件。在这个过程中,我们将会看到 picocli 库的一些特性,它们有助于让我们的工具更易于使用。

我们将会构建一个checksum CLI 工具,它能够接收一个名为-a--algorithm的选项和一个表示位置的参数,该参数表示要计算校验和的文件。

我们希望用户能够像使用 C++ 或其他语言编写的应用那样来使用我们的 Java checksum工具。大致如下所示:

复制代码
$ echo hi > hi.txt
$ checksum -a md5 hi.txt
764efa883dda1e11db47671c4a3bbd9e
$ checksum -a sha1 hi.txt
55ca6286e3e4f4fba5d0448333fa99fc5a404a73

这是对命令行应用的最低期望,但是我们不会满足于这种最小公分母式的应用,而是会创建一个让用户满意的出色 CLI 应用。那这意味着什么,我们又该如何实现呢?

出色的应用是有帮助的

我们做出了一些权衡:选择了命令行界面(command line interface,CLI),而不是图形化用户界面(graphical user interface,GUI),这意味着应用对新用户来说并不太易于学习如何使用。我们可以通过提供良好的在线帮助来部分弥补这一不足。

在用户通过-h--help选项请求帮助或者使用了非法的用户输入时,我们的应用应该展示帮助信息。当带有V--version选项的时候,它应该展示版本信息。接下来,我们会看到 picocli 是如何简化该过程的。

用户体验

通过在支持的平台上使用彩色输出,我们可以让应用对用户更加友好。这不仅仅是看上去更漂亮,还能减少用户的认知负担:这种对比会使重要的信息,如命令、选项和参数,能够从周围的文本突出显示出来。

基于 picocli 的应用所生成的帮助信息默认就会使用彩色输出。我们的checksum样例看上去如下所示:

如何借助Graalvm和Picocli构建Java编写的原生CLI应用

一般而言,应用只有在交互式使用的时候才会输出彩色文本,当执行脚本时,我们不希望日志文件和 ANSI 转义代码混杂在一起。幸运的是,picocli 会自动帮我们处理这个问题。这引入了下一个话题:好的 CLI 应用都设计为能够与其他命令组合使用。

出色的 CLI 应用能够与其他应用协作

Stdout 与 stderr

很多的 CLI 工具都使用标准 I/O 流,这样的话,它们就可以与其他的工具进行组合。通常,细节决定成败。当用户请求帮助的时候,应用应该将使用帮助信息打印到标准输出中。这允许用户将输出以管道的方式输入到其他工具中,如grepless

另一方面,当遇到非法输入的时候,错误信息和使用帮助信息应该打印到标准错误流中:如果我们程序的输出作为其他程序的输入的话,我们不希望错误信息破坏其他的程序。

退出码

当程序结束的时候,它会返回一个退出状态码。通常来讲,值为零的退出码用来表示成功,而非零的退出码则用来表示某种类型的失败。

这就允许用户通过使用&&将多个命令连接在一起,并且在这个序列中如果有命令失败的话,整个序列都会停止。

默认情况下,对于非法的用户输入,picocli 会返回2,而对于应用的业务逻辑中出现的异常则会返回1,否则返回零(一切正常)。当然,在应用中配置其他的退出码是很容易的,但是对于checksum样例来说,默认值就是可以的。

注意,picocli 库并不会调用System.exit,它只是返回一个整数,应用要负责确定是否调用System.exit

紧凑的代码

在上面的章节中,我们描述了很多的功能。你可能会认为需要大量的代码才能完成它们,但是大多数“标准的 CLI 行为”都是由 picocli 库提供的。在我们的应用中,我们所需要做的就是定义选项和位置参数,并通过将类定义为CallableRunnable来实现我们的业务逻辑。在 main 方法中,我们用一行代码就能启动应用:

复制代码
import picocli.CommandLine;
import picocli.CommandLine.Command;
import picocli.CommandLine.Option;
import picocli.CommandLine.Parameters;
import java.io.File;
import java.math.BigInteger;
import java.nio.file.Files;
import java.security.MessageDigest;
import java.util.concurrent.Callable;
@Command(name = "checksum", mixinStandardHelpOptions = true,
version = "checksum 4.0",
description = "Prints the checksum (MD5 by default) of a file to STDOUT.")
class CheckSum implements Callable<Integer> {
@Parameters(index = "0", arity = "1",
description = "The file whose checksum to calculate.")
private File file;
@Option(names = {"-a", "--algorithm"},
description = "MD5, SHA-1, SHA-256, ...")
private String algorithm = "MD5";
// 本样例实现了 Callable,所以解析、错误处理以及对使用帮助或版本帮助的用户请求处理
// 都可以在一行代码中实现。
public static void main(String... args) {
int exitCode = new CommandLine(new CheckSum()).execute(args);
System.exit(exitCode);
}
@Override
public Integer call() throws Exception { // the business logic...
byte[] data = Files.readAllBytes(file.toPath());
byte[] digest = MessageDigest.getInstance(algorithm).digest(data);
String format = "%0" + (digest.length*2) + "x%n";
System.out.printf(format, new BigInteger(1, digest));
return 0;
}
}

我们已经有了一个理想的 Java 工具程序。接下来,我们看一下如何将其转换成一个原生的可执行文件。

原生镜像

对于反射的配置

我们在前面提到过,原生镜像编译器有一些限制:支持反射,但是需要配置

这会影响基于 picocli 的应用:在运行时,picocli 会使用反射去发现所有@Command注解标注的子命令,以及@Option@Parameters注解标注的命令选项和位置参数。

因此,我们需要向 GraalVM 提供一个配置文件,指明所有带注解的类、方法和字段。这样的配置文件如下所示:

复制代码
[
{
"name" : "CheckSum",
"allDeclaredConstructors" : true,
"allPublicConstructors" : true,
"allDeclaredMethods" : true,
"allPublicMethods" : true,
"fields" : [
{ "name" : "algorithm" },
{ "name" : "file" }
]
},
{
"name" : "picocli.CommandLine$AutoHelpMixin",
"allDeclaredConstructors" : true,
"allPublicConstructors" : true,
"allDeclaredMethods" : true,
"allPublicMethods" : true,
"fields" : [
{ "name" : "helpRequested" },
{ "name" : "versionRequested" }
]
}
]

对于有很多选项的工具来说,这样很快就会变得非常繁琐,但幸运的是,我们并不需要手工来完成这项任务。

Picocli 注解处理器

picocli-codegen模块包含了一个注解处理器,它能够根据 picocli 注解在编译期就构建好一个模型,而不是在运行期。

在编译时,注解处理器会在META-INF/native-image/picocli-generated/$project目录生成 Graal 配置文件,它们会被包含在应用的 jar 中。其中,就包括 反射资源动态代理的配置文件。通过嵌入这些配置文件,我们的 jar 马上就能支持 Graal 了。在生成原生镜像时,大多数情况都不需要额外的配置了。

除此之外,注解处理器还会在编译期立即将非法注解或属性的错误展现出来,而不必等到运行时的测试阶段,这样会形成更短的反馈周期。

所以,我们需要做的就是使用类路径下的picocli-codegen来编译CheckSum.java源文件:

在 Linux 下,编译CheckSum.java并创建一个checksum.jar。在 Windows 下,需要将这些命令的:路径分隔符替换为;

复制代码
mkdir classes
javac -cp .:picocli-4.2.0.jar:picocli-codegen-4.2.0.jar -d classes CheckSum.java
cd classes && jar -cvef CheckSum ../checksum.jar * && cd ..

在 jar 文件的META-INF/native-image/picocli-generated/目录下,我们会看到生成的配置文件:

复制代码
jar -tf checksum.jar
META-INF/
META-INF/MANIFEST.MF
CheckSum.class
META-INF/native-image/
META-INF/native-image/picocli-generated/
META-INF/native-image/picocli-generated/proxy-config.json
META-INF/native-image/picocli-generated/reflect-config.json
META-INF/native-image/picocli-generated/resource-config.json

我们的应用已经编写完成了。下一步,我们要制作一个原生镜像。

GraalVM 原生镜像工具链

要创建原生镜像,我们需要安装 GraalVM,确保已安装native-image工具,并根据构建所使用的 OS 安装 C/C++ 编译器工具链。在这个过程中,我遇到了一些问题,希望下面的步骤能够帮助其他开发人员解决相关的问题。

开发就是 10% 的灵感加上 90% 的环境搭建。

— 未知开发人员

安装 GraalVM

首先,安装最新版本的 GraalVM,在编写本文的时候,版本为 20.0。GraalVM 的起步指南页面是掌握在各种操作系统和容器下安装 GraalVM 最新指令的最佳地点。

安装原生镜像工具

GraalVM 附带了一个native-image生成器工具。在最近版本的 GraalVM 中,它需要预先下载并通过 Graal Updater 工具单独进行安装:

在 Linux 上为 Java 11 安装native-image生成器工具。

复制代码
gu install -L /path/to/native-image-installable-svm-java11-linux-amd64-20.0.0.jar

从 20.0 版本开始,对于 Windows 版本的 GraalVM 来说,这同样是必要的。

关于更多细节,请参见 GraalVM 的参考指南原生镜像章节。

安装编译器工具链

Linux 和 MacOS 编译器工具链

native-image的编译依赖于本地工具链,所以在 Linux 和 MacOS 上,我们需要对应操作系统上可用的glibc-develzlib-devel(C 库和 zlib 的头文件)和 gcc。

为了在 Linux 完成安装,需要执行 sudo dnf install gcc glibc-devel zlib-develsudo apt-get install build-essential libz-dev

在 macOS 上,需要执行xcode-select --install

针对 Java 8 的 Windows 编译器工具链

从 19.2.0 版本开始,GraalVM 开始为 Windows 原生镜像提供了实验性的支持。

对 Windows 的支持依然是实验性的,官方文档对 Windows 原生镜像的详细信息很少。从 19.3 版本开始,GraalVM 同时支持 Java 8 和 Java 11,在 Windows 上,它们需要不同的工具链。

要使用 Java 8 版本的 GraalVM 构建原生镜像,我们需要 Microsoft Windows SDK for Windows 7 和.NET Framework 4 ,以及来自KB2519277 的C 编译器。我们可以使用 chocolatey 来安装它们:

复制代码
choco install windows-sdk-7.1 kb2519277

然后(在 cmd 提示行中),激活 sdk-7.1 环境:

复制代码
call "C:\Program Files\Microsoft SDKs\Windows\v7.1\Bin\SetEnv.cmd"

这首先会启动一个新的命令提示行,并启用了 sdk-7.1 环境,在这个命令行提示窗口中运行所有后续的命令。这适用于 Java 8 环境下从 19.2.0 到 20.0 版本的所有 GraalVM。

针对 Java 11 的 Windows 编译器工具链

要使用 Java 11 版本的 GraalVM(19.3.0 及以上),我们可以要么安装 Visual Studio 2017 IDE(确保要包含 Visual C++ tools for CMake),要么可以通过 chocolatey 安装 Visual C Build Tools Workload for Visual Studio 2017 Build Tools:

复制代码
choco install visualstudio2017-workload-vctools

安装之后,在命令提示行中通过如下的命令搭建环境:

复制代码
call "C:\Program Files (x86)\Microsoft Visual Studio\2017\BuildTools\VC\Auxiliary\Build\vcvars64.bat"

提示:
如果你安装了 Visual Studio 2017 IDE,那么需要在上面的命令中将BuildTools替换为CommunityEnterprise,这取决于你的 Visual Studio 版本。

然后,在命令行提示窗口中运行native-image

创建原生镜像

native-image 工具可以将 Java 应用编译为原生镜像,在进行编译的平台上,该原生镜像可以作为原生可执行文件来运行。在 Linux 上,如下所示:

在 Linux 上创建原生镜像

复制代码
$ /usr/lib/jvm/graalvm/bin/native-image \
-cp classes:picocli-4.2.0.jar --no-server \
--static -H:Name=checksum CheckSum

在我的笔记本电脑上,native-image 会耗费大约一分钟的时间,并产生如下所示的输出:

复制代码
[checksum:1073] classlist: 3,124.74 ms, 1.14 GB
[checksum:1073] (cap): 2,885.31 ms, 1.14 GB
[checksum:1073] setup: 4,767.19 ms, 1.14 GB
[checksum:1073] (typeflow): 8,733.59 ms, 1.94 GB
[checksum:1073] (objects): 6,073.44 ms, 1.94 GB
[checksum:1073] (features): 313.28 ms, 1.94 GB
[checksum:1073] analysis: 15,384.41 ms, 1.94 GB
[checksum:1073] (clinit): 322.84 ms, 1.94 GB
[checksum:1073] universe: 793.02 ms, 1.94 GB
[checksum:1073] (parse): 2,191.69 ms, 1.94 GB
[checksum:1073] (inline): 2,064.62 ms, 2.13 GB
[checksum:1073] (compile): 14,960.43 ms, 2.73 GB
[checksum:1073] compile: 20,040.78 ms, 2.73 GB
[checksum:1073] image: 1,272.17 ms, 2.73 GB
[checksum:1073] write: 722.20 ms, 2.73 GB
[checksum:1073] [total]: 46,743.28 ms, 2.73 GB

最终,我们会得到一个原生 Linux 可执行文件。有趣的是,Java 11 版本的 GraalVM 所创建的原生二进制文件要比 Java 8 版本的 GraalVM 所创建的文件更大一些:

复制代码
-rwxrwxrwx 1 remko remko 14744296 Feb 19 09:51 java11-20.0/checksum*
-rwxrwxrwx 1 remko remko 12393600 Feb 19 09:48 java8-20.0/checksum*

我们可以看到文件是 12.4MB 和 14.7MB。到底文件是大还是小,则取决于我们要和什么进行对比。对我来讲,这种大小的文件是可以接受的。

接下来,我们运行该应用,确保它是可用的。在这个过程中,我们还可以对比正常基于 JIT 的 JVM 与原生镜像的启动时间:

复制代码
$ time java -cp classes:picocli-4.2.0.jar CheckSum hi.txt
764efa883dda1e11db47671c4a3bbd9e
real 0m0.415s ← startup is 415 millis with normal Java
user 0m0.609s
sys 0m0.313s
$ time ./checksum hi.txt
764efa883dda1e11db47671c4a3bbd9e
real 0m0.004s ← native image starts up in 4 millis
user 0m0.002s
sys 0m0.002s

至少在 Linux 上我们已经看到了如何将 Java 应用分发为单个原生可执行文件。那在 Windows 上又会怎样呢?

Windows 上的原生镜像

原生镜像对 Windows 的支持还有一些缺陷,所以我们会对此进行更详细的讨论。

在 Windows 上创建原生镜像

创建原生镜像本身并不是什么问题。举例来讲:

在 Windows 上创建原生镜像

复制代码
C:\apps\graalvm-ce-java8-20.0.0\bin\native-image ^
-cp picocli-4.2.0.jar --static -jar checksum.jar

在 Windows 上,native-image.cmd 工具的输出和 Linux 类似,耗费的时间大致相当,所生成的可执行文件稍微小一些,Java 8 版本的 GraalVM 对应的输出是 11.3MB,Java 11 版本的 GraalVM 所输出的二进制文件是 14.2MB。

二进制文件能够很好地运行,但是有一个差异:在控制台我们没有看到 ANSI 的颜色,接下来,看一下如何修复它。

具有彩色输出的 Windows 原生镜像

为了在 Windows 命令提示行中实现 ANSI 彩色显示,我们需要使用 Jansi 库。但令人遗憾的是,Jansi(从 1.18 版本开始)有一些问题,这意味着在GraalVM 原生镜像中,它无法产生彩色的输出。为了解决该问题,picocli 提供了一个 Jansi 协作库,即picocli-jansi-graalvm,它能够让 Jansi 库在 Windows 的 GraalVM 原生镜像上正确地运行。

我们要修改main方法,告诉 Jansi 在 Windows 上启用渲染 ANSI 转义码的功能,如下所示:

复制代码
//...
import picocli.jansi.graalvm.AnsiConsole;
//...
public class CheckSum implements Callable<Integer> {
// ...
public static void main(String[] args) {
int exitCode = 0;
// enable colors on Windows
try (AnsiConsole ansi = AnsiConsole.windowsInstall()) {
exitCode = new CommandLine(new CheckSum()).execute(args);
}
System.exit(exitCode);
}
}

通过该命令构建新的原生镜像(注意,从 GraalVM 19.3 开始,我们需要在类路径中引用 jar 文件):

复制代码
set GRAALVM_HOME=C:\apps\graalvm-ce-java11-20.0.0
%GRAALVM_HOME%\bin\native-image ^
-cp "picocli-4.2.0.jar;jansi-1.18.jar;picocli-jansi-graalvm-1.1.0.jar;checksum.jar" ^
picocli.nativecli.demo.CheckSum checksum

在 DOS 控制台应用中,我们就能看到彩色的输出的了:

如何借助Graalvm和Picocli构建Java编写的原生CLI应用

这需要额外多花点功夫,但是现在我们的原生 Windows CLI 应用可以使用彩色对比了,提供了与 Linux 类似的用户体验。

添加 Jansi 库对形成的二进制文件的大小并没有什么变化:使用 Java 11 GraalVM 构建的二进制文件是 14.3MB,使用 Java 8 GraalVM 构建的二进制文件是 11.3MB。

在 Windows 上运行原生镜像

我们几乎就要完工了,但是还有一个问题是尚未暴露的。

我们刚才创建的二进制文件在构建它的机器上能够很好地运行,但是如果我们在另外一台 Windows 机器上运行的话,你可能会看到如下的错误:

如何借助Graalvm和Picocli构建Java编写的原生CLI应用

它表明,我们的原生镜像需要来自VS C++ Redistributable 2010 的 msvcr100.dll。这个 dll 文件可以放到与exe文件相同的目录下,也可以放到C:\Windows\System32中。有一项正在进行中的工作在试图解决该问题。

在 Java 11 的 GraalVM 中,我们可以看到类似的错误,只不过它提示的是缺少不同的 DLL,即VCRUNTIME140.dll

如何借助Graalvm和Picocli构建Java编写的原生CLI应用

就现在来讲,我们只能随应用一起分发这些 DLL,或者告诉用户下载并安装 Microsoft Visual C++ 2015 Redistributable Update 3 RC 以便于获取基于 Java 11 的原生镜像所需的VCRUNTIME140.dll,或者安装 Microsoft Visual C++ 2010 SP1 Redistributable Package (x64) 以获取基于 Java 8 的原生镜像所需的msvcr100.dll

GraalVM 不支持交叉编译(cross-compilation),不过将来可能会支持。现在,我们需要在 Linux 上编译以获得 Linux 可执行文件,在 MacOS 上编译以获得 MacOS 可执行文件,在 Windows 上编译以获得 Windows 可执行文件。

结论

命令行应用程序是 GraalVM 原生镜像的典型使用场景:我们现在可以使用 Java(或另外的 JVM 语言)进行开发,并将 CLI 应用程序作为单个的、相对较小的原生可执行文件进行分发。(只不过在 Windows 上,我们可能需要分发一个额外的运行时 DLL。) 最大的好处就是快速启动和减少内存占用。

GraalVM 原生镜像有一些限制,应用程序可能需要做一些工作才能转换成原生镜像。

Picocli 使得借助众多 JVM 语言编写命令行应用程序变得很容易,并且提供了一些附加功能,可以轻松地将 CLI 应用程序转换为原生镜像。

在你的下一个命令行应用程序中,尝试一下 Picocli 和 GraalVM 吧!

作者介绍:

Remko Popma白天在 SMBC Nikko Securities 做 Algo 开发,晚上则是 picocli 的作者。Popma 也是 Log4j 2 的性能黑客。他使 Log4j 2 免受垃圾回收之苦,并贡献了 Async Loggers,与当前市场领先的日志包 log4j-1.x 和 logback 相比,Async Loggers 在多线程场景中具有 10 倍的吞吐量和多个数量级的低延迟。Popma 负责了 Log4j 2.0-beta4 版本以来大部分的性能改进。出于兴趣,他喜欢学习新东西:性能、并发性、可伸缩性、低延迟、人工智能、机器学习、密码学、比特币和加密货币技术。你可以通过 @RemkoPopma 找到 Popma。

原文链接:

Build Great Native CLI Apps in Java with Graalvm and Picocli

评论

发布