Add Doc for GraalVM support

apache · Sep 14, 2023 · 746e5fe · 746e5fe
1 parent aa4be56
commit 746e5fe
Show file tree

Hide file tree

Showing 5 changed files with 252 additions and 4 deletions.
diff --git a/.github/workflows/graalvm-ce-nativetest.yml b/.github/workflows/graalvm-ce-nativetest.yml
@@ -36,8 +36,8 @@ jobs:
   build:
     strategy:
       matrix:
-        java: [ '17.0.8' ]
-        os: [ 'windows-latest', 'ubuntu-latest' ]
+        graalvm: [ '17.0.8' ]
+        os: [ 'ubuntu-latest' ]
     runs-on: ${{ matrix.os }}
     steps:
       - name: Configure Git
@@ -48,7 +48,7 @@ jobs:
       - name: Set up GraalVM CE ${{ matrix.java }}
         uses: graalvm/setup-graalvm@v1
         with:
-          java-version: ${{ matrix.java }}
+          java-version: ${{ matrix.graalvm }}
           distribution: 'graalvm-community'
           github-token: ${{ secrets.GITHUB_TOKEN }}
           cache: 'maven'

diff --git a/docs/content/user-manual/elasticjob-lite/configuration/graalvm-native-image.cn.md b/docs/content/user-manual/elasticjob-lite/configuration/graalvm-native-image.cn.md
@@ -0,0 +1,88 @@
++++
+title = "GraalVM Native Image 支持"
+weight = 6
+chapter = true
++++
+
+## 对 GraalVM Native Image 的支持
+
+ElasticJob Lite 通过 GAV 信息为 `org.apache.shardingsphere.elasticjob:elasticjob-lite-reachability-metadata:${project.version}` 
+的 Maven 库，提供了 GraalVM Native Image 运行所需要的 GraalVM Reachability Metadata。如果你期望构建包含 ElasticJob Lite 的 
+GraalVM Native Image，你可在 `pom.xml` 引入如下依赖。
+
+```xml
+<project>
+    <dependencies>
+        <dependency>
+            <groupId>org.apache.shardingsphere.elasticjob</groupId>
+            <artifactId>elasticjob-lite-core</artifactId>
+            <version>${project.version}</version>
+        </dependency>
+	<dependency>
+            <groupId>org.apache.shardingsphere.elasticjob</groupId>
+            <artifactId>elasticjob-lite-reachability-metadata</artifactId>
+            <version>${project.version}</version>
+        </dependency>
+    </dependencies>
+</project>
+```
+
+## 内部的 GraalVM Reachability Metadata 条目
+
+`org.apache.shardingsphere.elasticjob:elasticjob-lite-reachability-metadata` 托管了如下 Maven 库的 GraalVM Reachability 
+Metadata，一旦 https://github.com/oracle/graalvm-reachability-metadata 对如下库的 GraalVM Reachability Metadata 进行了 
+Release 流程, 下列第三方库的相关 JSON 文件将在 ElasticJob 一侧被删除。
+
+-  `org.apache.zookeeper:zookeeper:3.9.0`
+- `org.apache.curator:curator-client:5.5.0`
+- `org.apache.curator:curator-framework:5.5.0`
+- `org.apache.curator:curator-framework:5.5.0`
+- `org.apache.shardingsphere.elasticjob:elasticjob-lite-core:${project.version}`
+
+用户可以通过在自有项目的资源根目录或测试资源文件夹，通过新建对应库信息的 `/META-INF/native-image/${project.groupId}/${project.artifactId}/${project.version}` 
+文件夹来覆写被传入项目的 GraalVM Reachability Metadata 。
+
+即使用户不使用 `org.apache.shardingsphere.elasticjob:elasticjob-lite-reachability-metadata` 库，用户依然可以自己编写 GraalVM 
+Reachability Metadata 的相关文件来为 ElasticJob Lite 提供 GraalVM Native Image 支持。
+
+## 已知限制
+
+1. 用户无法在 GraalVM Native Image 使用 elasticJobType 为 SCRIPT 的 Job。参考 https://github.com/oracle/graal/issues/7390 。
+
+2. 用户无法在 GraalVM Native Image 下使用与 `org.apache.shardingsphere.elasticjob.tracing.api.TracingConfiguration` 相关的 Tracing 功能。
+
+3. ElasticJob 的 Spring Boot Starter 尚未在 GraalVM Native Image 下可用。
+
+## 贡献 GraalVM Reachability Metadata
+
+此节文本针对贡献者。假设贡献者位于新的 Ubuntu 22.04.3 实例下，可通过 SDKMAN! 初始化 GraalVM CE 环境。
+
+```bash
+sdk install java 17.0.8-graalce
+sdk use java 17.0.8-graalce
+sudo apt-get install build-essential libz-dev zlib1g-dev -y
+```
+
+
+对于与 ElasticJob 无关的 GraalVM Reachability Metadata，相关的 issue 和 PR 应当首先创建在 https://github.com/oracle/graalvm-reachability-metadata 。
+该存储库使 GraalVM Native Image 的用户能够共享和重用 Java 生态系统中的库和框架的元数据。
+
+`org.apache.shardingsphere.elasticjob:elasticjob-lite-reachability-metadata` 维护了一组单元测试子集，此子集避开对 Mockito 相关的
+类的使用，以服务于项目 CI 对 Native Image 的测试。参考 https://github.com/mockito/mockito/issues/2862。
+
+在 ElasticJob 一侧，存在 Maven Profile 为 generateMetadata，用户可在 ElasticJob 项目根目录执行如下命令来采集 GraalVM Reachability Metadata。
+
+```bash
+./mvnw -PgenerateMetadata -DskipNativeTests -e -T1C -B clean test native:metadata-copy
+```
+
+在 ElasticJob 一侧，存在 Maven Profile 为 nativeTestInElasticJob，用户可在 ElasticJob 项目根目录执行如下命令来执行特定于 GraalVM 
+Native Build Tools 的 nativeTest，以验证 Native Image 中的单元测试覆盖率。
+
+```bash
+./mvnw -PnativeTestInElasticJob -T1C -B -e clean test
+```
+
+对于特定于单元测试的 GraalVM Reachability Metadata，请放置在 `elasticjob-lite/elasticjob-lite-reachability-metadata/src/test/resources/META-INF/native-image/${project.artifactId}-test-metadata/` 
+文件夹下，`${project.artifactId}` 为对应单元测试涉及的子模块。如有需要，请使用 `org.junit.jupiter.api.condition.DisabledInNativeImage` 
+注解或 `org.graalvm.nativeimage.imagecode` 的 System Property 屏蔽部分单元测试在 GraalVM Native Image 下运行。
diff --git a/docs/content/user-manual/elasticjob-lite/configuration/graalvm-native-image.en.md b/docs/content/user-manual/elasticjob-lite/configuration/graalvm-native-image.en.md
@@ -0,0 +1,98 @@
++++
+title = "GraalVM Native Image Support"
+weight = 6
+chapter = true
++++
+
+## Support for GraalVM Native Image
+
+ElasticJob Lite provides the GraalVM Reachability Metadata required for GraalVM Native Image to run through the Maven 
+library whose GAV information is `org.apache.shardingsphere.elasticjob:elasticjob-lite-reachability-metadata:${project.version}`. 
+If you want to build the GraalVM Native Image that includes ElasticJob Lite, you can introduce the following 
+dependencies in `pom.xml`.
+
+```xml
+<project>
+     <dependencies>
+         <dependency>
+             <groupId>org.apache.shardingsphere.elasticjob</groupId>
+             <artifactId>elasticjob-lite-core</artifactId>
+             <version>${project.version}</version>
+         </dependency>
+         <dependency>
+             <groupId>org.apache.shardingsphere.elasticjob</groupId>
+             <artifactId>elasticjob-lite-reachability-metadata</artifactId>
+             <version>${project.version}</version>
+         </dependency>
+     </dependencies>
+</project>
+```
+
+## Internal GraalVM Reachability Metadata entries
+
+`org.apache.shardingsphere.elasticjob:elasticjob-lite-reachability-metadata` hosts the GraalVM Reachability Metadata of 
+the following Maven library. Once https://github.com/oracle/graalvm-reachability-metadata is used for the GraalVM 
+Reachability Metadata of the following library After the Release process, the JSON files related to the following 
+third-party libraries will be deleted on the ElasticJob side.
+
+- `org.apache.zookeeper:zookeeper:3.9.0`
+- `org.apache.curator:curator-client:5.5.0`
+- `org.apache.curator:curator-framework:5.5.0`
+- `org.apache.curator:curator-framework:5.5.0`
+- `org.apache.shardingsphere.elasticjob:elasticjob-lite-core:${project.version}`
+
+Users can create a new `/META-INF/native-image/${project.groupId}/${project.artifactId}/${project.version}` folder 
+corresponding to the library information in the resource root directory of their own project or the test resource folder 
+to overwrite the GraalVM Reachability Metadata passed into the project.
+
+Even if users do not use the `org.apache.shardingsphere.elasticjob:elasticjob-lite-reachability-metadata` library, 
+users can still write their own GraalVM Reachability Metadata related files to provide GraalVM Native Image support for 
+ElasticJob Lite.
+
+## Known limitations
+
+1. Users cannot use jobs whose elasticJobType is SCRIPT in GraalVM Native Image. Reference https://github.com/oracle/graal/issues/7390.
+
+2. Users cannot use Tracing functions related to `org.apache.shardingsphere.elasticjob.tracing.api.TracingConfiguration`
+under GraalVM Native Image.
+
+3. ElasticJob’s Spring Boot Starter is not yet available under GraalVM Native Image.
+
+## Contribute GraalVM Reachability Metadata
+
+The text in this section is directed to contributors. Assuming the contributor is under a new Ubuntu 22.04.3 instance, 
+the GraalVM CE environment can be initialized via `SDKMAN!`.
+
+```bash
+sdk install java 17.0.8-graalce
+sdk use java 17.0.8-graalce
+sudo apt-get install build-essential libz-dev zlib1g-dev -y
+```
+
+For GraalVM Reachability Metadata not related to ElasticJob, related issues and PRs should first be created at 
+https://github.com/oracle/graalvm-reachability-metadata. This repository enables users of GraalVM Native Image to share 
+and reuse metadata for libraries and frameworks across the Java ecosystem.
+
+`org.apache.shardingsphere.elasticjob:elasticjob-lite-reachability-metadata` maintains a subset of unit tests that 
+avoids the use of Mockito-related classes to serve the project CI's testing of Native Image. 
+Reference https://github.com/mockito/mockito/issues/2862 .
+
+On the ElasticJob side, there is a Maven Profile called `generateMetadata`. Users can execute the following command in 
+the ElasticJob project root directory to collect GraalVM Reachability Metadata.
+
+```bash
+./mvnw -PgenerateMetadata -DskipNativeTests -e -T1C -B clean test native:metadata-copy
+```
+
+On the ElasticJob side, the Maven Profile exists as `nativeTestInElasticJob`. Users can execute the following command in
+the ElasticJob project root directory to execute nativeTest specific to GraalVM Native Build Tools to verify the unit 
+test coverage in Native Image.
+
+```bash
+./mvnw -PnativeTestInElasticJob -T1C -B -e clean test
+```
+
+For unit test-specific GraalVM Reachability Metadata, place it in `elasticjob-lite/elasticjob-lite-reachability-metadata/src/test/resources/META-INF/native-image/${project.artifactId}-test-metadata/` 
+folder, `${project.artifactId}` is the submodule involved in the corresponding unit test. If necessary, use the 
+`org.junit.jupiter.api.condition.DisabledInNativeImage` annotation or the `org.graalvm.nativeimage.imagecode` System 
+Property blocks some unit tests from running under GraalVM Native Image.
diff --git a/elasticjob-lite/elasticjob-lite-reachability-metadata/pom.xml b/elasticjob-lite/elasticjob-lite-reachability-metadata/pom.xml
@@ -55,4 +55,4 @@
             </plugin>
         </plugins>
     </build>
