支持 Graal VM

dubbo3.0 支持 native-image 文档

特性说明

本文档将介绍将 dubbo3.0 项目接入 GraalVM,进行 native-image 编译为二进制的流程。

关于 GraalVm 的更多信息可以阅读 https://www.graalvm.org/docs/getting-started/container-images/ 此文档。

使用场景

使用方式

在编译我们的dubbo项目之前,需要确保我们正基于graalVm的环境。

安装GraalVM

进入 https://www.graalvm.org/ 官网根据自己的系统选取最新版本安装:

支持 Graal VM - 图1

安装完成后,修改配置 JAVA_HOME 的路径,生效后查看本地 jdk 可以看到如下:

支持 Graal VM - 图2 这里我们使用的基于jdk1.8版本的GraalVM。

  • 安装native-image,只需执行gu install native-image即可。
  1. 拉取dubbo代码,切换到apache:3.0分支。
  2. 手动执行生成SPI代码。

由于目前编译native-image不支持代码动态生成编译,所以有关代码动态生成的部分需要我们手动先生成,这里提供了工具函数:

支持 Graal VM - 图3 执行CodeGenerator即可在dubbo-native模块下生成SPI代码。

在根目录下执行install

  1. MacdeMacBook-pro-3:incubator-dubbo mac$ pwd
  2. /Users/mac/Documents/Mi/project/incubator-dubbo
  3. MacdeMacBook-pro-3:incubator-dubbo mac$ mvn clean package install -Dmaven.test.skip=true

编译demo项目

这里我们提供了可直接进行编译的示例项目,dubbo-demo/dubbo-demo-native。上面步骤install完成后,先到dubbo-demo-native的provider下,执行native-image编译:

  1. mvn clean package -P native -Dmaven.test.skip=true

这里由于我们在maven中引入了native-image插件,所以直接-P native即可执行该插件。

支持 Graal VM - 图4 编译成功后可以在target下看到已经生成的二进制文件,本地启动一个zookeeper,直接执行该二进制,可见启动成功如下:

支持 Graal VM - 图5 consumer端同样执行编译,在consumer的target下也会生成二进制文件:demo-native-consumer,执行该二进制可以看到调用结果如下:

支持 Graal VM - 图6

具体步骤

实际上在这个demo下我们做了一些工作来确保项目可以编译执行,主要有以下几个步骤

  • 引入dubbo-native依赖
  1. <dependency>
  2. <groupId>org.apache.dubbo</groupId>
  3. <artifactId>dubbo-native</artifactId>
  4. <version>${project.version}</version>
  5. </dependency>

该模块下有我们生成的SPI代码。

  • 引入native-image插件
  1. <plugin>
  2. <groupId>org.graalvm.nativeimage</groupId>
  3. <artifactId>native-image-maven-plugin</artifactId>
  4. <version>21.0.0.2</version>
  5. <executions>
  6. <execution>
  7. <goals>
  8. <goal>native-image</goal>
  9. </goals>
  10. <phase>package</phase>
  11. </execution>
  12. </executions>
  13. <configuration>
  14. <skip>false</skip>
  15. <imageName>demo-native-provider</imageName>
  16. <mainClass>org.apache.dubbo.demo.graalvm.provider.Application</mainClass>
  17. <buildArgs>
  18. --no-fallback
  19. --initialize-at-build-time=org.slf4j.MDC
  20. --initialize-at-build-time=org.slf4j.LoggerFactory
  21. --initialize-at-build-time=org.slf4j.impl.StaticLoggerBinder
  22. --initialize-at-build-time=org.apache.log4j.helpers.Loader
  23. --initialize-at-build-time=org.apache.log4j.Logger
  24. --initialize-at-build-time=org.apache.log4j.helpers.LogLog
  25. --initialize-at-build-time=org.apache.log4j.LogManager
  26. --initialize-at-build-time=org.apache.log4j.spi.LoggingEvent
  27. --initialize-at-build-time=org.slf4j.impl.Log4jLoggerFactory
  28. --initialize-at-build-time=org.slf4j.impl.Log4jLoggerAdapter
  29. --initialize-at-build-time=org.eclipse.collections.api.factory.Sets
  30. --initialize-at-run-time=io.netty.channel.epoll.Epoll
  31. --initialize-at-run-time=io.netty.channel.epoll.Native
  32. --initialize-at-run-time=io.netty.channel.epoll.EpollEventLoop
  33. --initialize-at-run-time=io.netty.channel.epoll.EpollEventArray
  34. --initialize-at-run-time=io.netty.channel.DefaultFileRegion
  35. --initialize-at-run-time=io.netty.channel.kqueue.KQueueEventArray
  36. --initialize-at-run-time=io.netty.channel.kqueue.KQueueEventLoop
  37. --initialize-at-run-time=io.netty.channel.kqueue.Native
  38. --initialize-at-run-time=io.netty.channel.unix.Errors
  39. --initialize-at-run-time=io.netty.channel.unix.IovArray
  40. --initialize-at-run-time=io.netty.channel.unix.Limits
  41. --initialize-at-run-time=io.netty.util.internal.logging.Log4JLogger
  42. --initialize-at-run-time=io.netty.channel.unix.Socket
  43. --initialize-at-run-time=io.netty.channel.ChannelHandlerMask
  44. --report-unsupported-elements-at-runtime
  45. --allow-incomplete-classpath
  46. --enable-url-protocols=http
  47. -H:+ReportExceptionStackTraces
  48. </buildArgs>
  49. </configuration>
  50. </plugin>

其中定义了生成的镜像名以及一些构建镜像的参数。

  • 挂载native-image-agent

由于我们需要将一些反射、JNI等类先指定出来,我们需要先使用该agent以正常方式运行一遍生成这些类的json形式的信息。

在启动参数中添加:

  1. -agentlib:native-image-agent=config-output-dir=/tmp/config/,config-write-period-secs=300,config-write-initial-delay-secs=5

以正常方式启动,在项目的resources下建立文件夹META-INF.native-image,把在本地目录中生成的文件粘进去:

支持 Graal VM - 图7 (可能会有缺漏没有生成的类信息,需要根据编译或运行时的报错信息手动添加。)

完成以上几步后就可以进行项目的编译了。

最后修改 December 16, 2022: Fix check (#1736) (97972c1)