Luke/snow
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

!15 docs: 增加Snow-Lang GraalVM AOT 打包指南

Browse Source 
Merge pull request !15 from Luke/feature/docs-graalvm-package
This commit is contained in:
zhangxun 2025-06-20 04:57:24 +00:00 committed by Gitee
commit 0e730b952c
No known key found for this signature in database
GPG Key ID: 173E9B9CA92EEF8F
11 changed files with 225 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
README.md
View File

@ -36,7 +36,7 @@ Snow 语言是一个正在发展的编程语言,采用类模块（module）语
Snow 语言受到 LLM 驱动代码生成趋势的启发,强调简单而清晰的语法和严格的类型系统,以帮助人工智能模型更好地理解程序结构。语言使用显式的 `module` 声明来组织代码,用 `function`,`parameter`,`return_type`,`body` 等关键字分隔不同代码块,语法结构固定且易读。此外,Snow 实现了语义分析来检查变量作用域和类型一致性,在编译阶段捕获错误并确保生成的中间代码正确无误。这种自上而下的编译流程,使得代码设计和生成更加模块化,可解释,也有利于调试和优化。
相关背景: [心路历程](doc/Snow's-Journey/Snow's-Journey.md)
相关背景: [心路历程](doc/Snow-Lang-Journey/Snow-Lang-Journey.md)
## 下载Snow发行版
@ -44,7 +44,9 @@ Snow 语言受到 LLM 驱动代码生成趋势的启发,强调简单而清晰的
## 相关文档
[Git 管理规范](doc/Git-Management/Git-Management.md)
[Git 管理规范](doc/Snow-Lang-Git-Management/Snow-Lang-Git-Management.md)
[Snow-Lang GraalVM AOT 打包指南](doc/Snow-Lang-GraalVM-AOT-Native-Image-Package/Snow-Lang-GraalVM-AOT-Native-Image-Package.md)
## 功能特性
@ -60,7 +62,7 @@ Snow 语言受到 LLM 驱动代码生成趋势的启发,强调简单而清晰的
## 开发计划
[Snow 语言现状和下一阶段开发路线图-2025-06-11](doc/Snow's-current-language-situation-and-the-development-roadmap-for-the-next-stage/Snow's-current-language-situation-and-the-development-roadmap-for-the-next-stage.md)
[Snow 语言现状和下一阶段开发路线图-2025-06-11](doc/Snow-Lang-Roadmap/Snow-Lang-Roadmap.md)
## 开发环境安装

0
doc/Git-Management/Git-Management.md → doc/Snow-Lang-Git-Management/Snow-Lang-Git-Management.md
View File

174
doc/Snow-Lang-GraalVM-AOT-Native-Image-Package/Snow-Lang-GraalVM-AOT-Native-Image-Package.md Normal file
View File

