From 9ff6e5d64ee2c57872337fe9aaa76e1e41b68c67 Mon Sep 17 00:00:00 2001 From: linghengqian Date: Thu, 14 Sep 2023 09:34:26 +0800 Subject: [PATCH] Add Doc for GraalVM support --- .github/workflows/graalvm-ce-nativetest.yml | 6 +- .../configuration/graalvm-native-image.cn.md | 88 +++++++++++++++++ .../configuration/graalvm-native-image.en.md | 98 +++++++++++++++++++ .../pom.xml | 2 +- pom.xml | 62 ++++++++++++ 5 files changed, 252 insertions(+), 4 deletions(-) create mode 100644 docs/content/user-manual/elasticjob-lite/configuration/graalvm-native-image.cn.md create mode 100644 docs/content/user-manual/elasticjob-lite/configuration/graalvm-native-image.en.md diff --git a/.github/workflows/graalvm-ce-nativetest.yml b/.github/workflows/graalvm-ce-nativetest.yml index 9ce5316327..3ded6940c0 100644 --- 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 new file mode 100644 index 0000000000..8c814964f6 --- /dev/null +++ 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 + + + + org.apache.shardingsphere.elasticjob + elasticjob-lite-core + ${project.version} + + + org.apache.shardingsphere.elasticjob + elasticjob-lite-reachability-metadata + ${project.version} + + + +``` + +## 内部的 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 new file mode 100644 index 0000000000..f55c702153 --- /dev/null +++ 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 + + + + org.apache.shardingsphere.elasticjob + elasticjob-lite-core + ${project.version} + + + org.apache.shardingsphere.elasticjob + elasticjob-lite-reachability-metadata + ${project.version} + + + +``` + +## 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 index d95fa36068..9fd4da2151 100644 --- a/elasticjob-lite/elasticjob-lite-reachability-metadata/pom.xml +++ b/elasticjob-lite/elasticjob-lite-reachability-metadata/pom.xml @@ -55,4 +55,4 @@ - \ No newline at end of file + diff --git a/pom.xml b/pom.xml index 581fb8523d..2db0631247 100644 --- a/pom.xml +++ b/pom.xml @@ -754,6 +754,68 @@ + + generateMetadata + + 17 + + + + + + maven-surefire-plugin + + + org.apache.shardingsphere.elasticjob.lite.reachability.metadata.fixture.** + + + + + org.graalvm.buildtools + native-maven-plugin + ${native-maven-plugin.version} + true + + + build-native + + compile-no-fork + + package + + + test-native + + test + + test + + + + + true + Conditional + + + ${user.dir}/elasticjob-lite/elasticjob-lite-reachability-metadata/user-code-filter-elasticjob-lite-core.json + ${user.dir}/elasticjob-lite/elasticjob-lite-reachability-metadata/extra-filter.json + true + + + + + main + + false + ${user.dir}/elasticjob-lite/elasticjob-lite-reachability-metadata/src/main/resources/META-INF/native-image/org.apache.shardingsphere.elasticjob/elasticjob-lite-core + + + + + + + + nativeTestInElasticJob