-</project>
+</project>
diff --git a/pom.xml b/pom.xml
@@ -754,6 +754,68 @@
                 </pluginManagement>
             </build>
         </profile>
+        <profile>
+            <id>generateMetadata</id>
+            <properties>
+                <java.version>17</java.version>
+            </properties>
+            <build>
+                <pluginManagement>
+                    <plugins>
+                        <plugin>
+                            <artifactId>maven-surefire-plugin</artifactId>
+                            <configuration>
+                                <includes>
+                                    <include>org.apache.shardingsphere.elasticjob.lite.reachability.metadata.fixture.**</include>
+                                </includes>
+                            </configuration>
+                        </plugin>
+                        <plugin>
+                            <groupId>org.graalvm.buildtools</groupId>
+                            <artifactId>native-maven-plugin</artifactId>
+                            <version>${native-maven-plugin.version}</version>
+                            <extensions>true</extensions>
+                            <executions>
+                                <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>
+                                <agent>
+                                    <enabled>true</enabled>
+                                    <defaultMode>Conditional</defaultMode>
+                                    <modes>
+                                        <conditional>
+                                            <userCodeFilterPath>${user.dir}/elasticjob-lite/elasticjob-lite-reachability-metadata/user-code-filter-elasticjob-lite-core.json</userCodeFilterPath>
+                                            <extraFilterPath>${user.dir}/elasticjob-lite/elasticjob-lite-reachability-metadata/extra-filter.json</extraFilterPath>
+                                            <parallel>true</parallel>
+                                        </conditional>
+                                    </modes>
+                                    <metadataCopy>
+                                        <disabledStages>
+                                            <stage>main</stage>
+                                        </disabledStages>
+                                        <merge>false</merge>
+                                        <outputDirectory>${user.dir}/elasticjob-lite/elasticjob-lite-reachability-metadata/src/main/resources/META-INF/native-image/org.apache.shardingsphere.elasticjob/elasticjob-lite-core</outputDirectory>
+                                    </metadataCopy>
+                                </agent>
+                            </configuration>
+                        </plugin>
+                    </plugins>
+                </pluginManagement>
+            </build>
+        </profile>
         <profile>
             <id>nativeTestInElasticJob</id>
             <properties>