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

本文要点:

  • 开发人员想要以单个原生可执行性文件的形式分发其命令行应用。
  • 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页面。

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

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

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流,这样的话,它们就可以与其他的工具进行组合。通常,细节决定成败。当用户请求帮助的时候,应用应该将使用帮助信息打印到标准输出中。这允许用户将输出以管道的方式输入到其他工具中,如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控制台应用中,我们就能看到彩色的输出的了:

这需要额外多花点功夫,但是现在我们的原生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

  • 发表于:
  • 本文为 InfoQ 中文站特供稿件
  • 首发地址https://www.infoq.cn/article/4RRJuxPRE80h7YsHZJtX
  • 如有侵权,请联系 yunjia_community@tencent.com 删除。

扫码关注云+社区

领取腾讯云代金券