Skip to content

Commit

Permalink
Publishing documentation for version 0.9.29-SNAPSHOT
Browse files Browse the repository at this point in the history
  • Loading branch information
@graalvmbot
graalvmbot committed Nov 27, 2023
1 parent 0bd4861 commit 6a380e6
Show file tree
Hide file tree
Showing 8 changed files with 135 additions and 280 deletions.
141 changes: 7 additions & 134 deletions 0.9.29-SNAPSHOT/gradle-plugin-quickstart.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -455,13 +455,8 @@ <h1>Getting Started with Gradle Plugin for GraalVM Native Image</h1>
<ul class="sectlevel1">
<li><a href="#_prepare_a_demo_application">Prepare a Demo Application</a></li>
<li><a href="#build-a-native-executable-with-resources-autodetection">Build a Native Executable with Resources Autodetection</a></li>
<li><a href="#build-a-native-executable-detecting-resources-with-the-agent">Build a Native Executable by Detecting Resources with the Agent</a>
<ul class="sectlevel2">
<li><a href="#_plugin_customization">Plugin Customization</a></li>
</ul>
</li>
<li><a href="#_add_junit_testing">Add JUnit Testing</a></li>
<li><a href="#_run_tests_with_the_agent">Run Tests with the Agent</a>
<li><a href="#build-a-native-executable-detecting-resources-with-the-agent">Build a Native Executable by Detecting Resources with the Agent</a></li>
<li><a href="#_add_junit_testing">Add JUnit Testing</a>
<ul class="sectlevel2">
<li><a href="#_summary">Summary</a></li>
</ul>
Expand All @@ -476,7 +471,7 @@ <h1>Getting Started with Gradle Plugin for GraalVM Native Image</h1>
<p>This guide shows how to get started with the <a href="gradle-plugin.html">Gradle plugin for GraalVM Native Image</a> and build a native executable for a Java application.</p>
</div>
<div class="paragraph">
<p>You will create a sample application, enable the plugin, add support for dynamic features, run JUnit tests, and build a native executable.</p>
<p>You will create a sample application, enable the plugin, add support for dynamic features, build a native executable, and run JUnit tests.</p>
</div>
<div class="paragraph">
<p>Two ways of building a native executable using the plugin will be demonstrated:</p>
Expand Down Expand Up @@ -611,7 +606,7 @@ <h2 id="_prepare_a_demo_application"><a class="anchor" href="#_prepare_a_demo_ap
</div>
</li>
<li>
<p>Delete the <em>fortune/src/test/java</em> directory, you will add tests in a later stage.</p>
<p>Delete the <em>fortune/src/test/java</em> directory (you will add tests in a later stage).</p>
</li>
<li>
<p>Copy and paste the following file,
Expand Down Expand Up @@ -674,19 +669,13 @@ <h2 id="_prepare_a_demo_application"><a class="anchor" href="#_prepare_a_demo_ap
<div class="listingblock multi-language-sample">
<div class="content">
<pre class="highlightjs highlight"><code data-lang="groovy" class="language-groovy hljs">plugins {
// ...

// Apply GraalVM Native Image plugin
id 'org.graalvm.buildtools.native' version '0.9.29-SNAPSHOT'
}</code></pre>
</div>
</div>
<div class="listingblock multi-language-sample">
<div class="content">
<pre class="highlightjs highlight"><code data-lang="kotlin" class="language-kotlin hljs">plugins {
// ...

// Apply GraalVM Native Image plugin
id("org.graalvm.buildtools.native") version "0.9.29-SNAPSHOT"
}</code></pre>
</div>
Expand Down Expand Up @@ -719,7 +708,6 @@ <h2 id="build-a-native-executable-with-resources-autodetection"><a class="anchor
binaries.all {
resources.autodetect()
}
toolchainDetection = false
}</code></pre>
</div>
</div>
Expand All @@ -729,51 +717,10 @@ <h2 id="build-a-native-executable-with-resources-autodetection"><a class="anchor
binaries.all {
resources.autodetect()
}
toolchainDetection.set(false)
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>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&#8217;s configuration.
For example:</p>
</div>
<div class="listingblock multi-language-sample">
<div class="content">
<pre class="highlightjs highlight"><code data-lang="groovy" class="language-groovy hljs">graalvmNative {
binaries {
main {
javaLauncher = javaToolchains.launcherFor {
languageVersion = JavaLanguageVersion.of(11)
vendor = JvmVendorSpec.matching("Oracle GraalVM")
}
}
}
}</code></pre>
</div>
</div>
<div class="listingblock multi-language-sample">
<div class="content">
<pre class="highlightjs highlight"><code data-lang="kotlin" class="language-kotlin hljs">graalvmNative {
binaries {
main {
javaLauncher = javaToolchains.launcherFor {
languageVersion = JavaLanguageVersion.of(11)
vendor = JvmVendorSpec.matching("Oracle GraalVM")
}
}
}
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>The workaround to this is to disable toolchain detection with this command <code>toolchainDetection = false</code>.</p>
</div>
</li>
</ol>
</div>
<div class="olist arabic">
<ol class="arabic" start="2">
<li>
<p>Compile the project and build a native executable at one step:</p>
<div class="listingblock">
Expand All @@ -792,12 +739,12 @@ <h2 id="build-a-native-executable-with-resources-autodetection"><a class="anchor
<pre class="highlightjs highlight"><code data-lang="shell" class="language-shell hljs">./fortune/build/native/nativeCompile/fortune</code></pre>
</div>
</div>
</li>
</ol>
</div>
<div class="paragraph">
<p>The application starts and prints a random quote.</p>
</div>
</li>
</ol>
</div>
<div class="paragraph">
<p>Configuring the <code>graalvmNative</code> plugin to automatically detect resources (<code>resources.autodetect()</code>) to be included in a binary is one way to make this example work.
Using <code>resources.autodetect()</code> works because the application uses resources (<em>fortunes.json</em>) which are directly available in the <code>src/main/resources</code> location.</p>
Expand Down Expand Up @@ -874,43 +821,6 @@ <h2 id="build-a-native-executable-detecting-resources-with-the-agent"><a class="
</li>
</ol>
</div>
<div class="paragraph">
<p>To see the benefits of running your application as a native executable, <code>time</code> how long it takes and compare the results with running as a Java application.</p>
</div>
<div class="sect2">
<h3 id="_plugin_customization"><a class="anchor" href="#_plugin_customization"></a>Plugin Customization</h3>
<div class="paragraph">
<p>You can customize the plugin. For example, change the name of the native executable and pass additional parameters to the plugin in the <em>build.gradle</em> file, as follows:</p>
</div>
<div class="listingblock multi-language-sample">
<div class="content">
<pre class="highlightjs highlight"><code data-lang="groovy" class="language-groovy hljs">graalvmNative {
binaries {
main {
imageName.set('fortuneteller')
buildArgs.add('--verbose')
}
}
}</code></pre>
</div>
</div>
<div class="listingblock multi-language-sample">
<div class="content">
<pre class="highlightjs highlight"><code data-lang="kotlin" class="language-kotlin hljs">graalvmNative {
binaries {
main {
imageName.set("fortuneteller")
buildArgs.add("--verbose")
}
}
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>The native executable then will be called <code>fortuneteller</code>.
Notice how you can pass additional arguments to the <code>native-image</code> tool using the <code>buildArgs.add</code> syntax.</p>
</div>
</div>
</div>
</div>
<div class="sect1">
Expand Down Expand Up @@ -976,39 +886,6 @@ <h2 id="_add_junit_testing"><a class="anchor" href="#_add_junit_testing"></a>Add
}</code></pre>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_run_tests_with_the_agent"><a class="anchor" href="#_run_tests_with_the_agent"></a>Run Tests with the Agent</h2>
<div class="sectionbody">
<div class="paragraph">
<p>If you need to test collecting metadata with the agent, add the <code>-Pagent</code> option to the <code>test</code> and <code>nativeTest</code> task invocations:</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>Run the tests on the JVM with the agent:</p>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code data-lang="shell" class="language-shell hljs">./gradlew -Pagent test</code></pre>
</div>
</div>
<div class="paragraph">
<p>It runs your application on the JVM with the agent, collects the metadata and uses it for testing on <code>native-image</code>.
The generated configuration files (containing the metadata) can be found in the <em>${buildDir}/native/agent-output/${taskName}</em> directory.
In this case, the plugin also substitutes <code>{output_dir}</code> in the agent options to point to this directory.</p>
</div>
</li>
<li>
<p>Build a native executable using the metadata collected by the agent:</p>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code data-lang="shell" class="language-shell hljs">./gradlew -Pagent nativeTest</code></pre>
</div>
</div>
</li>
</ol>
</div>
<div class="sect2">
<h3 id="_summary"><a class="anchor" href="#_summary"></a>Summary</h3>
<div class="paragraph">
Expand All @@ -1017,10 +894,6 @@ <h3 id="_summary"><a class="anchor" href="#_summary"></a>Summary</h3>
<a href="https://graalvm.github.io/native-build-tools/latest/gradle-plugin.html">plugin
reference documentation</a>.</p>
</div>
<div class="paragraph">
<p>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 <code>./gradlew nativeRun</code>.</p>
</div>
</div>
</div>
</div>
Expand Down
Binary file modified 0.9.29-SNAPSHOT/javadocs/native-gradle-plugin/member-search-index.zip
View file
Binary file not shown.
Binary file modified 0.9.29-SNAPSHOT/javadocs/native-gradle-plugin/package-search-index.zip
View file
Binary file not shown.
Binary file modified 0.9.29-SNAPSHOT/javadocs/native-gradle-plugin/type-search-index.zip
View file
Binary file not shown.
Binary file modified 0.9.29-SNAPSHOT/javadocs/native-maven-plugin/member-search-index.zip
View file
Binary file not shown.
Binary file modified 0.9.29-SNAPSHOT/javadocs/native-maven-plugin/package-search-index.zip
View file
Binary file not shown.
Binary file modified 0.9.29-SNAPSHOT/javadocs/native-maven-plugin/type-search-index.zip
View file
Binary file not shown.
Loading

0 comments on commit 6a380e6

Please sign in to comment.