Skip to content

Commit

Permalink
[#814] (Doc) Document how a CLI application can be packaged for distr…
Browse files Browse the repository at this point in the history 
…ibution.
  • Loading branch information
@remkop
remkop committed Sep 17, 2019
1 parent e02f5d2 commit 08f98c1
Show file tree
Hide file tree
Showing 3 changed files with 99 additions and 9 deletions.
3 changes: 2 additions & 1 deletion RELEASE-NOTES.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,8 @@ Picocli follows [semantic versioning](http://semver.org/).
## <a name="4.0.5-fixes"></a> Fixed issues
* [#811] (Bugfix) `CommandLine.setResourceBundle` did not propagate resource bundle to subcommands recursively. Thanks to [thope](https://github.com/frontfact) for the pull request with the bug fix.
* [#813] (Doc) Clarify usage of negatable boolean `@Option` with default value "true". Thanks to [Yann ROBERT](https://github.com/YannRobert) for raising this.

* [#814] (Doc) Document how a CLI application can be packaged for distribution.


## <a name="4.0.5-deprecated"></a> Deprecations
No features were deprecated in this release.
Expand Down
37 changes: 35 additions & 2 deletions docs/index.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4548,8 +4548,11 @@ image:https://www.osgi.org/wp-content/uploads/OSGi-website-header-logo.png[OSGi

From 4.0, the picocli JAR is an OSGi bundle with `Bundle-Name: picocli` and other appropriate metadata in the manifest.

== Packaging Your Application

== GraalVM Native Images
You finished your application. Congratulations! Now, how do you package it and distribute it to your users? Here are some ideas.

=== GraalVM Native Image

image:exe-picocli-on-graalvm.png[Turn your picocli-based application into a native image,width=265,height=150]

Expand All @@ -4569,12 +4572,42 @@ file.
By embedding these configuration files, your jar is instantly Graal-enabled: the
https://www.graalvm.org/docs/reference-manual/aot-compilation/#install-native-image[`native-image` tool]
used to generate the native executable is able to get the configuration from the jar.

In most cases no further configuration is needed when generating a native image.

GraalVM includes a https://medium.com/graalvm/simplifying-native-image-generation-with-maven-plugin-and-embeddable-configuration-d5b283b92f57[Maven plugin]
to generate a native image during the build.
Gradle users may be interested in the https://github.com/palantir/gradle-graal[gradle-graal] plugin by Palantir.
(Documentation for both of these seems sparse at time of this writing.)

This https://picocli.info/picocli-on-graalvm.html[older article], "Picocli on GraalVM: Blazingly Fast Command Line Apps", may still be useful.


=== Build Tool Plugins

Both https://www.mojohaus.org/appassembler/[Application Assembler Maven Plugin] and https://docs.gradle.org/current/userguide/application_plugin.html[Gradle Application plugin] create a distribution zip or tar file with launcher scripts. Both require a JRE to be installed on the target machine.

=== Launch4j and JDK 8 JavaPackage
http://launch4j.sourceforge.net/docs.html[launch4j] and JDK 8 https://docs.oracle.com/javase/8/docs/technotes/tools/windows/javapackager.html[javapackage] can create a native launcher executable. Both can bundle a JRE (~200MB) or use a pre-installed one.

=== jlink
With the JPMS module system introduced in Java 9 it became possible to use https://docs.oracle.com/javase/9/tools/jlink.htm#JSWOR-GUID-CECAC52B-CFEE-46CB-8166-F17A8E9280E9[`jlink`] to create a custom light-weight JRE with only the necessary modules.
This JRE may be as small as 30-40MB.
Use `jlink` with the `--launcher` option to generate launcher scripts for your application.

See https://medium.com/azulsystems/using-jlink-to-build-java-runtimes-for-non-modular-applications-9568c5e70ef4[this article] for using jlink for non-modular applications.

=== jpackage (Early Access)
https://jdk.java.net/jpackage/[`jpackage`] is an early access build of https://openjdk.java.net/jeps/343[JEP 343: Packaging Tool].
JPackage can take the custom light-weight JRE produced by `jlink` and create an installer and a native application launcher.
The result is a Java "application image" that is a single directory in the filesystem containing
the native application launcher, resources and configuration files,
and the custom light-weight JRE runtime image (including the application modules) produced by `jlink`.

This https://www.infoq.com/news/2019/03/jep-343-jpackage/[InfoQ article] has more details.
Gradle users may like these plugins: https://badass-runtime-plugin.beryx.org/releases/latest/[org.beryx Badass Runtime Plugin]
and https://badass-jlink-plugin.beryx.org/releases/latest/[org.beryx Badass JLink Plugin].


== Picocli in Other Languages
Picocli may be used in other JVM languages that support annotations.

Expand Down
68 changes: 62 additions & 6 deletions docs/index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -736,7 +736,15 @@ <h1>picocli - a mighty tiny command line interface</h1>
</ul>
</li>
<li><a href="#_osgi_bundle">25. OSGi Bundle</a></li>
<li><a href="#_graalvm_native_images">26. GraalVM Native Images</a></li>
<li><a href="#_packaging_your_application">26. Packaging Your Application</a>
<ul class="sectlevel2">
<li><a href="#_graalvm_native_image">26.1. GraalVM Native Image</a></li>
<li><a href="#_build_tool_plugins">26.2. Build Tool Plugins</a></li>
<li><a href="#_launch4j_and_jdk_8_javapackage">26.3. Launch4j and JDK 8 JavaPackage</a></li>
<li><a href="#_jlink">26.4. jlink</a></li>
<li><a href="#_jpackage_early_access">26.5. jpackage (Early Access)</a></li>
</ul>
</li>
<li><a href="#_picocli_in_other_languages">27. Picocli in Other Languages</a>
<ul class="sectlevel2">
<li><a href="#_groovy">27.1. Groovy</a></li>
Expand Down Expand Up @@ -794,7 +802,7 @@ <h2 id="_introduction">1. Introduction</h2>
Generates highly customizable usage help messages with <a href="#_ansi_colors_and_styles">ANSI colors and styles</a>.
Picocli-based applications can have <a href="autocomplete.html">command line TAB completion</a> showing available options, option parameters and subcommands, for any level of nested subcommands.
Picocli-based applications can be ahead-of-time compiled to <span class="image"><img src="https://www.graalvm.org/resources/img/logo-colored.svg" alt="GraalVM"></span>
<a href="#_graalvm_native_images">native images</a>, with extremely fast startup time and lower memory requirements, which can be distributed as a single executable file.</p>
<a href="#GraalVM Native Images">native images</a>, with extremely fast startup time and lower memory requirements, which can be distributed as a single executable file.</p>
</div>
<div class="paragraph">
<p><span class="image"><img src="images/checksum-usage-help.png" alt="Screenshot of usage help with Ansi codes enabled"></span></p>
Expand Down Expand Up @@ -7149,9 +7157,14 @@ <h2 id="_osgi_bundle">25. OSGi Bundle</h2>
</div>
</div>
<div class="sect1">
<h2 id="_graalvm_native_images">26. GraalVM Native Images</h2>
<h2 id="_packaging_your_application">26. Packaging Your Application</h2>
<div class="sectionbody">
<div class="paragraph">
<p>You finished your application. Congratulations! Now, how do you package it and distribute it to your users? Here are some ideas.</p>
</div>
<div class="sect2">
<h3 id="_graalvm_native_image">26.1. GraalVM Native Image</h3>
<div class="paragraph">
<p><span class="image"><img src="images/exe-picocli-on-graalvm.png" alt="Turn your picocli-based application into a native image" width="265" height="150"></span></p>
</div>
<div class="paragraph">
Expand All @@ -7173,15 +7186,58 @@ <h2 id="_graalvm_native_images">26. GraalVM Native Images</h2>
<div class="paragraph">
<p>By embedding these configuration files, your jar is instantly Graal-enabled: the
<a href="https://www.graalvm.org/docs/reference-manual/aot-compilation/#install-native-image"><code>native-image</code> tool</a>
used to generate the native executable is able to get the configuration from the jar.</p>
used to generate the native executable is able to get the configuration from the jar.
In most cases no further configuration is needed when generating a native image.</p>
</div>
<div class="paragraph">
<p>In most cases no further configuration is needed when generating a native image.</p>
<p>GraalVM includes a <a href="https://medium.com/graalvm/simplifying-native-image-generation-with-maven-plugin-and-embeddable-configuration-d5b283b92f57">Maven plugin</a>
to generate a native image during the build.
Gradle users may be interested in the <a href="https://github.com/palantir/gradle-graal">gradle-graal</a> plugin by Palantir.
(Documentation for both of these seems sparse at time of this writing.)</p>
</div>
<div class="paragraph">
<p>This <a href="https://picocli.info/picocli-on-graalvm.html">older article</a>, "Picocli on GraalVM: Blazingly Fast Command Line Apps", may still be useful.</p>
</div>
</div>
<div class="sect2">
<h3 id="_build_tool_plugins">26.2. Build Tool Plugins</h3>
<div class="paragraph">
<p>Both <a href="https://www.mojohaus.org/appassembler/">Application Assembler Maven Plugin</a> and <a href="https://docs.gradle.org/current/userguide/application_plugin.html">Gradle Application plugin</a> create a distribution zip or tar file with launcher scripts. Both require a JRE to be installed on the target machine.</p>
</div>
</div>
<div class="sect2">
<h3 id="_launch4j_and_jdk_8_javapackage">26.3. Launch4j and JDK 8 JavaPackage</h3>
<div class="paragraph">
<p><a href="http://launch4j.sourceforge.net/docs.html">launch4j</a> and JDK 8 <a href="https://docs.oracle.com/javase/8/docs/technotes/tools/windows/javapackager.html">javapackage</a> can create a native launcher executable. Both can bundle a JRE (~200MB) or use a pre-installed one.</p>
</div>
</div>
<div class="sect2">
<h3 id="_jlink">26.4. jlink</h3>
<div class="paragraph">
<p>With the JPMS module system introduced in Java 9 it became possible to use <a href="https://docs.oracle.com/javase/9/tools/jlink.htm#JSWOR-GUID-CECAC52B-CFEE-46CB-8166-F17A8E9280E9"><code>jlink</code></a> to create a custom light-weight JRE with only the necessary modules.
This JRE may be as small as 30-40MB.
Use <code>jlink</code> with the <code>--launcher</code> option to generate launcher scripts for your application.</p>
</div>
<div class="paragraph">
<p>See <a href="https://medium.com/azulsystems/using-jlink-to-build-java-runtimes-for-non-modular-applications-9568c5e70ef4">this article</a> for using jlink for non-modular applications.</p>
</div>
</div>
<div class="sect2">
<h3 id="_jpackage_early_access">26.5. jpackage (Early Access)</h3>
<div class="paragraph">
<p><a href="https://jdk.java.net/jpackage/"><code>jpackage</code></a> is an early access build of <a href="https://openjdk.java.net/jeps/343">JEP 343: Packaging Tool</a>.
JPackage can take the custom light-weight JRE produced by <code>jlink</code> and create an installer and a native application launcher.
The result is a Java "application image" that is a single directory in the filesystem containing
the native application launcher, resources and configuration files,
and the custom light-weight JRE runtime image (including the application modules) produced by <code>jlink</code>.</p>
</div>
<div class="paragraph">
<p>This <a href="https://www.infoq.com/news/2019/03/jep-343-jpackage/">InfoQ article</a> has more details.
Gradle users may like these plugins: <a href="https://badass-runtime-plugin.beryx.org/releases/latest/">org.beryx Badass Runtime Plugin</a>
and <a href="https://badass-jlink-plugin.beryx.org/releases/latest/">org.beryx Badass JLink Plugin</a>.</p>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_picocli_in_other_languages">27. Picocli in Other Languages</h2>
Expand Down Expand Up @@ -7499,7 +7555,7 @@ <h3 id="_source">34.5. Source</h3>
<div id="footer">
<div id="footer-text">
Version 4.0.4<br>
Last updated 2019-09-09 06:50:40 JST
Last updated 2019-09-17 19:48:08 JST
</div>
</div>
</body>
Expand Down

0 comments on commit 08f98c1

Please sign in to comment.