https://github.com/vertx-howtos/jlink-howto
Assembling a small runtime image of a modular Vert.x application with jlink
https://github.com/vertx-howtos/jlink-howto
howto jlink jpms vertx
Last synced: about 1 month ago
JSON representation
Assembling a small runtime image of a modular Vert.x application with jlink
- Host: GitHub
- URL: https://github.com/vertx-howtos/jlink-howto
- Owner: vertx-howtos
- License: apache-2.0
- Created: 2025-02-03T14:42:26.000Z (over 1 year ago)
- Default Branch: master
- Last Pushed: 2025-02-04T10:28:39.000Z (over 1 year ago)
- Last Synced: 2026-04-06T16:41:49.449Z (2 months ago)
- Topics: howto, jlink, jpms, vertx
- Language: Java
- Homepage:
- Size: 24.4 KB
- Stars: 0
- Watchers: 5
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.adoc
- License: LICENSE
Awesome Lists containing this project
README
= Assembling a small runtime image of a modular Vert.x application with jlink
:page-permalink: /
:page-github: vertx-howtos/jlink-howto
ifdef::env-github[]
image:https://github.com/vertx-howtos/jlink-howto/workflows/Publish%20the%20how-to/badge.svg["Build Status",link="https://github.com/vertx-howtos/jlink-howto/actions?query=workflow%3A%22Publish+the+how-to%22"]
endif::env-github[]
This document will show you how to assemble a small runtime image of a modular Vert.x application with jlink.
== What you need
* A text editor or an IDE
* Java 11 or higher
== Create a project
Here is the content of the Maven `pom.xml` file you should be using:
ifdef::env-github[]
link:pom.xml[Maven POM file]
endif::env-github[]
ifndef::env-github[]
[source,xml]
.Maven `pom.xml`
----
include::pom.xml[]
----
<1> The https://maven.apache.org/plugins/maven-jlink-plugin/[Apache Maven JLink Plugin] will take care of invoking the `jlink` command-line tool.
<2> Mandatory classifier for the custom runtime image archive that will be attached as a Maven artifact.
<3> `server` is the name of the launcher script to generate via jlink.
This is optional.
<4> Add the `jdk.jdwp.agent` module so that we can attach a remote debugger, if we need to.
endif::env-github[]
== Implementing the application
The server setup code fits into a single class, `io.vertx.howtos.jlink.ServerVerticle`:
ifdef::env-github[]
link:src/main/java/io/vertx/howtos/jlink/ServerVerticle.java[ServerVerticle.java]
endif::env-github[]
ifndef::env-github[]
[source,java]
----
include::src/main/java/io/vertx/howtos/jlink/ServerVerticle.java[]
----
endif::env-github[]
A custom application launcher provides a factory for the main verticle to deploy:
ifdef::env-github[]
link:src/main/java/io/vertx/howtos/jlink/CustomLauncher.java[CustomLauncher.java]
endif::env-github[]
ifndef::env-github[]
[source,java]
----
include::src/main/java/io/vertx/howtos/jlink/CustomLauncher.java[]
----
endif::env-github[]
Having the verticle factory in `io.vertx.howtos.jlink.CustomLauncher` simplifies the Java module configuration:
ifdef::env-github[]
link:src/main/java/module-info.java[module-info.java]
endif::env-github[]
ifndef::env-github[]
[source,java]
----
include::src/main/java/module-info.java[]
----
endif::env-github[]
Indeed, since the verticle instance won't be created via reflection, we don't have to export our application package to the `io.vertx.core` module, we just have to declare a few required modules.
== Building the application
On Linux or other Unix-like systems, run the following command:
[source,bash]
----
./mvnw clean package
----
On Microsoft Windows:
[source,shell]
----
mvnw.cmd clean package
----
Notice that all required modules are resolved before `jlink` creates the custom runtime image.
----
[INFO] --- jlink:3.2.0:jlink (jlink) @ jlink-howto ---
[INFO] -> module: io.netty.handler ( /path/to/my/mavenrepo/io/netty/netty-handler/4.2.0.RC1/netty-handler-4.2.0.RC1.jar )
[INFO] -> module: io.vertx.web ( /path/to/my/mavenrepo/io/vertx/vertx-web/5.0.0.CR4/vertx-web-5.0.0.CR4.jar )
[INFO] -> module: io.vertx.core ( /path/to/my/mavenrepo/io/vertx/vertx-core/5.0.0.CR4/vertx-core-5.0.0.CR4.jar )
[INFO] -> module: io.netty.handler.proxy ( /path/to/my/mavenrepo/io/netty/netty-handler-proxy/4.2.0.RC1/netty-handler-proxy-4.2.0.RC1.jar )
[INFO] -> module: com.fasterxml.jackson.core ( /path/to/my/mavenrepo/com/fasterxml/jackson/core/jackson-core/2.16.1/jackson-core-2.16.1.jar )
[INFO] -> module: io.netty.codec.unused ( /path/to/my/mavenrepo/io/netty/netty-codec/4.2.0.RC1/netty-codec-4.2.0.RC1.jar )
[INFO] -> module: io.vertx.launcher.application ( /path/to/my/mavenrepo/io/vertx/vertx-launcher-application/5.0.0.CR4/vertx-launcher-application-5.0.0.CR4.jar )
[INFO] -> module: io.vertx.auth.common ( /path/to/my/mavenrepo/io/vertx/vertx-auth-common/5.0.0.CR4/vertx-auth-common-5.0.0.CR4.jar )
[INFO] -> module: info.picocli ( /path/to/my/mavenrepo/info/picocli/picocli/4.7.4/picocli-4.7.4.jar )
[INFO] -> module: io.vertx.howtos.jlink ( /path/to/my/Projects/vertx-howtos/jlink-howto/target/classes )
[INFO] -> module: io.netty.transport.unix.common ( /path/to/my/mavenrepo/io/netty/netty-transport-native-unix-common/4.2.0.RC1/netty-transport-native-unix-common-4.2.0.RC1.jar )
[INFO] -> module: io.netty.codec.compression ( /path/to/my/mavenrepo/io/netty/netty-codec-compression/4.2.0.RC1/netty-codec-compression-4.2.0.RC1.jar )
[INFO] -> module: io.vertx.web.common ( /path/to/my/mavenrepo/io/vertx/vertx-web-common/5.0.0.CR4/vertx-web-common-5.0.0.CR4.jar )
[INFO] -> module: io.netty.buffer ( /path/to/my/mavenrepo/io/netty/netty-buffer/4.2.0.RC1/netty-buffer-4.2.0.RC1.jar )
[INFO] -> module: io.netty.codec.http2 ( /path/to/my/mavenrepo/io/netty/netty-codec-http2/4.2.0.RC1/netty-codec-http2-4.2.0.RC1.jar )
[INFO] -> module: io.vertx.core.logging ( /path/to/my/mavenrepo/io/vertx/vertx-core-logging/5.0.0.CR4/vertx-core-logging-5.0.0.CR4.jar )
[INFO] -> module: io.netty.common ( /path/to/my/mavenrepo/io/netty/netty-common/4.2.0.RC1/netty-common-4.2.0.RC1.jar )
[INFO] -> module: io.netty.resolver.dns ( /path/to/my/mavenrepo/io/netty/netty-resolver-dns/4.2.0.RC1/netty-resolver-dns-4.2.0.RC1.jar )
[INFO] -> module: io.netty.codec.http ( /path/to/my/mavenrepo/io/netty/netty-codec-http/4.2.0.RC1/netty-codec-http-4.2.0.RC1.jar )
[INFO] -> module: io.netty.codec.socks ( /path/to/my/mavenrepo/io/netty/netty-codec-socks/4.2.0.RC1/netty-codec-socks-4.2.0.RC1.jar )
[INFO] -> module: io.netty.codec.dns ( /path/to/my/mavenrepo/io/netty/netty-codec-dns/4.2.0.RC1/netty-codec-dns-4.2.0.RC1.jar )
[INFO] -> module: io.netty.transport ( /path/to/my/mavenrepo/io/netty/netty-transport/4.2.0.RC1/netty-transport-4.2.0.RC1.jar )
[INFO] -> module: io.netty.codec ( /path/to/my/mavenrepo/io/netty/netty-codec-base/4.2.0.RC1/netty-codec-base-4.2.0.RC1.jar )
[INFO] -> module: io.netty.resolver ( /path/to/my/mavenrepo/io/netty/netty-resolver/4.2.0.RC1/netty-resolver-4.2.0.RC1.jar )
[INFO] -> module: io.vertx.eventbusbridge ( /path/to/my/mavenrepo/io/vertx/vertx-bridge-common/5.0.0.CR4/vertx-bridge-common-5.0.0.CR4.jar )
[INFO] Building zip: /path/to/my/vertx-howtos/jlink-howto/target/jlink-howto-dist.zip
----
== Running the application
Extract the `target/jlink-howto-dist.zip` archive somewhere on your disk.
On Linux or other Unix-like systems, you can do this with the following command:
[source,bash]
----
unzip -d target/jlink-howto target/jlink-howto-dist.zip
----
Inspect the total size of the custom runtime image folder.
On Linux or other Unix-like systems, you can do this with the following command:
[source,bash]
----
du -sh target/jlink-howto
----
On my machine, the result is 68 MB.
In comparison, the total size of the JDK 11 distribution is 312 MB.
It's time to give the application a try.
On Linux or other Unix-like systems, you can do this with the following command:
[source,bash]
----
target/jlink-howto/bin/java --module io.vertx.howtos.jlink/io.vertx.howtos.jlink.CustomLauncher
----
Or, you can use the generated `server` script:
[source,bash]
----
target/jlink-howto/bin/server
----
You should see something like:
----
Feb 03, 2025 6:48:31 PM io.vertx.howtos.jlink.ServerVerticle lambda$start$1
INFO: HTTP server started on port 8888
Feb 03, 2025 6:48:31 PM io.vertx.launcher.application.VertxApplication
INFO: Succeeded in deploying verticle
----
Now, browse to http://localhost:8888 and verify that a greeting is displayed in the browser.
[NOTE]
====
When the launcher script is used, it's not possible to specify VM options (heap size, remote debugging, etc.) as arguments.
You can either change the `JLINK_VM_OPTIONS` variable in the `server` script or use the `java` command.
For example, for remote debugging on Linux or other Unix-like systems:
[source,bash]
----
target/jlink-howto/bin/java \
-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=*:5005 \
--module io.vertx.howtos.jlink/io.vertx.howtos.jlink.CustomLauncher
----
====
== Summary
This document covered:
. creating a modular Vert.x Web application,
. assembling a custom runtime image with jlink.
== See also
* The https://vertx.io/docs/guides/modular-vertx-guide/[Modular Vert.x Guide]