@ -0,0 +1,174 @@
# Snow-Lang GraalVM AOT 打包指南
## 1. 概述
本文档介绍如何使用 GraalVM 的 AOT（Ahead-of-Time）编译功能将一个 Snow-Lang 项目打包成原生可执行文件（Native Image）。
## 2. 前置条件
1. 操作系统：Linux/macOS/Windows
2. Java 项目（Maven）
3. GraalVM（建议 24+ 版本）
## 3. 环境准备
### 3.1 安装 GraalVM
1. 下载对应平台的 GraalVM Community 版本：[https://www.graalvm.org/downloads/](https://www.graalvm.org/downloads/)
2. 解压并配置环境变量：
3. 验证安装：
```bash
java -version
# 应显示 GraalVM 版本信息
java version "24.0.1" 2025-04-15
Java(TM) SE Runtime Environment Oracle GraalVM 24.0.1+9.1 (build 24.0.1+9-jvmci-b01)
Java HotSpot(TM) 64-Bit Server VM Oracle GraalVM 24.0.1+9.1 (build 24.0.1+9-jvmci-b01, mixed mode, sharing)
```
### 3.2 Windows 上 Native Image 的先决条件
在 Windows 上，Native Image 需要 Visual Studio 和 Microsoft Visual C++(MSVC)。
1. 从 [visualstudio.microsoft.com](https://visualstudio.microsoft.com/zh-hans/vs/) 下载 Visual Studio Build Tools 2022 或更高版本（C 开发环境）。
2. 通过打开下载的文件来启动安装，然后单击 **继续**
![IMG_VS_1.png](img/IMG_VS_1.png)
3. 在主窗口中选择 **使用 C++ 进行桌面开发** 复选框。在右侧的“安装详细信息”下，确保选择了两个要求，**Windows 11 SDK** 和 **MSVC (…) C++ x64/x86 构建工具**。单击 **安装** 继续。
![IMG_VS_2.png](img/IMG_VS_2.png)
您现在能够使用 GraalVM Native Image 进行构建。
## 4. Maven 项目配置文件
通过将以下配置文件添加到 `pom.xml` 中，为 Native Image 启用 Maven 插件：
```xml
<profiles>
<!--
原生镜像构建：Linux 平台
- 使用 GraalVM 的 native-image 工具，生成静态链接的可执行文件
- 依赖 musl libc，需提前安装并配置 musl-gcc 工具链
-->
<profile>
<id>native-linux</id>
<activation>
<os>
<family>unix</family>
</os>
</activation>
<build>
<plugins>
<plugin>
<groupId>org.graalvm.buildtools</groupId>
<artifactId>native-maven-plugin</artifactId>
<version>${native.maven.plugin.version}</version>
<!-- 启用插件扩展，允许在 build 生命周期中无须额外配置 -->
<extensions>true</extensions>
<executions>
<!-- 打包阶段生成原生可执行文件 -->
<execution>
<id>build-native</id>
<goals>
<!-- compile-no-fork 在当前 JVM 进程中执行 native-image -->
<goal>compile-no-fork</goal>
</goals>
<phase>package</phase>
</execution>
<!-- 测试阶段运行原生镜像的测试 -->
<execution>
<id>test-native</id>
<goals>
<goal>test</goal>
</goals>
<phase>test</phase>
</execution>
</executions>
<configuration>
<buildArgs>
<!-- 静态链接 -->
<buildArg>--static</buildArg>
<!-- 指定 musl libc -->
<buildArg>--libc=musl</buildArg>
<!-- 输出构建报告 -->
<buildArg>--emit build-report</buildArg>
<!-- 优化级别 O2 -->
<buildArg>-O2</buildArg>
</buildArgs>
<environment>
<!-- 指定使用 musl 工具链 -->
<PATH>/opt/musl-1.2.5/bin:${env.PATH}</PATH>
<C_INCLUDE_PATH>/opt/musl-1.2.5/include</C_INCLUDE_PATH>
<LIBRARY_PATH>/opt/musl-1.2.5/lib</LIBRARY_PATH>
</environment>
</configuration>
</plugin>
</plugins>
</build>
</profile>
<!--
原生镜像构建：Windows 平台
- 使用 GraalVM 的 native-image 工具，生成 Windows 可执行文件
- Windows 上不使用 musl，因此不配置静态链接
-->
<profile>
<id>native-windows</id>
<activation>
<os>
<family>Windows</family>
</os>
</activation>
<build>
<plugins>
<plugin>
<groupId>org.graalvm.buildtools</groupId>
<artifactId>native-maven-plugin</artifactId>
<version>${native.maven.plugin.version}</version>
<extensions>true</extensions>
<executions>
<!-- 打包阶段生成 Windows 可执行文件 -->
<execution>
<id>build-native</id>
<goals>
<goal>compile-no-fork</goal>
</goals>
<phase>package</phase>
</execution>
<!-- 测试阶段运行原生镜像测试 -->
<execution>
<id>test-native</id>
<goals>
<goal>test</goal>
</goals>
<phase>test</phase>
</execution>
</executions>
<configuration>
<buildArgs>
<!-- 输出构建报告 -->
<buildArg>--emit build-report</buildArg>
<!-- 优化级别 O2 -->
<buildArg>-O2</buildArg>
</buildArgs>
</configuration>
</plugin>
</plugins>
</build>
</profile>
</profiles>
```
## 5. 构建 Native Image
1. 确保项目已在 JVM 下通过测试。
2. 点击 `Maven` `生命周期` `package`
![IMG_Maven_Package_1.png](img/IMG_Maven_Package_1.png)
3. 等待 Native Image 构建完成：这个过程可能较慢（数分钟）。
4. 可执行文件即可直接运行，无需 JVM。
> 生成的可执行文件位于 target/ 目录。

BIN
doc/Snow-Lang-GraalVM-AOT-Native-Image-Package/img/IMG_Maven_Package_1.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 10 KiB

BIN
doc/Snow-Lang-GraalVM-AOT-Native-Image-Package/img/IMG_VS_1.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 13 KiB

BIN
doc/Snow-Lang-GraalVM-AOT-Native-Image-Package/img/IMG_VS_2.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 185 KiB

0
doc/Snow's-Journey/Snow's-Journey.md → doc/Snow-Lang-Journey/Snow-Lang-Journey.md
View File

0
doc/Snow's-Journey/img/IMG_JNotepad_1.png → doc/Snow-Lang-Journey/img/IMG_JNotepad_1.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 190 KiB

After

Width:  |  Height:  |  Size: 190 KiB

0
doc/Snow's-Journey/img/IMG_JNotepad_2.png → doc/Snow-Lang-Journey/img/IMG_JNotepad_2.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 192 KiB

After

Width:  |  Height:  |  Size: 192 KiB

0
doc/Snow's-current-language-situation-and-the-development-roadmap-for-the-next-stage/Snow's-current-language-situation-and-the-development-roadmap-for-the-next-stage.md → doc/Snow-Lang-Roadmap/Snow-Lang-Roadmap.md
View File

49
pom.xml
View File

@ -19,24 +19,41 @@
<!-- 通用编译 & 打包插件 -->
<build>
<!-- 资源文件目录及占位符替换（resource filtering） -->
<resources>
<resource>
<!-- 指定资源文件所在目录 -->
<directory>src/main/resources</directory>
<!-- 开启资源文件中的占位符（如 ${project.version}）替换 -->
<filtering>true</filtering>
</resource>
</resources>
<plugins>
<!-- Java 编译插件 -->
<!--
Java 编译插件：
- 使用 Maven 自带的 maven-compiler-plugin 进行源码编译
- <fork>true</fork> 表示在单独的进程中执行 javac，提高兼容性
-->
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.12.1</version>
<configuration>
<!-- 在新的 JVM 进程中调用编译器 -->
<fork>true</fork>
<!-- 可以根据需要指定编译器版本，如：
<source>1.8</source>
<target>1.8</target>
-->
</configuration>
</plugin>
<!-- Jar 打包插件 -->
<!--
Jar 打包插件：
- 使用 maven-jar-plugin 将编译产物打包成可执行 JAR
- 在 MANIFEST 中指定主类，支持命令行直接 java -jar 调用
-->
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-jar-plugin</artifactId>
@ -44,8 +61,11 @@
<configuration>
<archive>
<manifest>
<!-- 指定程序入口类，运行 java -jar 时会执行此类的 main 方法 -->
<mainClass>org.jcnc.snow.cli.SnowCLI</mainClass>
<!-- 将项目类路径添加到 MANIFEST Class-Path 中 -->
<addClasspath>true</addClasspath>
<!-- 在 MANIFEST 中添加实现版本、实现供应商等默认条目 -->
<addDefaultImplementationEntries>true</addDefaultImplementationEntries>
</manifest>
</archive>
@ -55,6 +75,11 @@
</build>
<profiles>
<!--
原生镜像构建：Linux 平台
- 使用 GraalVM 的 native-image 工具，生成静态链接的可执行文件
- 依赖 musl libc，需提前安装并配置 musl-gcc 工具链
-->
<profile>
<id>native-linux</id>
<activation>
@ -68,15 +93,19 @@
<groupId>org.graalvm.buildtools</groupId>
<artifactId>native-maven-plugin</artifactId>
<version>${native.maven.plugin.version}</version>
<!-- 启用插件扩展，允许在 build 生命周期中无须额外配置 -->
<extensions>true</extensions>
<executions>
<!-- 打包阶段生成原生可执行文件 -->
<execution>
<id>build-native</id>
<goals>
<!-- compile-no-fork 在当前 JVM 进程中执行 native-image -->
<goal>compile-no-fork</goal>
</goals>
<phase>package</phase>
</execution>
<!-- 测试阶段运行原生镜像的测试 -->
<execution>
<id>test-native</id>
<goals>
@ -87,13 +116,17 @@
</executions>
<configuration>
<buildArgs>
<!-- 静态链接 -->
<buildArg>--static</buildArg>
<!-- 指定 musl libc -->
<buildArg>--libc=musl</buildArg>
<!-- 输出构建报告 -->
<buildArg>--emit build-report</buildArg>
<!-- 优化级别 O2 -->
<buildArg>-O2</buildArg>
</buildArgs>
<environment>
<!-- 指定 musl-gcc 工具链 -->
<!-- 指定使用 musl 工具链 -->
<PATH>/opt/musl-1.2.5/bin:${env.PATH}</PATH>
<C_INCLUDE_PATH>/opt/musl-1.2.5/include</C_INCLUDE_PATH>
<LIBRARY_PATH>/opt/musl-1.2.5/lib</LIBRARY_PATH>
@ -104,6 +137,11 @@
</build>
</profile>
<!--
原生镜像构建：Windows 平台
- 使用 GraalVM 的 native-image 工具，生成 Windows 可执行文件
- Windows 上不使用 musl，因此不配置静态链接
-->
<profile>
<id>native-windows</id>
<activation>
@ -119,6 +157,7 @@
<version>${native.maven.plugin.version}</version>
<extensions>true</extensions>
<executions>
<!-- 打包阶段生成 Windows 可执行文件 -->
<execution>
<id>build-native</id>
<goals>
@ -126,6 +165,7 @@
</goals>
<phase>package</phase>
</execution>
<!-- 测试阶段运行原生镜像测试 -->
<execution>
<id>test-native</id>
<goals>
@ -136,7 +176,9 @@
</executions>
<configuration>
<buildArgs>
<!-- 输出构建报告 -->
<buildArg>--emit build-report</buildArg>
<!-- 优化级别 O2 -->
<buildArg>-O2</buildArg>
</buildArgs>
</configuration>
@ -145,4 +187,5 @@
</build>
</profile>
</profiles>
</project>