diff --git a/docs/src/docs/asciidoc/end-to-end-gradle-guide.adoc b/docs/src/docs/asciidoc/end-to-end-gradle-guide.adoc index 2ec9539d..36ed1be6 100644 --- a/docs/src/docs/asciidoc/end-to-end-gradle-guide.adoc +++ b/docs/src/docs/asciidoc/end-to-end-gradle-guide.adoc @@ -102,7 +102,7 @@ graalvmNative { binaries.main { // options to configure the main binary imageName = 'application' - mainClass = 'org.test.Main' + mainClass = 'org.example.Main' buildArgs.add('-O3') // enables additional compiler optimizations } binaries.test { @@ -120,11 +120,10 @@ graalvmNative { // common options verbose.set(true) } - binaries.main { // options to configure the main binary imageName.set('application') - mainClass.set('org.test.Main') + mainClass.set('org.example.Main') buildArgs.add('-O3') // enables additional compiler optimizations } @@ -299,7 +298,7 @@ To enable the agent via the command line, pass the `-Pagent` option when running [source,bash, role="multi-language-sample"] ---- -./gradlew -Pagent nativeRun +./gradlew -Pagent run ---- [TIP] @@ -329,10 +328,12 @@ graalvmNative { } ---- -From that point on, commands you execute will run with the agent attached. +From that point on, commands like `run` or `test` will be executed with the agent attached. By default, the agent creates the metadata in the _build/native/agent-output_ directory. -Step 2: **Copy the generated metadata** from the default location, _build/native/agent-output_, to the resources directory, for example, _resources/META-INF/_. +Step 2: **Copy the generated metadata** from the default location, _build/native/agent-output_, to the resources directory, for example, _resources/META-INF/native-image_. +Native Image automatically takes metadata from that location. + To do that with Gradle, configure and run the `metadataCopy` task. Add a new task named `metadataCopy` inside the `graalvmNative` block. @@ -343,8 +344,8 @@ Your `agent` configuration should look like this: agent { enabled = true metadataCopy { - inputTaskNames.add("test") - outputDirectories.add("src/test/resources/META-INF/native-image/org.example") + inputTaskNames.add("run") + outputDirectories.add("src/main/resources/META-INF/native-image/org.example") mergeWithExisting = true } } @@ -355,8 +356,8 @@ agent { agent { enabled.set(true) metadataCopy { - inputTaskNames.add("test") - outputDirectories.add("resources/META-INF/native-image/org.example") + inputTaskNames.add("run") + outputDirectories.add("src/main/resources/META-INF/native-image/org.example") mergeWithExisting.set(true) } } diff --git a/docs/src/docs/asciidoc/end-to-end-maven-guide.adoc b/docs/src/docs/asciidoc/end-to-end-maven-guide.adoc index 0ef3e3a3..7e12bec3 100644 --- a/docs/src/docs/asciidoc/end-to-end-maven-guide.adoc +++ b/docs/src/docs/asciidoc/end-to-end-maven-guide.adoc @@ -73,7 +73,7 @@ For convenience, you can create a Maven profile and add the plugin into it: ---- -Replace `{maven-plugin-version}` with the latest released version. +Replace `maven-plugin-version` with the latest released version. All plugin versions are listed https://github.com/graalvm/native-build-tools/releases[here]. The `` tag provides the path to the application main class (the main entry point). @@ -182,6 +182,17 @@ The tests are compiled ahead of time and executed as native code. ---- +- Add surefire plugin into plugins section of your profile: + +[source,xml, role="multi-language-sample"] +---- + + org.apache.maven.plugins + maven-surefire-plugin + 3.0.0 + +---- + - Run the tests: [source,bash, role="multi-language-sample"] @@ -344,6 +355,13 @@ In such cases, additional metadata is required. The easiest way to collect the missing metadata is by using the https://www.graalvm.org/reference-manual/native-image/metadata/AutomaticMetadataCollection/[Tracing Agent]. This agent tracks all usages of dynamic features during application execution on the JVM and generates the necessary configuration. +[NOTE] +==== +In this guide we will show you how to generate metadata from your tests. +Generating metadata from your main application requires <>. +Other than that, the guide remains the same, except that you use the `package` phase instead of the `test` phase. +==== + The agent is disabled by default. You can enable it on the command line or in _pom.xml_. @@ -351,7 +369,7 @@ To enable the agent via the command line, pass the `-Dagent=true` option when ru [source,bash, role="multi-language-sample"] ---- -mvn -Pnative -Dagent=true package +mvn -Pnative -Dagent=true test ---- [TIP] @@ -366,7 +384,6 @@ Step 1: **Enable the agent** by setting `` to `true` in the `native` prof [source,xml, role="multi-language-sample"] ---- - org.example.Main true @@ -375,7 +392,9 @@ Step 1: **Enable the agent** by setting `` to `true` in the `native` prof From that point on, commands you execute will run with the agent attached. By default, the agent creates the metadata in the _target/native/agent-output_ directory. -Step 2: **Copy the generated metadata** from the default location, _target/native/agent-output/_, to the resources directory, for example, _resources/META-INF/_. +Step 2: **Copy the generated metadata** from the default location, _target/native/agent-output/_, to the resources directory, for example, _resources/META-INF/native-image_. +Native Image automatically takes metadata from that location. + To do that with Maven, configure and run the `metadataCopy` task. Add a new task named `metadataCopy` inside the `agent` block that you added in step 1. @@ -384,13 +403,12 @@ Your `agent` configuration should look like this: [source,xml, role="multi-language-sample"] ---- - true main true - resources/META-INF/ + src/test/resources/META-INF/native-image ---- @@ -405,14 +423,15 @@ Step 3: Now that the `metadataCopy` task is configured, **run the agent to colle [source,bash,subs="verbatim,attributes", role="multi-language-sample"] ---- -mvn -Pnative test native:metadata-copy +mvn -Pnative -Dagent=true test native:metadata-copy ---- -Step 4: Finally, **build the native image with the metadata** and run: +Step 4: Finally, you can proceed without the agent and **build the native image with the metadata from `META-INF` directory**. +From that point on, you can run your tests with: [source,bash, role="multi-language-sample"] ---- -mvn -Pnative package +mvn -Pnative test ---- If your native image is successfully build, but still fails at run time, check the troubleshooting guide https://www.graalvm.org/reference-manual/native-image/guides/troubleshoot-run-time-errors/[Troubleshoot Native Image Run-Time Errors]. @@ -453,6 +472,13 @@ When running on GraalVM for JDK 21, pass the `-H:+BuildReport` option instead to All the monitoring and debugging tools https://www.graalvm.org/reference-manual/native-image/debugging-and-diagnostics/[listed on the website], can be enabled in the plugin configuration using ``. +You will see the output of these tools among generated artifacts when you run: + +[source,bash, role="multi-language-sample"] +---- +mvn -Pnative -DskipNativeTests package +---- + === Learn more To continue learning, refer to the <>.