From dc85d10ee4ec9be111dde78f3b7098194ba76c8f Mon Sep 17 00:00:00 2001 From: Albert Attard Date: Thu, 23 Nov 2023 07:47:41 +0100 Subject: [PATCH 1/4] Bump dependencies versions --- .../asciidoc/maven-plugin-quickstart.adoc | 328 +++++++++++------- 1 file changed, 194 insertions(+), 134 deletions(-) diff --git a/docs/src/docs/asciidoc/maven-plugin-quickstart.adoc b/docs/src/docs/asciidoc/maven-plugin-quickstart.adoc index 960ead82..e20d765d 100644 --- a/docs/src/docs/asciidoc/maven-plugin-quickstart.adoc +++ b/docs/src/docs/asciidoc/maven-plugin-quickstart.adoc @@ -22,9 +22,34 @@ 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", in the _demo_ package. -Make sure to choose JUnit Jupiter as the test engine. -The application should contain a sole Java file with the following content: +. Create a new Java project with *Maven* in your favorite IDE, called `Fortune` and 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. ++ +[source,xml] +---- + + + 4.0.0 + + demo + fortune + 1.0.0 + Fortune Teller GraalVM Demo + + + + org.junit.jupiter + junit-jupiter + 5.10.1 + test + + + +---- + +Create a package, named `demo` and add the `Fortune.java` (`src/main/java/demo/Fortune.java`) class. + [source,java] ---- @@ -59,9 +84,9 @@ public class Fortune { while (elements.hasNext()) { JsonNode quote = elements.next().get("quote"); fortunes.add(quote.asText()); - } + } } - + private String readInputStream(InputStream is) { StringBuilder out = new StringBuilder(); try (InputStreamReader streamReader = new InputStreamReader(is, StandardCharsets.UTF_8); @@ -76,20 +101,25 @@ public class Fortune { } return out.toString(); } - + private void printRandomFortune() throws InterruptedException { - //Pick a random number - int r = RANDOM.nextInt(fortunes.size()); - //Use the random number to pick a random fortune - String f = fortunes.get(r); + //Pick a random fortune + String f = randomFortune(); // Print out the fortune s.l.o.w.l.y - for (char c: f.toCharArray()) { + for (char c : f.toCharArray()) { System.out.print(c); - Thread.sleep(100); + Thread.sleep(100); } System.out.println(); } + public String randomFortune() { + //Pick a random number + int r = RANDOM.nextInt(fortunes.size()); + //Use the random number to pick a random fortune + return fortunes.get(r); + } + /** * @param args the command line arguments * @throws java.lang.InterruptedException @@ -102,7 +132,7 @@ public class Fortune { } ---- . 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 _resources/_. +https://raw.githubusercontent.com/graalvm/graalvm-demos/master/fortune-demo/fortune/src/main/resources/fortunes.json[fortunes.json] under the `resources` directory. Your project tree should be: + [source,shell] @@ -117,20 +147,38 @@ Your project tree should be: └── resources └── fortunes.json ---- -. Add explicit FasterXML Jackson dependencies 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: +. Add explicit 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 + +---- +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.12.6.1 - - + + + 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: +Insert the following into the `build` section in the `pom.xml` file: + [source,xml] ---- @@ -139,7 +187,7 @@ Insert the following into the `build` section in the _pom.xml_ file: org.codehaus.mojo exec-maven-plugin - 3.0.0 + 3.1.1 java @@ -156,7 +204,7 @@ Insert the following into the `build` section in the _pom.xml_ file: org.apache.maven.plugins maven-compiler-plugin - 3.8.1 + 3.11.0 ${maven.compiler.source} ${maven.compiler.source} @@ -166,7 +214,7 @@ Insert the following into the `build` section in the _pom.xml_ file: org.apache.maven.plugins maven-jar-plugin - 3.2.2 + 3.3.0 @@ -180,6 +228,7 @@ Insert the following into the `build` section in the _pom.xml_ file: org.apache.maven.plugins maven-assembly-plugin + 3.6.0 package @@ -204,13 +253,12 @@ Insert the following into the `build` section in the _pom.xml_ file: ---- -. Replace the default `` section in the _pom.xml_ file with this content: +. Replace the default `` section in the `pom.xml` file with this content: + [source,xml,subs="verbatim,attributes"] ---- {maven-plugin-version} - 5.8.1 ${java.specification.version} ${java.specification.version} fortune @@ -221,105 +269,109 @@ 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`, in the profile called `native` by adding +the following to the `pom.xml` file: + [source,xml] ---- - - - native - - - - org.graalvm.buildtools - native-maven-plugin - ${native.maven.plugin.version} - true - - - build-native - - build - - package - - - test-native - - test - - test - - - - false - - - - - - + + + native + + + + org.graalvm.buildtools + native-maven-plugin + ${native.maven.plugin.version} + true + + + build-native + + compile-no-fork + + package + + + test-native + + test + + test + + + + false + + + + + + ---- + 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). +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: 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. +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: +- To enable the agent via the `pom.xml` file, specify `true` in the `native-maven-plugin` plugin +configuration: + [source,xml] ---- - - - true - - + + false + + true + + ---- -- To enable the agent via the command line, pass the `-Dagent=true` option when running Maven. -+ +- 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. +. 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.0.0 - - - 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. @@ -349,16 +401,21 @@ 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` within a -`` node: +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] ---- - - fortuneteller - + + false + fortuneteller + + true + + ---- . Run the demo directly or with the Maven profile: + @@ -372,8 +429,8 @@ The executable's name is derived from the artifact ID, but you can specify any c mvn -Pnative exec:exec@native ---- -To see the benefits of running your application as a native executable, `time` how long it takes and compare the results with running on the -JVM. +To see the benefits of running your application as a native executable, `time` how long it takes and compare the results +with running on the JVM. == Add JUnit Testing @@ -381,32 +438,35 @@ The Maven plugin for GraalVM Native Image can run https://junit.org/junit5/docs/current/user-guide/[JUnit Platform] tests on a native executable. This means that tests will be compiled and executed as native code. -This plugin requires JUnit Platform 1.8 or higher and Maven Surefire 2.22.0 or higher to run tests on a native executable. +This plugin requires JUnit Platform 1.10 or higher and Maven Surefire 2.22.0 or higher to run tests on a native +executable. . 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 to the dependencies section of your native +profile configuration as in the following example: + [source,xml] ---- - - - org.junit.platform - junit-platform-launcher - 1.8.2 - 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: + From 51dfcdc34eff824298710fc17e0ea70f463df39e Mon Sep 17 00:00:00 2001 From: Albert Attard Date: Thu, 23 Nov 2023 07:50:19 +0100 Subject: [PATCH 2/4] Fix formatting error --- docs/src/docs/asciidoc/maven-plugin-quickstart.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/docs/asciidoc/maven-plugin-quickstart.adoc b/docs/src/docs/asciidoc/maven-plugin-quickstart.adoc index e20d765d..4dfaba1b 100644 --- a/docs/src/docs/asciidoc/maven-plugin-quickstart.adoc +++ b/docs/src/docs/asciidoc/maven-plugin-quickstart.adoc @@ -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 a package, named `demo` and add the `Fortune.java` (`src/main/java/demo/Fortune.java`) class. + [source,java] ---- From 567f1167bef04dd3f99bf7e184a2728aa41cd7ef Mon Sep 17 00:00:00 2001 From: Albert Attard Date: Thu, 23 Nov 2023 08:13:40 +0100 Subject: [PATCH 3/4] Fix documentation mistakes --- .../asciidoc/maven-plugin-quickstart.adoc | 166 +++++++++--------- 1 file changed, 82 insertions(+), 84 deletions(-) diff --git a/docs/src/docs/asciidoc/maven-plugin-quickstart.adoc b/docs/src/docs/asciidoc/maven-plugin-quickstart.adoc index 4dfaba1b..95cb1ce4 100644 --- a/docs/src/docs/asciidoc/maven-plugin-quickstart.adoc +++ b/docs/src/docs/asciidoc/maven-plugin-quickstart.adoc @@ -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 a package, named `demo`, and add the `Fortune.java` (`src/main/java/demo/Fortune.java`) class. + [source,java] ---- @@ -182,88 +182,87 @@ Insert the following into the `build` section in the `pom.xml` file: + [source,xml] ---- - - - - org.codehaus.mojo - exec-maven-plugin - 3.1.1 - - - java - - java - - - ${mainClass} - - - - - - - org.apache.maven.plugins - maven-compiler-plugin - 3.11.0 - - ${maven.compiler.source} - ${maven.compiler.source} - - - - - org.apache.maven.plugins - maven-jar-plugin - 3.3.0 - - - - true - ${mainClass} - - - - - - - org.apache.maven.plugins - maven-assembly-plugin - 3.6.0 - - - package - - single - - - - - - - true - ${mainClass} - - - - jar-with-dependencies - - - - - - + + + + org.codehaus.mojo + exec-maven-plugin + 3.1.1 + + + java + + java + + + ${mainClass} + + + + + + + org.apache.maven.plugins + maven-compiler-plugin + 3.11.0 + + ${maven.compiler.source} + ${maven.compiler.source} + + + + + org.apache.maven.plugins + maven-jar-plugin + 3.3.0 + + + + true + ${mainClass} + + + + + + + org.apache.maven.plugins + maven-assembly-plugin + 3.6.0 + + + package + + single + + + + + + + true + ${mainClass} + + + + jar-with-dependencies + + + + + ---- . Replace the default `` section in the `pom.xml` file with this content: + [source,xml,subs="verbatim,attributes"] ---- - - {maven-plugin-version} - ${java.specification.version} - ${java.specification.version} - fortune - demo.Fortune - + + {maven-plugin-version} + ${java.specification.version} + ${java.specification.version} + fortune + demo.Fortune + ---- + The statements "hardcoded" plugin versions and the entry point class to your application. @@ -283,7 +282,6 @@ the following to the `pom.xml` file: org.graalvm.buildtools native-maven-plugin ${native.maven.plugin.version} - true build-native @@ -470,7 +468,6 @@ profile configuration as in the following example: ---- . Create the following test in the `src/test/java/demo/FortuneTest.java` file: + -.src/test/java/demo/FortuneTest.java [source,java] ---- package demo; @@ -479,14 +476,14 @@ import com.fasterxml.jackson.core.JsonProcessingException; import org.junit.jupiter.api.DisplayName; import org.junit.jupiter.api.Test; -import static org.junit.jupiter.api.Assertions.assertTrue; +import static org.junit.jupiter.api.Assertions.assertFalse; class FortuneTest { @Test @DisplayName("Returns a fortune") void testItWorks() throws JsonProcessingException { Fortune fortune = new Fortune(); - assertTrue(fortune.randomFortune().length()>0); + assertFalse(fortune.randomFortune().isEmpty()); } } ---- @@ -495,10 +492,11 @@ class FortuneTest { + [source,shell] ---- -mvn -Pnative test +mvn -Pnative -Dagent test ---- + -Run `-Pnative` profile will then build and run native tests. +Run `-Pnative` profile will then build and run native tests. Include the `-Dagent` is this is not enabled in the +`pom.xml` file. === Summary From 073657af7bb4f3cf41877c4366c1626b0483336d Mon Sep 17 00:00:00 2001 From: Albert Attard Date: Thu, 23 Nov 2023 11:50:10 +0100 Subject: [PATCH 4/4] Align with convention (italics for paths) --- .../asciidoc/maven-plugin-quickstart.adoc | 30 +++++++++---------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/docs/src/docs/asciidoc/maven-plugin-quickstart.adoc b/docs/src/docs/asciidoc/maven-plugin-quickstart.adoc index 95cb1ce4..a33dfc86 100644 --- a/docs/src/docs/asciidoc/maven-plugin-quickstart.adoc +++ b/docs/src/docs/asciidoc/maven-plugin-quickstart.adoc @@ -22,8 +22,8 @@ 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 -https://mvnrepository.com/artifact/org.junit.jupiter/junit-jupiter[JUnit Jupiter] as the test engine. The `pom.xml` file +. Create a new Java project with *Maven* in your favorite IDE, called _Fortune_ and 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. + [source,xml] @@ -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 a package, named _demo_, and add the _Fortune.java_ (_src/main/java/demo/Fortune.java_) class. + [source,java] ---- @@ -132,8 +132,8 @@ public class Fortune { } ---- . 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 the `resources` directory. -Your project tree should be: +https://raw.githubusercontent.com/graalvm/graalvm-demos/master/fortune-demo/fortune/src/main/resources/fortunes.json[fortunes.json] +under the _resources_ directory (_src/main/resources/fortunes.json_). Your project tree should be: + [source,shell] ---- @@ -149,7 +149,7 @@ Your project tree should be: ---- . Add explicit 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: +_pom.xml_ file (a Maven configuration file), and insert the following in the `` section: + [source,xml] ---- @@ -178,7 +178,7 @@ There should be two dependencies, the FasterXML Jackson dependency and the JUnit ---- . 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: +Insert the following into the `build` section in the _pom.xml_ file: + [source,xml] ---- @@ -252,7 +252,7 @@ Insert the following into the `build` section in the `pom.xml` file: ---- -. Replace the default `` section in the `pom.xml` file with this content: +. Replace the default `` section in the _pom.xml_ file with this content: + [source,xml,subs="verbatim,attributes"] ---- @@ -269,7 +269,7 @@ The statements "hardcoded" plugin versions and the entry point class to your app 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: +the following to the _pom.xml_ file: + [source,xml] ---- @@ -316,9 +316,9 @@ should be. With this plugin you can already build a native executable directly w 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. +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 +- To enable the agent via the _pom.xml_ file, specify `true` in the `native-maven-plugin` plugin configuration: + [source,xml] @@ -390,7 +390,7 @@ mvn clean package mvn -Pnative -Dagent exec:exec@java-agent ---- + -The agent collects the metadata and generates the configuration files in a subdirectory of `target/native/agent-output`. +The agent collects the metadata and generates the configuration files in a subdirectory of _target/native/agent-output_. Those files will be automatically used by the `native-image` tool if you pass the appropriate options. . Now build a native executable with the Maven profile: + @@ -399,7 +399,7 @@ 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 +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` @@ -466,7 +466,7 @@ profile configuration as in the following example: ---- -. Create the following test in the `src/test/java/demo/FortuneTest.java` file: +. Create the following test in the _src/test/java/demo/FortuneTest.java_ file: + [source,java] ---- @@ -496,7 +496,7 @@ 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. +_pom.xml_ file. === Summary