Skip to content

Commit

Permalink
Start sentences from a new line
Browse files Browse the repository at this point in the history
  • Loading branch information
@olyagpl
olyagpl committed Jun 28, 2023
1 parent cba01c5 commit 7b9332a
Show file tree
Hide file tree
Showing 2 changed files with 67 additions and 57 deletions.
69 changes: 38 additions & 31 deletions docs/src/docs/asciidoc/gradle-plugin-quickstart.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -125,7 +125,8 @@ public class Fortune {
----
. 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:
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:
+
[source,shell]
----
Expand Down Expand Up @@ -157,7 +158,8 @@ application {
mainClass = 'demo.Fortune'
}
----
. Add explicit FasterXML Jackson dependencies that provide functionality to read and write JSON, data bindings (used in the demo application). Insert the following three lines in the `dependencies` section of _build.gradle_:
. Add explicit FasterXML Jackson dependencies that provide functionality to read and write JSON, data bindings (used in the demo application).
Insert the following three lines in the `dependencies` section of _build.gradle_:
+
[source,xml]
----
Expand All @@ -170,8 +172,7 @@ Also, remove the dependency on `guava` that will not be used.
+
The next steps demonstrate what you should do to enable the
https://graalvm.github.io/native-build-tools/latest/gradle-plugin.html[Gradle Plugin for GraalVM Native Image].
. Register the plugin. Add the following to
`plugins` section of your project’s _build.gradle_ file:
. Register the plugin. Add the following to `plugins` section of your project’s _build.gradle_ file:
+
[source,groovy,subs="verbatim,attributes", role="multi-language-sample"]
----
Expand All @@ -193,10 +194,11 @@ plugins {
}
----
+
The `{gradle-plugin-version}` block pulls the latest plugin version. Replace it 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.
. The plugin is not yet available on the Gradle Plugin Portal, so declare an additional plugin repository. Open the _settings.gradle_ file and replace the default content with this:
The `{gradle-plugin-version}` block pulls the latest plugin version.
Replace it 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.
. The plugin is not yet available on the Gradle Plugin Portal, so declare an additional plugin repository.
Open the _settings.gradle_ file and replace the default content with this:
+
[source,groovy,subs="verbatim,attributes", role="multi-language-sample"]
----
Expand Down Expand Up @@ -229,11 +231,11 @@ Note that the `pluginManagement {}` block must appear before any other statement
[[build-a-native-executable-with-resources-autodetection]]
== Build a Native Executable with Resources Autodetection

You can already build a native executable by running
`./gradlew nativeCompile` or run it directly by invoking
`./gradlew nativeRun`. However, at this stage, running the native executable will fail because this application requires additional metadata: you need to provide it with a list of resources to load.
You can already build a native executable by running `./gradlew nativeCompile` or run it directly by invoking `./gradlew nativeRun`.
However, at this stage, running the native executable will fail because this application requires additional metadata: you need to provide it with a list of resources to load.

. Instruct the plugin to automatically detect resources to be included in the native executable. Add this to your `build.gradle` file:
. Instruct the plugin to automatically detect resources to be included in the native executable.
Add this to your _build.gradle_ file:
+
[source,groovy,subs="verbatim,attributes", role="multi-language-sample"]
----
Expand All @@ -255,7 +257,9 @@ graalvmNative {
}
----
+
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:
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"]
----
Expand Down Expand Up @@ -295,8 +299,7 @@ The workaround to this is to disable toolchain detection with this command `tool
./gradlew nativeRun
----
+
The native executable, named _fortune_, is created in the
_/fortune/build/native/nativeCompile_ directory.
The native executable, named _fortune_, is created in the _/fortune/build/native/nativeCompile_ directory.
[start=3]
. Run the native executable:
+
Expand All @@ -307,7 +310,8 @@ _/fortune/build/native/nativeCompile_ directory.

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. Using `resources.autodetect()` works because the application uses resources (_fortunes.json_) which are directly available in the `src/main/resources` location.
Configuring the `graalvmNative` plugin to automatically detect resources (`resources.autodetect()`) to be included in a binary is one way to make this example work.
Using `resources.autodetect()` works because the application uses resources (_fortunes.json_) which are directly available in the `src/main/resources` location.

In the next section, the guide shows that you can use the tracing agent to do the same.

Expand All @@ -316,11 +320,12 @@ In the next section, the guide shows that you can use the tracing agent to do th

The Native Image Gradle plugin simplifies generation of the required metadata by injecting the
https://graalvm.github.io/native-build-tools/latest/gradle-plugin.html#agent-support[
tracing agent] automatically for you at compile time. To enable the agent, just pass the `-Pagent` option to any Gradle tasks that extends `JavaForkOptions` (for example, `test` or `run`).
tracing agent] automatically for you at compile time.
To enable the agent, just pass the `-Pagent` option to any Gradle tasks that extends `JavaForkOptions` (for example, `test` or `run`).

The following steps illustrate how to collect metadata using the agent, and then build a native executable using that metadata.

. To demonstrate this approach, remove the `resources.autodetect()` block from your `build.gradle` file:
. To demonstrate this approach, remove the `resources.autodetect()` block from your _build.gradle_ file:
+
[source,shell]
----
Expand All @@ -335,8 +340,7 @@ binaries.all {
./gradlew -Pagent run
----
It runs your application on the JVM with the agent, collects the metadata, and generates configuration files in the _$\{buildDir}/native/agent-output/$\{taskName}_ directory.
. Copy the configuration files into the project's
_/META-INF/native-image_ directory using the `metadataCopy` task:
. Copy the configuration files into the project's _/META-INF/native-image_ directory using the `metadataCopy` task:
+
[source,shell]
----
Expand All @@ -349,8 +353,7 @@ _/META-INF/native-image_ directory using the `metadataCopy` task:
./gradlew nativeCompile
----
+
The native executable, named _fortune_, is created in the
_build/native/nativeCompile_ directory.
The native executable, named _fortune_, is created in the _build/native/nativeCompile_ directory.
. Run the native executable:
+
[source,shell]
Expand Down Expand Up @@ -390,12 +393,14 @@ graalvmNative {
}
----

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.
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
https://junit.org/junit5/docs/current/user-guide/[JUnit Platform] tests on your native executable. This means that the tests will be compiled and run as native code.
https://junit.org/junit5/docs/current/user-guide/[JUnit Platform] tests on your native executable.
This means that the tests will be compiled and run as native code.

. Create the following test in the
_fortune/src/test/java/demo/FortuneTest.java_ file:
Expand Down Expand Up @@ -427,7 +432,8 @@ class FortuneTest {
./gradlew nativeTest
----

The plugin runs tests on the JVM prior to running tests from the native executable. To disable testing support (which comes by default), add the following configuration to the _build.gradle_ file:
The plugin runs tests on the JVM prior to running tests from the native executable.
To disable testing support (which comes by default), add the following configuration to the _build.gradle_ file:

[source,groovy,subs="verbatim,attributes", role="multi-language-sample"]
----
Expand All @@ -445,8 +451,7 @@ 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:
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:
+
Expand All @@ -455,8 +460,8 @@ If you need to test collecting metadata with the agent, add the
./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.
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:
+
Expand All @@ -467,8 +472,10 @@ In this case, the plugin also substitutes `{output_dir}` in the agent options to

=== 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
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`.
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`.
55 changes: 29 additions & 26 deletions docs/src/docs/asciidoc/maven-plugin-quickstart.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -112,7 +112,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 _resources/_. Your project tree should be:
https://raw.githubusercontent.com/graalvm/graalvm-demos/master/fortune-demo/fortune/src/main/resources/fortunes.json[fortunes.json] under _resources/_.
Your project tree should be:
+
[source,shell]
----
Expand All @@ -138,7 +139,8 @@ https://raw.githubusercontent.com/graalvm/graalvm-demos/master/fortune-demo/fort
</dependency>
</dependencies>
----
. 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:
. 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:
+
[source,xml]
----
Expand Down Expand Up @@ -226,10 +228,10 @@ https://raw.githubusercontent.com/graalvm/graalvm-demos/master/fortune-demo/fort
</properties>
----
+
The statements "hardcoded" plugin versions and the entry point class to your application. The next steps demonstrate what you should do to enable the
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]
----
Expand Down Expand Up @@ -271,15 +273,14 @@ https://graalvm.github.io/native-build-tools/latest/maven-plugin.html[Maven plug
+
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).
`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: 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
`<enabled>true</enabled>` in the `native-maven-plugin` plugin
configuration:
- To enable the agent via the _pom.xml_ file, specify `<enabled>true</enabled>` in the `native-maven-plugin` plugin configuration:
+
[source,xml]
----
Expand All @@ -292,7 +293,8 @@ configuration:
- 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]
----
Expand Down Expand Up @@ -330,12 +332,12 @@ So your next step is to run with the agent.
</plugin>
----
+
Now you are all set to to build a native executable from a Java
application the plugin.
Now you are all set to to build a native executable from a Java application the plugin.

== 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:
. 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:
+
[source,shell]
----
Expand All @@ -348,7 +350,8 @@ 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`. Those files will be automatically used by the `native-image` tool if you pass the appropriate options.
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:
+
[source,shell]
Expand Down Expand Up @@ -379,14 +382,14 @@ 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
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

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.
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.

Expand All @@ -401,8 +404,7 @@ This plugin requires JUnit Platform 1.8 or higher and Maven Surefire 2.22.0 or h
<version>${native.maven.plugin.version}</version>
<extensions>true</extensions>
----
. Add an explicit dependency on the `junit-platform-launcher` artifact
to the dependencies section of your native profile configuration as in
. 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]
Expand All @@ -416,8 +418,7 @@ the following example:
</dependency>
</dependencies>
----
. 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:
+
.src/test/java/demo/FortuneTest.java
[source,java]
Expand Down Expand Up @@ -451,6 +452,8 @@ Run `-Pnative` profile will then build and run native 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 <<maven-plugin.adoc#,plugin reference documentation>>.
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 <<maven-plugin.adoc#,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 `mvn clean -Pnative package`.
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`.

0 comments on commit 7b9332a

Please sign in to comment.