diff --git a/docs/src/docs/asciidoc/gradle-plugin-quickstart.adoc b/docs/src/docs/asciidoc/gradle-plugin-quickstart.adoc index 21e8d5dae..73912408e 100644 --- a/docs/src/docs/asciidoc/gradle-plugin-quickstart.adoc +++ b/docs/src/docs/asciidoc/gradle-plugin-quickstart.adoc @@ -4,7 +4,7 @@ The GraalVM team This guide shows how to get started with the <> and build a native executable for a Java application. -You will create a sample application, enable the plugin, add support for dynamic features, run JUnit tests, and build a native executable. +You will create a sample application, enable the plugin, add support for dynamic features, build a native executable, and run JUnit tests. Two ways of building a native executable using the plugin will be demonstrated: @@ -113,7 +113,7 @@ public class Fortune { } } ---- -. Delete the _fortune/src/test/java_ directory, you will add tests in a later stage. +. Delete the _fortune/src/test/java_ directory (you will add tests in a later stage). . Copy and paste the following file, https://raw.githubusercontent.com/graalvm/graalvm-demos/master/fortune-demo/fortune/src/main/resources/fortunes.json[fortunes.json] under _fortune/src/main/resources/_. Your project tree should be: @@ -167,9 +167,6 @@ https://graalvm.github.io/native-build-tools/latest/gradle-plugin.html[Gradle Pl [source,groovy,subs="verbatim,attributes", role="multi-language-sample"] ---- plugins { - // ... - - // Apply GraalVM Native Image plugin id 'org.graalvm.buildtools.native' version '{gradle-plugin-version}' } ---- @@ -177,9 +174,6 @@ plugins { [source,kotlin,subs="verbatim,attributes",role="multi-language-sample"] ---- plugins { - // ... - - // Apply GraalVM Native Image plugin id("org.graalvm.buildtools.native") version "{gradle-plugin-version}" } ---- @@ -203,7 +197,6 @@ graalvmNative { binaries.all { resources.autodetect() } - toolchainDetection = false } ---- + @@ -213,44 +206,8 @@ graalvmNative { binaries.all { resources.autodetect() } - toolchainDetection.set(false) } ---- -+ -Another thing to note here: the plugin may not be able to properly detect the GraalVM installation, because of limitations in Gradle. -If you want to use Oracle GraalVM, or a particular version of GraalVM and Java, you need to explicitly tell this in plugin's configuration. -For example: -+ -[source,groovy,subs="verbatim,attributes", role="multi-language-sample"] ----- -graalvmNative { - binaries { - main { - javaLauncher = javaToolchains.launcherFor { - languageVersion = JavaLanguageVersion.of(11) - vendor = JvmVendorSpec.matching("Oracle GraalVM") - } - } - } -} ----- -+ -[source,kotlin,subs="verbatim,attributes", role="multi-language-sample"] ----- -graalvmNative { - binaries { - main { - javaLauncher = javaToolchains.launcherFor { - languageVersion = JavaLanguageVersion.of(11) - vendor = JvmVendorSpec.matching("Oracle GraalVM") - } - } - } -} ----- -+ -The workaround to this is to disable toolchain detection with this command `toolchainDetection = false`. - [start=2] . Compile the project and build a native executable at one step: + @@ -267,7 +224,7 @@ The native executable, named _fortune_, is created in the _/fortune/build/native ---- ./fortune/build/native/nativeCompile/fortune ---- - ++ The application starts and prints a random quote. Configuring the `graalvmNative` plugin to automatically detect resources (`resources.autodetect()`) to be included in a binary is one way to make this example work. @@ -323,39 +280,6 @@ The native executable, named _fortune_, is created in the _build/native/nativeCo + The application starts and prints a random quote. -To see the benefits of running your application as a native executable, `time` how long it takes and compare the results with running as a Java application. - -=== Plugin Customization - -You can customize the plugin. For example, change the name of the native executable and pass additional parameters to the plugin in the _build.gradle_ file, as follows: - -[source,groovy,subs="verbatim,attributes", role="multi-language-sample"] ----- -graalvmNative { - binaries { - main { - imageName.set('fortuneteller') - buildArgs.add('--verbose') - } - } -} ----- - -[source,kotlin,subs="verbatim,attributes", role="multi-language-sample"] ----- -graalvmNative { - binaries { - main { - imageName.set("fortuneteller") - buildArgs.add("--verbose") - } - } -} ----- - -The native executable then will be called `fortuneteller`. -Notice how you can pass additional arguments to the `native-image` tool using the `buildArgs.add` syntax. - == Add JUnit Testing The Gradle plugin for GraalVM Native Image can run @@ -409,33 +333,9 @@ graalvmNative { } ---- -== Run Tests with the Agent - -If you need to test collecting metadata with the agent, add the `-Pagent` option to the `test` and `nativeTest` task invocations: - -. Run the tests on the JVM with the agent: -+ -[source,shell] ----- -./gradlew -Pagent test ----- -+ -It runs your application on the JVM with the agent, collects the metadata and uses it for testing on `native-image`. -The generated configuration files (containing the metadata) can be found in the _$\{buildDir}/native/agent-output/$\{taskName}_ directory. -In this case, the plugin also substitutes `{output_dir}` in the agent options to point to this directory. -. Build a native executable using the metadata collected by the agent: -+ -[source,shell] ----- -./gradlew -Pagent nativeTest ----- - === Summary The Gradle plugin for GraalVM Native Image adds support for building and testing native executables using the https://gradle.org[Gradle]. The plugin has many features, described in the https://graalvm.github.io/native-build-tools/latest/gradle-plugin.html[plugin -reference documentation]. - -Note that if your application does not call any classes dynamically at run time, the execution with the agent is needless. -Your workflow, in that case, is just `./gradlew nativeRun`. +reference documentation]. \ No newline at end of file diff --git a/docs/src/docs/asciidoc/maven-plugin-quickstart.adoc b/docs/src/docs/asciidoc/maven-plugin-quickstart.adoc index a33dfc861..8c0dcb38c 100644 --- a/docs/src/docs/asciidoc/maven-plugin-quickstart.adoc +++ b/docs/src/docs/asciidoc/maven-plugin-quickstart.adoc @@ -4,7 +4,7 @@ The GraalVM team This guide shows how to get started with the <> and build a native executable for a Java application. -You will create a sample application, enable the plugin, add support for dynamic features, run JUnit tests, and build a native executable. +You will create a sample application, enable the plugin, add support for dynamic features, build a native executable, and run JUnit tests. ==== The plugin requires that you https://www.graalvm.org/latest/docs/getting-started/[setup GraalVM]. @@ -22,7 +22,7 @@ https://en.wikipedia.org/wiki/Fortune_(Unix)[fortune Unix program]. The data for the fortune phrases is provided by https://github.com/your-fortune[YourFortune]. ==== -. Create a new Java project with *Maven* in your favorite IDE, called _Fortune_ and make sure to choose +. Create a new Java project with *Maven* in your favorite IDE, called _Fortune_, in the package named _demo_. Make sure to choose https://mvnrepository.com/artifact/org.junit.jupiter/junit-jupiter[JUnit Jupiter] as the test engine. The _pom.xml_ file should look similar to the following. + @@ -49,7 +49,7 @@ should look similar to the following. ---- -. Create a package, named _demo_, and add the _Fortune.java_ (_src/main/java/demo/Fortune.java_) class. +. Create the _Fortune.java_ (_src/main/java/demo/Fortune.java_) class. + [source,java] ---- @@ -147,35 +147,35 @@ under the _resources_ directory (_src/main/resources/fortunes.json_). Your proje └── resources └── fortunes.json ---- -. Add explicit https://mvnrepository.com/artifact/com.fasterxml.jackson.core/jackson-databind[FasterXML Jackson] +. Add the https://mvnrepository.com/artifact/com.fasterxml.jackson.core/jackson-databind[FasterXML Jackson] dependency that provide functionality to read and write JSON, data bindings (used in the demo application). Open the _pom.xml_ file (a Maven configuration file), and insert the following in the `` section: + [source,xml] ---- - - com.fasterxml.jackson.core - jackson-databind - 2.16.0 - + + com.fasterxml.jackson.core + jackson-databind + 2.16.0 + ---- There should be two dependencies, the FasterXML Jackson dependency and the JUnit 5 dependency as shown below. + [source,xml] ---- - - - com.fasterxml.jackson.core - jackson-databind - 2.16.0 - - - org.junit.jupiter - junit-jupiter - 5.10.1 - test - - + + + com.fasterxml.jackson.core + jackson-databind + 2.16.0 + + + org.junit.jupiter + junit-jupiter + 5.10.1 + test + + ---- . Add regular Maven plugins for building and assembling a Maven project into an executable JAR. Insert the following into the `build` section in the _pom.xml_ file: @@ -268,8 +268,7 @@ Insert the following into the `build` section in the _pom.xml_ file: The statements "hardcoded" plugin versions and the entry point class to your application. The next steps demonstrate what you should do to enable the https://graalvm.github.io/native-build-tools/latest/maven-plugin.html[Maven plugin for GraalVM Native Image]. -. Register the Maven plugin for GraalVM Native Image, `native-maven-plugin`, in the profile called `native` by adding -the following to the _pom.xml_ file: +. Register the Maven plugin for GraalVM Native Image, `native-maven-plugin`, within a Maven profile, `native`, by adding the following to the _pom.xml_ file: + [source,xml] ---- @@ -308,73 +307,74 @@ the following to the _pom.xml_ file: ---- + -It pulls the latest plugin version. Replace `${native.maven.plugin.version}` with a specific version if you prefer. -The plugin discovers which JAR files it needs to pass to the `native-image` builder and what the executable main class -should be. With this plugin you can already build a native executable directly with Maven by running -`mvn -Pnative package` (if your application does not call any methods reflectively at run time). -+ -This demo application is a little more complicated than `HelloWorld`, and requires metadata before building a native -executable. You do not have to configure anything manually as the plugin can generate the required metadata for you by -injecting the https://graalvm.github.io/native-build-tools/latest/maven-plugin.html#agent-support[tracing agent] at -package time. The agent is disabled by default, and can be enabled in project's _pom.xml_ file or via the command line. - -- To enable the agent via the _pom.xml_ file, specify `true` in the `native-maven-plugin` plugin -configuration: +It pulls the latest plugin version. +Replace `${native.maven.plugin.version}` with a specific version if you prefer. +The plugin discovers which JAR files it needs to pass to the `native-image` builder and what the executable main class should be. +With this plugin you can already build a native executable directly with Maven by running `mvn -Pnative package` (if your application does not call any methods reflectively at run time). + +== Build a Native Executable by Detecting Resources with the Agent + +<<<<<<< HEAD +This demo application and requires metadata before building a native executable. +You do not have to configure anything manually: the plugin can generate the required configuration for you by injecting the https://graalvm.github.io/native-build-tools/latest/maven-plugin.html#agent-support[tracing agent] at package time. +======= +This demo application requires metadata before building a native executable. You do not have to configure anything manually: the plugin can generate the required configuration for you by injecting the https://graalvm.github.io/native-build-tools/latest/maven-plugin.html#agent-support[tracing agent] at package time. +>>>>>>> 24e5db3b (Remove extra word) +The agent is disabled by default, and can be enabled in project's _pom.xml_ file or via the command line. + +. To enable the agent via the _pom.xml_ file, specify `true` in the `native-maven-plugin` plugin configuration: + [source,xml] ---- - - false - - true - - + + false + + true + + ---- -- To enable the agent via the command line, pass the `-Dagent=true` option when running Maven. -+ -So your next step is to run with the agent. -. Before running with the agent, register a separate Mojo execution in the `native` profile which allows forking the -Java process. It is required to run your application with the agent. +To enable the agent via the command line, pass the `-Dagent=true` option when running Maven. + +. Before running with the agent, register a separate Mojo execution in the `native` profile which allows forking the Java process. +It is required to run your application with the agent. + [source,xml] ---- - - org.codehaus.mojo - exec-maven-plugin - 3.1.1 - - - java-agent - - exec - - - java - ${project.build.directory} - - -classpath - - ${mainClass} - - - - - native - - exec - - - ${project.build.directory}/${imageName} - ${project.build.directory} - - - - + + org.codehaus.mojo + exec-maven-plugin + 3.1.1 + + + java-agent + + exec + + + java + ${project.build.directory} + + -classpath + + ${mainClass} + + + + + native + + exec + + + ${project.build.directory}/${imageName} + ${project.build.directory} + + + + ---- + -Now you are all set to to build a native executable from a Java application the plugin. - -== Build a Native Executable +Now you are all set to to build a native executable. . Compile the project on the JVM to create a runnable JAR with all dependencies. Open a terminal window and, from the root application directory, run: @@ -399,21 +399,20 @@ Those files will be automatically used by the `native-image` tool if you pass th mvn -DskipTests=true -Pnative -Dagent package ---- + -When the command completes a native executable, _fortune_, is created in the _target_ directory of the project and -ready for use. +When the command completes, a native executable, _fortune_, is created in the _target_ directory of the project and ready for use. + The executable's name is derived from the artifact ID, but you can specify any custom name in `native-maven-plugin` by providing the `fortuneteller` within a `` node: + [source,xml] ---- - - false - fortuneteller - - true - - + + fortuneteller + false + + true + + ---- . Run the demo directly or with the Maven profile: + @@ -422,13 +421,7 @@ by providing the `fortuneteller` within a `true`: +. Enable extensions in the plugin's configuration, `true`: + [source,xml] ---- - - org.graalvm.buildtools - native-maven-plugin - ${native.maven.plugin.version} - true + + org.graalvm.buildtools + native-maven-plugin + ${native.maven.plugin.version} + true + ... + ---- -. Add an explicit dependency on the `junit-platform-launcher` artifact to the dependencies section of your native -profile configuration as in the following example: +. Add an explicit dependency on the `junit-platform-launcher` artifact in the dependencies section of your native profile configuration as in the following example: + [source,xml] ---- - - native - - - org.junit.platform - junit-platform-launcher - 1.10.0 - test - - + + native + + + org.junit.platform + junit-platform-launcher + 1.10.0 + test + + + ... + ---- . Create the following test in the _src/test/java/demo/FortuneTest.java_ file: + @@ -488,20 +483,16 @@ class FortuneTest { } ---- + -. Run native tests: +. Run JUnit tests: + [source,shell] ---- mvn -Pnative -Dagent test ---- + -Run `-Pnative` profile will then build and run native tests. Include the `-Dagent` is this is not enabled in the -_pom.xml_ file. +The `-Pnative` profile will then build and run JUnit tests. === Summary The Maven plugin for GraalVM Native Image adds support for building and testing native executables using https://maven.apache.org/[Apache Maven™]. -The plugin has many features, described in the <>. - -Note that if your application does not call any classes dynamically at run time, the execution with the agent is needless. -Your workflow, in that case, is just `mvn clean -Pnative package`. +The plugin has many features, described in the <>. \ No newline at end of file