GraalVM Native Image 构建总览：native-image 命令语法、构建流程与构建完成通知

GraalVM Native Image 构建总览native-image 命令语法、构建流程与构建完成通知【免费下载链接】graalGraalVM compiles applications into native executables that start instantly, scale fast, and use fewer compute resources 项目地址: https://gitcode.com/gh_mirrors/gr/graal本篇技术指南围绕 GraalVM Native Image 的构建入口展开系统讲解native-image命令的三种核心语法主类、JAR 包、Java 模块、命令行参数的求值顺序与命名规则以及如何在不同操作系统下在构建完成后及时获得通知。同时结合本仓库源码与配套文档深入说明-cp类路径语义、-H:/-R:/-J:参数族、构建过程中的内存与并行度默认值帮助你掌握从一条命令到可追溯、可配置的完整构建流程。native-image命令语法native-image是 GraalVM Native Image 的构建工具在仓库中由 substratevm/src/com.oracle.svm.driver/src/com/oracle/svm/driver/NativeImage.java 实现通常被称为native-imagebuilder 或 generator。它的使用方式与java启动器高度对齐支持三种基本形式形式一从主类构建native-image [options] mainclass [imagename] [options]在当前工作目录下从主类构建原生二进制文件。可以通过-cp classpath提供类路径其中classpath是以冒号分隔Windows 下为分号分隔的目录与 JAR 文件路径列表。其默认可执行文件名由主类全限定名小写化而来见下方可执行文件命名规则。形式二从 JAR 包构建native-image [options] -jar jarfile [imagename] [options]从 JAR 文件构建原生二进制文件。这是大多数应用最常用的一种形式默认可执行文件名为 JAR 文件名不含.jar后缀。完整的逐步演示可参考 构建原生可执行文件从 JAR 包开始。形式三从 Java 模块构建native-image [options] -m module/mainClass [imagename] [options]从 Java 模块构建原生二进制文件。native-image支持--module-m、--module-path-p、--add-opens、--add-exports等模块相关选项与java启动器一致并且在使用模块相关选项时native-image工具本身也会被当作一个模块来使用。默认可执行文件名由模块名小写化而来。完整演示见 构建 Java 模块的原生可执行文件。参数从左到右求值传递给native-image的选项从左到右依次求值。这意味着后面的同名选项会覆盖前面的选项。这一规则同样适用于通过META-INF/native-image目录中的配置文件间接传入的选项详情参见 构建配置 中的 Order of Arguments Evaluation 一节。一个典型的覆盖场景假设某个 JAR 内的native-image.properties含有Args -H:Optimize0而你希望在命令行中覆盖它那么把-H:Optimize2放在-cp jar-file之后即可生效。可执行文件命名规则源码视角从源码实现看NativeImage.javanative-image在未显式指定镜像名时会按以下优先级推导名称命令行中的显式镜像名最后一个-o name或位置参数中的额外名字优先生效无显式名称时若以主类构建则以主类名小写作为镜像名mainClass.toLowerCase(Locale.ROOT)若以模块构建-m module/mainClass则以模块名小写作为镜像名如果以上都无法确定且确实需要镜像名则会报错提示使用-o imagename。此外源码中还有对镜像名的合法性校验validateImageName以及对显式镜像名出现在末尾时优先extraNameIsLast的处理逻辑与文档中选项从左到右求值的规则保持一致。构建过程会做什么native-image接收 Java 字节码作为输入产出独立可执行文件或共享库。构建过程大致可分为以下阶段详细输出解读见 Native Image 构建输出Initializing初始化初始化构建环境与 FeaturePerforming analysis静态分析通过 points-to 分析确定哪些类型、字段、方法可达这决定了最终镜像的最小化程度Building universe / Parsing methods构建应用宇宙并解析方法Inlining / Compiling methods方法内联与 AOT 编译Laying out methods / Creating image方法布局与镜像生成包括 code area、image heap、debug info 等。关于构建期build time与运行期run time的区别、静态分析、镜像堆image heap等基础概念建议先阅读 Native Image 基础。构建默认生成可执行文件也可以生成共享库--shared与静态可执行文件--static/--static-nolibc。构建完成后的通知技巧构建一个较大的应用通常需要几分钟时间取决于应用规模与构建机器资源。如果你在后台构建可以使用操作系统通知机制在构建结束时获得提醒。下面按操作系统列出示例命令Linux# 让终端响铃 native-image -jar App.jar ... ; printf \a # 使用 libnotify 创建桌面通知携带退出码 native-image -jar App.jar ... ; notify-send GraalVM Native Image build completed with exit code $? # 使用 Zenity 打开一个信息对话框 native-image -jar App.jar ... ; zenity --info --textGraalVM Native Image build completed with exit code $?macOS# 让终端响铃 native-image -jar App.jar ... ; printf \a # 使用语音合成朗读完成信息 native-image -jar App.jar ... ; say GraalVM Native Image build completedWindows# 让终端响铃按 CtrlG 输入 ^G native-image.exe -jar App.jar echo ^G # 打开一个信息对话框 native-image.exe -jar App.jar msg %username% GraalVM Native Image build completed注意Linux/macOS 示例中...表示构建命令的其余参数;保证无论构建成功与否都执行通知命令而$?携带了退出码方便在notify-send或zenity中判断构建是否成功。核心选项族-H:、-R:、-J:与-Onative-image的选项体系详见 命令行选项大致分为几类Build options用native-image --help查看Extra build options用native-image --help-extra查看Expert build options用native-image --expert-options或更全面的--expert-options-all查看完整选项表native-image --print-options表格、--print-optionsmdMarkdown、--print-optionsjsonJSON。选项按作用域又分为Hosted options-H:前缀配置构建过程同时可为运行时行为设置默认值例如-H:MaxHeapSize2g设置原生可执行文件的默认最大堆大小。对大多数场景只用-H:选项即可无需刻意区分构建期与运行期配置Runtime options-R:前缀在构建时提供显式值运行时默认前缀为-XX:-J前缀将参数直接传递给运行 image builder 的 JVM例如-J-Xmx4g调整构建 JVM 堆大小、-J-XX:MaxRAMPercentage90.0设置最大内存百分比-O优化级别-Ob最快构建、-Os最小体积、-O0/-O1/-O2/-O3由无优化到全量优化。此外native-image的默认行为与java命令对齐java -jar App.jar someArgument对应的构建方式是native-image -jar App.jar运行时则是./App someArgument。构建过程中的内存与并行度native-imagebuilder 运行在 JVM 之上使用底层平台的内存管理因此常规的 Java GC 选项同样适用于 builder。构建时会在内存中构建整个应用的可达性表示属于计算密集型过程其默认内存参数为-Xss10M \ -XX:MaxRAMPercentagepercentage based on available memory \ -XX:GCTimeRatio19 \ -XX:ExitOnOutOfMemoryError \-XX:MaxRAMPercentage决定 builder 的最大堆大小根据系统可用内存计算默认上限为 32GB可通过-J-XX:MaxRAMPercentage90.0物理内存的 90%或-J-Xmx4g覆盖-XX:GCTimeRatio19将 GC 总时间目标提升至 5%更偏向吞吐量并降低峰值 RSS-XX:ExitOnOutOfMemoryError让构建在首次发生OutOfMemoryError时立即退出在内存压力大的环境中更快给出反馈。并行度方面native-image默认最多使用 32 个线程不超过可用处理器数可通过--parallelism...自定义。当构建大型项目或使用-H:Preserveall、--pgo-instrument等内存密集选项时若遇到OutOfMemoryError: Java heap space可以使用-Os缩小镜像体积用更精确的保留选项如-H:Preservepackagepackage替代-H:Preserveall用-J-Xmxng增加构建 JVM 堆大小。构建配置的组织方式虽然BuildOverview.md聚焦于命令入口但要让构建可复制、可追溯推荐将配置以native-image.properties形式嵌入 JAR 包的META-INF/native-image/目录并按照META-INF/native-image/groupID/artifactID/native-image.properties的布局组织避免多模块 JAR 配置相互覆盖。构建时无需额外命令行参数只需$JAVA_HOME/bin/native-image -jar target/name.jar使用native-image --verbose可以查看构建时实际应用了哪些配置文件便于排查配置来自哪里的问题。支持的关键属性包括Args项目需要的自定义native-image命令行选项JavaArgs传递给运行 builder 的 JVM 的自定义选项ImageName自定义可执行文件名命令行仍可覆盖且命令行优先级更高。native-image.properties中可使用${.}展开为当前配置文件所在资源位置配合-H:ReflectionConfigurationResources、-H:ResourceConfigurationResources、-H:JNIConfigurationResources、-H:DynamicProxyConfigurationResources、-H:SerializationConfigurationResources等资源型选项引用同目录下的 JSON 元数据文件。更完整的说明参见 Native Image 构建配置。另外Native Image 默认将配置信息存放在用户主目录的$HOME/.native-image/可通过环境变量NATIVE_IMAGE_USER_HOME更改。构建产物与后续排查构建结束时native-image会输出各阶段统计、资源使用情况与构建产物列表Build artifacts并给出安全报告与优化建议如 G1 GC、PGO、-marchnative等。机器可读的构建输出可通过-H:BuildOutputJSONFile获取。对构建阶段与产物内容的更详细分析可以使用--emit build-report生成单页 HTML 的 Build Report注意该选项在 GraalVM Community Edition 中不可用。对于刚接触 Native Image 的读者建议按以下顺序阅读Native Image 基础理解构建期/运行期、静态分析与镜像堆等核心概念构建配置掌握参数求值顺序与配置文件组织命令行选项查阅全部可用选项构建输出解读构建日志与各阶段统计构建报告深入分析构建产物内容。小结native-image命令的三种语法主类、-jar、-m覆盖了绝大多数 Java 应用的构建入口其选项从左到右求值的规则与java启动器的一致性让迁移成本极低。结合-H:/-R:/-J:选项族、META-INF/native-image配置嵌入机制、内存与并行度调优手段以及构建完成后的操作系统通知技巧你可以在不改变应用代码的前提下把一次native-image构建变成高效、可追溯、可复现的工程流程。【免费下载链接】graalGraalVM compiles applications into native executables that start instantly, scale fast, and use fewer compute resources 项目地址: https://gitcode.com/gh_mirrors/gr/graal创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考