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

by

• Remko Popma

摘要：

相对于其他可选方案，Java并不是创建简单的命令行驱动的应用程序的简便选项，这在很大程度上是因为它需要分发一个规模可观的运行时环境。GraalVM和Picocli的组合旨在改变这种情况，它们提供了原生编译的功能以及一个简单、现代的方式来处理命令行参数。

核心要点

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

梦想：可执行的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页面。

其中，有两个限制需要特别注意：

• 反射（reflection）
• 资源（resources）

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

Picocli

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

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

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样例看上去如下所示：

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

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

Stdout与stderr

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

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

退出码

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

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

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

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

紧凑的代码

在上面的章节中，我们描述了很多的功能。你可能会认为需要大量的代码才能完成它们，但是大多数“标准的CLI行为”都是由picocli库提供的。在我们的应用中，我们所需要做的就是定义选项和位置参数，并通过将类定义为Callable或Runnable来实现我们的业务逻辑。在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-devel、zlib-devel（C库和zlib的头文件）和gcc。

为了在Linux完成安装，需要执行 sudo dnf install gcc glibc-devel zlib-devel或sudo 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替换为Community或Enterprise，这取决于你的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控制台应用中，我们就能看到彩色的输出的了：

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

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

在Windows上运行原生镜像

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

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

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

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

就现在来讲，我们只能随应用一起分发这些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