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

Merge pull request !15 from Luke/feature/docs-graalvm-package

README.md

@@ -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)
 
 ## 开发环境安装
 

doc/Snow-Lang-GraalVM-AOT-Native-Image-Package/Snow-Lang-GraalVM-AOT-Native-Image-Package.md

@@ -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/ 目录。

pom.xml

@@ -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>