Desktop Packaging
The quarkus-desktop-packaging extension packages a desktop application as the installers of Windows, macOS and
Linux, at the end of the build: from its native executable or, in JVM mode, from its jar with a Java runtime. It does
not depend on a user interface toolkit: it packages AWT, Swing, SWT and JavaFX applications alike, with or without the
other extensions of Quarkus Desktop.
| Format | Operating system | What it is | Tool of the build machine |
|---|---|---|---|
|
all |
The application image: the directory of the application (an application bundle on macOS), which the other formats install |
none for a native executable; a JDK with |
|
Windows |
A Windows Installer package |
WiX Toolset 4 or later ( |
|
Windows |
A setup program with a wizard and an uninstaller |
Inno Setup 6.3 or later ( |
|
Windows |
An MSIX package |
|
|
macOS |
A disk image, with a link to the |
|
|
macOS |
An installer package |
|
|
Linux |
A Debian package |
|
|
Linux |
An RPM package |
|
|
Linux |
An AppImage: one executable file, without installation |
appimagetool, on the |
|
Linux |
A Flatpak bundle |
|
|
Linux |
A snap |
|
A package is built on its operating system, with the tool of its format: nothing is cross-built. The extension finds
the tools on the PATH and where their installers put them, and the build fails with what to install when one is
missing; quarkus.desktop.packaging.tools.<name> gives the path of a tool that is elsewhere. The tools of all the
formats, the name, the icon, the content directory, the certificate file and what the formats derive from the
configuration (the identifier, the version…) are checked before anything is packaged, and in a native build before the native executable is built: a missing tool or an invalid
value fails the build at once, rather than after the native build and the first packages.
Installation
<dependency>
<groupId>io.quarkiverse.desktop</groupId>
<artifactId>quarkus-desktop-packaging</artifactId>
<version>1.0.0</version>
</dependency>
implementation("io.quarkiverse.desktop:quarkus-desktop-packaging:1.0.0")
Building packages
Nothing is packaged by default. quarkus.desktop.packaging.formats lists the packages to build; the formats of the
other operating systems are skipped, so that one list serves the builds of the three of them:
quarkus.desktop.packaging.name=Acme Editor
quarkus.desktop.packaging.identifier=org.acme.editor
quarkus.desktop.packaging.vendor=Acme
quarkus.desktop.packaging.description=Edits documents
quarkus.desktop.packaging.formats=msi,exe,dmg,deb,rpm,appimage
./mvnw package -Dnative # the native executable, packaged
./mvnw package # the jar, packaged with a Java runtime
The packages are in target/packaging (build/packaging with Gradle; quarkus.desktop.packaging.output-directory,
relative to the build directory or absolute), the application image in target/packaging/image, and the generated files of each format (the WiX source,
the Inno Setup script, the spec file…) in target/packaging/work. A package is named after the application, its
version and its architecture, so that the packages of an x64 and an arm64 build can be in the same release
(Acme-Editor-1.2.3-x64.msi, Acme-Editor-1.2.3-arm64.dmg, Acme-Editor-1.2.3-x86_64.AppImage); the Debian, RPM and
snap packages follow the conventions of their format (acme-editor_1.2.3-1_amd64.deb,
acme-editor-1.2.3-1.x86_64.rpm). The directory is not cleaned: a package of an earlier build with another name,
version or format stays there until ./mvnw clean. The formats may also be given on the command line, to package in
the release build only: -Dquarkus.desktop.packaging.formats=msi, in quotes in PowerShell
("-Dquarkus.desktop.packaging.formats=msi"), which splits an unquoted -D argument at its first dot.
A native executable built in a container (quarkus.native.container-build=true) is a Linux executable: on Windows and
macOS, the extension warns that it packages nothing, as a package is built on its operating system. Build the native
executable without a container to get the packages of Windows or macOS, and on Linux to get the Linux packages.
The packages are not the artifact of the Quarkus build: the jar or the native executable still is (for
@QuarkusIntegrationTest, for the container image extensions).
The application
| Property | What it is |
|---|---|
|
The name that the users see: the shortcuts, the installed program, the application bundle. Defaults to
|
|
Defaults to |
|
A reverse domain name ( |
|
What the installers and the package managers show |
|
A square PNG file of 512 or 1024 pixels. Defaults to |
|
A directory of files added to the application image, next to the executable (in |
On Linux, the package and the command are named after linux.package-name: the name in lowercase ASCII with dashes
(acme-editor, and cafe-manager for Café Manager) by default. The files of the packages are named after the name
in ASCII too (Acme-Editeur-1.2.3-x64.msi). For a name without letters or digits in ASCII (in Arabic, Chinese or
Russian), these names and the default identifier come from quarkus.application.name (the artifact ID) instead.
The packages are built for the architecture of the native executable: an x64 executable, which an x64 GraalVM builds on
Windows arm64, gives x64 packages. In JVM mode, they are built for the architecture of the JVM of the build, which the
JDK of jvm.jdk has to have too.
The application image
Every package installs the same application image, which the directory format keeps as the result.
Native executable
The image has the native executable, under the name of the application, and the shared libraries that are next to it
when the build ends (*.dll, *.so, *.dylib, *.jnilib): the libraries of the JDK that an AWT executable
loads, the libraries of SWT (with quarkus.desktop.swt.native-libraries=next-to-executable, which suits a package:
nothing is extracted to the home directory of the user). Build from a clean directory (./mvnw clean package): a
library left by another build would be packaged too.
A native build with profile-guided optimization (quarkus.native.pgo.enabled) builds an instrumented executable, and
the optimized one after the integration tests (the quarkus:build-enhanced-artifact goal): the instrumented one is not
packaged, with a warning, and a second build packages the optimized one, which it reuses
(./mvnw package -Dnative "-Dquarkus.native.reuse-existing=true"). Nothing is packaged either when the native build
writes a native-image bundle (quarkus.native.bundle.enabled) instead of an executable.
On macOS, the image is an application bundle (Acme Editor.app), with its Info.plist and its icon.
macos.info-plist.<key> adds entries, such as the usage descriptions of the privacy permissions.
On Windows, the executable of the image is named after the application (Acme Editor.exe). The libraries of the JDK
that an AWT executable loads call the JVM through two libraries that native-image links with the executable by its
file name (jvm.dll, java.dll): the extension changes the name that they import in the image. A name that is not
ASCII cannot be imported: the executable then keeps the name of the build, which quarkus.package.output-name and
quarkus.package.jar.add-runner-suffix=false choose. Choose an ASCII name there: Windows loads the libraries of an
executable whose name is not ASCII only on the machines whose ANSI code page is the one of the build machine.
The Windows image also has the Visual C++ runtime that the executable and its libraries import, which is not part of
Windows (the Visual C++ Redistributable installs it): native-image links every executable with vcruntime140.dll,
and the libraries of the JDK need msvcp140.dll and vcruntime140_1.dll. The extension copies them from the JDK of the
native build (quarkus.native.graalvm-home, else quarkus.native.java-home, the JDK of the build by default), unless
the image has them already: Desktop AWT copies them next to an AWT executable, and the content directory may have them.
The Windows native executable also gets the icon of the application and its version information (the Details tab of its
properties). They are linked in the executable when it is built, so the extension has to be in the application then,
with or without packages; windows.executable-resources=false disables it. An application that links a resource file
of its own (-H:NativeLinkerOption=app.res in quarkus.native.additional-build-args) keeps it, without the resources
of the extension; one linked in another way, such as a native-image.properties file, conflicts with them (the link
fails with CVT1100: duplicate resource) unless windows.executable-resources=false. Native sources
(quarkus.native.sources-only=true) and native-image bundles (quarkus.native.bundle.*) do not get them: they are
linked from a file of the build directory, which the machine that compiles the sources or applies the bundle may not
have. The subsystem of the executable (no console window) is an option of the
toolkit extensions: quarkus.desktop.awt.windows.subsystem=windows or quarkus.desktop.swt.windows.subsystem=windows.
JVM mode
In JVM mode, the image is built by jpackage --type app-image: the jar of the application (a fast-jar, an aot-jar or
an uber-jar), a Java runtime built by jlink, and a launcher with the icon of the application. The JDK of the build
provides jpackage and the modules of the runtime, rather than the JDK of the PATH, unless jvm.jdk names another
one, of version 21 or later.
# a smaller Java runtime than the default one
quarkus.desktop.packaging.jvm.modules=java.desktop,java.net.http
quarkus.desktop.packaging.jvm.options=-Xms64m,-Xmx512m
By default, the runtime has the modules of Java SE and of the JDK that export an API, and the modules that provide
their services, which the jpackage of JDK 25 leaves out and the extension adds: the locale data (jdk.localedata),
the charsets that are not standard (jdk.charsets), the key stores of Windows (jdk.crypto.mscapi), PKCS#11
(jdk.crypto.cryptoki), the DNS and RMI naming providers (jdk.naming.dns, jdk.naming.rmi). With jvm.modules,
the runtime has the listed modules and the ones that Quarkus itself needs (java.logging, java.naming, jdk.jfr,
jdk.unsupported, jdk.zipfs), which the extension adds, with jdk.crypto.ec on JDK 21, which TLS needs. jlink
does not add the modules that provide services to such a list: add jdk.localedata for the dates and numbers of the
languages other than English, and the others that the application uses. An application that misses a module fails
when it uses it, so test the packaged application. jvm.runtime-image gives a Java runtime instead, which jpackage
takes as it is: jvm.modules and jvm.jlink-options cannot be set with it. The launcher of a fast-jar or an aot-jar
has the runner jar as its class path, as java -jar quarkus-run.jar has. The AppCDS or AOT archive that
quarkus.package.jar.aot.enabled has Quarkus write next to the runner jar is not in the image: it was built for the
JDK of the build, not for the Java runtime of the image.
The options of jvm.options are separated by commas, and each one is one argument of the JVM, white space and quotes
included (-Dapp.title=Acme Editor): the build warns about one that holds several options (-Xms64m -Xmx512m), which
the JVM rejects. The long form of an option with its value after a space (--add-opens java.base/java.lang=ALL-UNNAMED)
is written with =. Write the paths with /, which Java accepts on Windows (-Djava.library.path=$APPDIR/native): in
a list, \ escapes the next character, and C:\lib is C:lib. An option with a comma or a backslash is set in an
indexed property, and the other options then too, as the indexed properties replace the list:
quarkus.desktop.packaging.jvm.options[0]=-Xmx512m
quarkus.desktop.packaging.jvm.options[1]=-Djdk.tls.client.protocols=TLSv1.2,TLSv1.3
The options that the extensions of the application need come first (-XstartOnFirstThread for SWT on macOS).
On macOS, the bundle that jpackage writes gets macos.minimum-system-version and the entries of macos.info-plist,
as the bundle of a native executable: an entry replaces the one of jpackage of the same key, and the values true
and false are Booleans. The bundle identifier of both is the identifier of the application without underscores,
which macOS and jpackage do not allow: org._7zip.Editor is org.7zip.Editor, and org.acme.my_app is
org.acme.my-app.
Windows
windows.per-user=true makes the MSI package and the setup program install for the current user, without
administrator rights (in %LocalAppData%\Programs); they install in Program Files for all users otherwise.
windows.start-menu, windows.start-menu-group and windows.desktop-shortcut choose the shortcuts. The shortcuts of
an application with an SWT user interface have the AppUserModelID that SWT gives its process (quarkus.desktop.swt.application-name as the
build sees it), so that the windows of the application and its shortcut pinned to the taskbar are one button. The
Windows packages install the files of the application image: an empty directory is left out, with a warning.
The WiX Toolset and Inno Setup do not read a file whose path has 260 characters or more, even where Windows allows
longer paths: the build of the MSI package and of the setup program fails then, with the path of the file. A JVM
application gets there sooner: its jars are in target\packaging\image\<name>\app\lib\main\, and some of their names
have about 100 characters. Build the project from a shorter directory, or set output-directory to a short absolute
directory (C:\packaging).
The MSI package and the setup program of a new version replace the installed version of their format: they recognize
it by its upgrade code, derived from the identifier of the application (or given by windows.upgrade-code, a GUID with
or without braces). They refuse to install over each other, as they would share the files of the application: a
machine gets the application from one of the two. The MSI package removes the installed version first; the setup
program installs over it, in its directory, where it only deletes the jars and the Java runtime of a JVM application:
when the name of the application changes, the executable and the shortcut of the former name stay until the
application is removed. A first installation, or one in another directory, deletes nothing.
An MSIX package declares a full trust desktop application (runFullTrust), and the capabilities of
windows.msix.capabilities: general ones (internetClient), restricted ones (allowElevation), and the others with
their kind (rescap:packageQuery, uap:documentsLibrary, device:microphone). Windows only installs it when it is
signed, and its publisher (windows.msix.publisher, CN=<vendor> by default) has to be the subject of the signing
certificate, as Windows writes it: (Get-PfxCertificate acme.pfx).Subject in PowerShell prints it. Windows identifies
the package by its name, publisher, version and architecture, and refuses a rebuilt package of the installed version
(error 0x80073CFB): remove the installed package first (Remove-AppxPackage), or raise the version, as the builds
of a snapshot have the same one (1.2.3-SNAPSHOT is 1.2.3.0).
With a certificate, signtool of the Windows SDK signs the launcher of the application, the libraries and executables
of the application image that have no signature (such as the jvm.dll and java.dll that native-image links), the
three packages, and the uninstaller of the setup program:
quarkus.desktop.packaging.windows.sign.certificate-file=acme.pfx
quarkus.desktop.packaging.windows.sign.certificate-password=${SIGN_PASSWORD}
quarkus.desktop.packaging.windows.sign.timestamp-url=http://timestamp.digicert.com
windows.sign.subject-name or windows.sign.thumbprint select a certificate of the certificate store instead.
windows.sign.arguments adds arguments to signtool sign, and signs on its own: a signing service such as Azure
Trusted Signing, a key of a cryptographic provider (/csp, /kc), a certificate of the machine store (/sm). Write
its paths absolute, with /: the setup program is signed in the directory of Inno Setup, and in a list, \ escapes
the next character. signtool takes an option once: the extension passes /fd SHA256 unless the arguments have a
/fd, which then sets the hash of the MSIX package too, and /tr <url> /td SHA256 for windows.sign.timestamp-url,
without the /td when the arguments have one. The command that a signing service documents can then be copied as it
is, without its /tr when windows.sign.timestamp-url is set: the build refuses both.
quarkus.desktop.packaging.windows.sign.timestamp-url=http://timestamp.acs.microsoft.com
quarkus.desktop.packaging.windows.sign.arguments=/dlib,C:/tools/Azure.CodeSigning.Dlib.dll,/dmdf,C:/tools/metadata.json
The build logs what it signs, and with what certificate, or that nothing is signed. It warns when
windows.sign.certificate-password or windows.sign.timestamp-url is set without a certificate, as when the
certificate is an expression of a variable that the build does not define (a secret that a job does not have): the
value is then empty. It also warns when the signatures have no time stamp: they become invalid when the certificate
expires.
macOS
The application bundle is signed with an ad hoc signature by default: it runs on the machine that built it, and Gatekeeper blocks it on the others. To distribute the application, sign it with a Developer ID certificate, and have the packages notarized:
quarkus.desktop.packaging.macos.sign.identity=Developer ID Application: Acme (ABCDE12345)
quarkus.desktop.packaging.macos.sign.installer-identity=Developer ID Installer: Acme (ABCDE12345)
# xcrun notarytool store-credentials acme
quarkus.desktop.packaging.macos.notarize.keychain-profile=acme
With a certificate, the libraries, the executables and the bundle are signed with the hardened runtime and a secure
time stamp. The hardened runtime only loads the libraries signed by Apple or with the identity of the application,
unless an entitlement allows the others: a JVM application gets the entitlements that a JVM needs, and a native
executable the one that allows them (com.apple.security.cs.disable-library-validation), for the libraries that it
loads from outside the bundle, such as the ones that SWT extracts to the home directory of the user by default
(quarkus.desktop.swt.native-libraries=next-to-executable puts them in the bundle, signed with it).
macos.sign.entitlements replaces them.
The disk image is signed too, the installer package is signed with the installer identity, and with a keychain profile
both are submitted to the notary service and stapled: the build waits for the answer of Apple (macos.notarize.timeout
limits the wait: 30m, 2h), logs it with the identifier of the submission, and fails with the log of the submission,
which lists the problems, when Apple does not accept a package. Apple only accepts packages signed with Developer ID
identities: the build fails before building them when the bundle is not signed with a certificate, or when the
installer package has no installer identity. Without a keychain profile, the build warns that the packages of a bundle
signed with a certificate are not notarized, and that an installer package without an installer identity is not
signed: Gatekeeper blocks them on the machines that download them.
The notary service checks the macOS libraries inside the jars of a JVM application too (JNA, FlatLaf, sqlite-jdbc…):
with a certificate, the ones that their vendor did not sign with a certificate are signed in their jars, and the others
keep the signature of their vendor. A signed jar (META-INF/*.SF) cannot be changed: when one of its libraries is not
signed with a certificate, the build fails if the packages are notarized, and otherwise warns and leaves the jar as it
is. The hardened runtime then loads that library only with the com.apple.security.cs.disable-library-validation
entitlement, which the entitlements of a JVM have.
With macos.sign.enabled=false, nothing is signed, not even the installer package with macos.sign.installer-identity,
except the bundle of a JVM application that jpackage signed ad hoc (on Apple silicon): it is signed ad hoc again once
the extension has changed it, so that its signature stays valid.
In the bundle of a native executable, an entry of macos.info-plist replaces the one of the extension of the same key
(NSHighResolutionCapable, CFBundleName…), and the values true and false are Booleans.
The installer package installs the bundle in /Applications (macos.install-location).
Linux
The Debian and RPM packages install the application image in /opt/<package-name> (linux.install-directory), a link
to its launcher in /usr/bin, a desktop entry (linux.categories, linux.startup-wm-class), the icons of the
hicolor theme and the license-file. The Debian package is compressed with xz, which every dpkg reads (dpkg-deb
compresses with zstd on Ubuntu, which the dpkg of Debian 11 cannot read). The window class of the desktop entry of
every Linux package (linux.startup-wm-class) defaults to the one that SWT gives the windows of an application with
an SWT user interface
(quarkus.desktop.swt.application-name as the build sees it): the desktops match them with the entry.
The Debian package depends on the packages of the shared libraries that the application is linked with
(dpkg-shlibdeps), and rpmbuild finds the ones of the RPM package. dpkg-shlibdeps finds the packages of the
libraries installed on the machine of the build: a library that is missing there is not a dependency, and the build
warns about it. The dependencies are the packages of the distribution of the build, with their minimum versions, as
is the version of glibc that a native executable needs: build on the oldest distribution to support. The library
packages that Ubuntu 24.04 and Debian 13 renamed for the 64-bit time_t
(libasound2t64) get their former names as alternatives (libasound2t64 (>= 1.0.16) | libasound2 (>= 1.0.16)): the
package of a JVM application built there installs on the releases before them too.
Neither tool sees the libraries that the application opens at run time (dlopen): AWT opens fontconfig, CUPS and GTK
that way. List them:
quarkus.desktop.packaging.linux.deb.depends=libfontconfig1,libcups2
quarkus.desktop.packaging.linux.rpm.requires=fontconfig,cups-libs
Nor do they see the libraries of a native executable compressed with UPX (quarkus.native.compression.level), which
has no dynamic section: the build warns about it, and they have to be listed too (libc6 and glibc, for instance).
The libraries that SWT loads only in some cases, its GTK 4 port (with SWT_GTK4=1) and its OpenGL library (for a
GLCanvas), are left out of the analysis: the packages of an SWT application built with
quarkus.desktop.swt.native-libraries=next-to-executable depend on GTK 3, not on GTK 4 or OpenGL, which an application
that uses them lists too (libgtk-4-1 and libgl1 in linux.deb.depends, gtk4 and libglvnd-glx in
linux.rpm.requires).
An AppImage has the application image, not the libraries of the system: it runs where they are installed.
appimagetool downloads the runtime of the AppImage from GitHub at each build: for a build without access to GitHub,
or with a runtime of a known version, download the runtime-<arch> file of a
release of the runtime once, and give it in
linux.appimage.runtime-file.
The Flatpak bundle is built with the flatpak command alone, 1.2.1 or later: the build directory is written by the
extension, neither flatpak-builder nor the SDK are needed, and nothing runs in a sandbox, so that the bundle builds
in a container too. The runtime (linux.flatpak.runtime, org.freedesktop.Platform by default) is installed with the
bundle, from Flathub. Its version (linux.flatpak.runtime-version, 25.08 by default) is a branch of the runtime,
which reaches its end of life after one or two years and then gets no security fixes: it follows the releases of the
runtime. The default runtime has GTK 3, which SWT needs. org.gnome.Platform also has WebKitGTK, which the Browser
widget of SWT uses: it goes with its SDK, and its versions are the ones of GNOME:
quarkus.desktop.packaging.linux.flatpak.runtime=org.gnome.Platform
quarkus.desktop.packaging.linux.flatpak.sdk=org.gnome.Sdk
quarkus.desktop.packaging.linux.flatpak.runtime-version=50
linux.flatpak.finish-args are the permissions of the sandbox.
The snap is built by snapcraft pack from a generated project, whose application uses the gnome extension (the
libraries of a desktop application), which supports the strict and devmode confinements: a classic snap
(linux.snap.confinement=classic) has no extension, with linux.snap.extensions set to an empty value
(quarkus.desktop.packaging.linux.snap.extensions=). Snapcraft builds in an LXD container by default, which the build
deletes afterwards (snapcraft clean): a stopped container would otherwise remain for each build.
linux.snap.build-args=--destructive-mode builds on the host, on the Ubuntu release of the base snap, without a
container.
A strictly confined snap cannot write the hidden directories of the home directory, where SWT extracts its native
libraries (~/.swt): in a snap, the Desktop SWT extension has SWT extract them into
$SNAP_USER_COMMON/.swt/lib/<os>/<arch> instead, unless swt.library.path is set. A native executable built with
quarkus.desktop.swt.native-libraries=next-to-executable loads them from the snap, without extracting them.
File types and URL schemes
The packages register the application for the types of files that it opens and for its URL schemes, so that the file managers, the browsers and the other applications open them with it:
quarkus.desktop.packaging.file-types.document.extensions=acme,acmex
quarkus.desktop.packaging.file-types.document.description=Acme document
quarkus.desktop.packaging.file-types.document.icon=src/main/packaging/document.png
# acme://...
quarkus.desktop.packaging.url-schemes=acme
A file type has a name (document), its extensions, a MIME type (application/x-<package name>-<type> by default),
a description (the name of the application and the name of the type by default), and an icon (the icon of the
application by default). Each format registers them its way:
-
the MSI package and the setup program: the registry keys of the extensions, of a programmatic identifier per type (
<identifier>.<type>) and of the URL schemes, for the current user or for all users as the package installs, removed with the application; -
the MSIX package: its
windows.fileTypeAssociationandwindows.protocolextensions (an extension with a dot, such astar.gz, is refused: MSIX takes the last one only); -
the macOS bundle:
CFBundleDocumentTypes,UTExportedTypeDeclarations(the uniform type identifier<bundle identifier>.<type>) andCFBundleURLTypesof itsInfo.plist, in both modes; -
the Linux packages: the
MimeTypeof the desktop entry (x-scheme-handler/<scheme>for the URL schemes), and a shared-mime-info file that declares the MIME types of the extensions. The snap has the desktop entry only: its file types need MIME types that the system already knows.
On Windows and Linux, the system starts the application with the file or the URL as an argument (a file may be a
file:// URL on Linux, which Desktop AWT and Desktop SWT take for the file; Windows may start an MSIX application
without it). On macOS, it sends the running application an event instead, also when the file starts it.
Desktop AWT and Desktop SWT receive both, and fire an OpenRequest with the files and the URLs on the thread of the user
interface, after DesktopStartupEvent (SwtStartupEvent): an argument is a file to open when it names an existing
file of a registered extension, and a URL to open when its scheme is a registered one; the other arguments are the
application’s own. With quarkus.desktop.awt.single-instance=true (quarkus.desktop.swt.single-instance=true), a
second launch gives its files and URLs to the instance that already runs, which fires the OpenRequest, and exits, on
every operating system and in production only (not in dev mode or tests): see
Application model and CDI and Desktop SWT.
Automatic updates
Two formats update the application themselves, from where the packages are published:
-
the MSIX package: with
windows.msix.update-url, the URL of the directory of the packages, the build writes an App Installer file next to the package (<name>-<architecture>.appinstaller, without the version: Windows reads it again at its URL to find the next version, whose file replaces it). Publish both files in that directory, and give the users the URL of the App Installer file: Windows installs the package from it, and looks for a new version at the start of the application, everywindows.msix.update-hourshours (24 by default); -
the AppImage: with
linux.appimage.update-information(gh-releases-zsync|acme|editor|latest|Acme-Editor-*-x86_64.AppImage.zsyncfor the releases of GitHub, orzsync|https://acme.org/downloads/Acme-Editor-x86_64.AppImage.zsync), the AppImage carries the information, and the build writes its.zsyncfile next to it (withzsyncmakeof thezsyncpackage), to publish with it: AppImageUpdate and AppImageLauncher update the AppImage from it.
The Flatpak bundle and the snap are updated by their repositories and stores, and the Debian and RPM packages by the repositories of their package managers (apt, dnf), where the extension does not publish them. The MSI package, the setup program, the disk image and the installer package have no updates of their own: an application that wants them checks a feed of its versions, and downloads and runs the package of the new one.
For extension authors
The quarkus-desktop-packaging-spi artifact has build items for the deployment modules of other extensions:
-
NativeExecutableFileBuildItem: a file that the native executable needs next to it. The build steps that write files next to the executable after the native build produce it (or declare that they do), which also makes the packages wait for them. Desktop AWT and Desktop SWT do. On macOS,codesigntakes every file ofContents/MacOSfor code: a file that is not code (not a Mach-O file) goes to the same path inContents/Resources, with a symbolic link to it next to the executable. A library that the executable loads only in some cases is optional: the Debian and RPM packages do not depend on the libraries that it is linked with. -
PackagedJvmOptionBuildItem: an option of the JVM that the application needs in JVM mode, for one operating system or for all of them. -
ApplicationIdBuildItem: the name that the application gives itself at run time, the AppUserModelID of its process on Windows and the class of its windows on Linux, which the shortcuts and the desktop entry of the packages get. Desktop SWT produces it for an SWT user interface. -
PackagedApplicationNameBuildItem, which this extension produces: thenameof the configuration, when it is set, which Desktop AWT and Desktop SWT give the application by default.
Continuous integration
A job per operating system builds the packages of each of them, as the packaging job of the
build workflow of this project
does:
jobs:
package:
strategy:
matrix:
os: [ ubuntu-latest, windows-latest, macos-latest ]
runs-on: ${{ matrix.os }}
steps:
- uses: actions/checkout@v7
- uses: graalvm/setup-graalvm@v1
with:
java-version: '25'
distribution: 'graalvm'
- if: runner.os == 'Windows'
run: |
dotnet tool install --global wix --version 5.0.2
if (-not (Test-Path "${env:ProgramFiles(x86)}\Inno Setup 6\ISCC.exe")) { choco install innosetup -y --no-progress }
- if: runner.os == 'Linux'
run: |
sudo apt-get update
sudo apt-get install -y rpm dpkg-dev
- run: ./mvnw -B package -Dnative "-Dquarkus.desktop.packaging.formats=msi,exe,dmg,pkg,deb,rpm"
- uses: actions/upload-artifact@v4
with:
name: packages-${{ matrix.os }}
path: |
target/packaging/*.*
The steps run in the default shell of each runner: PowerShell on Windows, where the step of the tools installs Inno Setup
when the runner does not have it, and where the formats are in quotes, as PowerShell splits an unquoted -D argument at
its first dot. The Linux packages get the dependencies of the distribution of the runner (see Linux).
Limitations
-
No cross-building: each package is built on its operating system, and for the architecture of the native executable or, in JVM mode, of the JVM of the build. A native executable built in a container is a Linux executable, packaged on Linux only.
-
A second launch of the application gives its files to the running instance with
single-instanceof Desktop AWT and Desktop SWT only. -
Automatic updates through the App Installer file of the MSIX package, the update information of the AppImage, and the stores and repositories only (see Automatic updates).
-
The packages of the application stores (the Microsoft Store, the Mac App Store, Flathub, the Snap Store) need their own submission steps, which the extension does not do.
Configuration reference
Configuration property fixed at build time - All other configuration properties are overridable at runtime
Configuration property |
Type |
Default |
|---|---|---|
Whether the extension does anything : the packages, and the icon and version of the Windows native executable. Environment variable: |
boolean |
|
The packages to build : A native build ( Environment variable: |
list of |
|
The name of the application, as its users see it : the name of the shortcuts, of the installed program, of the application bundle on macOS. Defaults to Environment variable: |
string |
|
The version of the application. Defaults to Environment variable: |
string |
|
The identifier of the application, a reverse domain name such as Environment variable: |
string |
|
The vendor of the application : the publisher on Windows, the maintainer of the Linux packages. Environment variable: |
string |
|
A one line description of the application. Defaults to its name. Environment variable: |
string |
|
The copyright notice of the application. Environment variable: |
string |
|
The home page of the application. Environment variable: |
string |
|
The license of the application, as a text file : shown by the Windows setup program and by the macOS installer package, installed with the Debian and RPM packages. Environment variable: |
string |
|
The icon of the application, a square PNG file of 512 or 1024 pixels : the extension derives the icons of every format from it ( Environment variable: |
string |
|
A directory of files to add to the application image : documents, data files. They are next to the executable, in Environment variable: |
string |
|
The directory of the packages, relative to the build directory ( Environment variable: |
string |
|
The paths of the packaging tools that are not on the Environment variable: |
Map<String,String> |
|
The extensions of the files, without their dot ( Environment variable: |
list of string |
required |
The MIME type of the files, which Linux knows the files by. Defaults to Environment variable: |
string |
|
The description of the type, which the file managers show. Defaults to the name of the application followed by the name of the type. Environment variable: |
string |
|
The icon of the files, a square PNG file of 256 pixels or more. Defaults to the icon of the application. Environment variable: |
string |
|
The URL schemes of the application ( Environment variable: |
list of string |
|
Whether the native executable gets the icon of the application and its version information (the Details tab of its properties : product name, version, vendor, copyright). They are resources linked in the executable when it is built : the extension has to be in the application then, with or without packages. Native sources ( Environment variable: |
boolean |
|
The upgrade code of the application, a GUID, with or without braces : the Windows installers of the next versions upgrade the application that has the same code. Defaults to a GUID derived from the identifier of the application : never change either once the application is released. Environment variable: |
string |
|
Whether the application is installed for the current user only, without administrator rights (in Environment variable: |
boolean |
|
The name of the installation directory. Defaults to the name of the application. Environment variable: |
string |
|
Whether the installers add a shortcut to the Start menu. Environment variable: |
boolean |
|
The folder of the shortcut in the Start menu. None by default : the shortcut is in the programs folder. Environment variable: |
string |
|
Whether the installers add a shortcut to the desktop : the MSI package always does, the setup program lets the user choose. Environment variable: |
boolean |
|
The name of the identity of the package : letters, digits, dots and dashes. Defaults to the identifier of the application. Environment variable: |
string |
|
The publisher of the package, a distinguished name that has to be the subject of the certificate that signs the package ( Environment variable: |
string |
|
The name of the publisher, as the users see it. Defaults to the vendor. Environment variable: |
string |
|
The capabilities of the application : general capabilities ( Environment variable: |
list of string |
|
The minimum version of Windows that installs the package : four numbers, such as Environment variable: |
string |
|
The URL of the directory where the MSIX package is published ( Environment variable: |
string |
|
How often Windows looks for a new version of an application installed from the App Installer file, in hours, when it starts : Environment variable: |
int |
|
The certificate file ( Environment variable: |
string |
|
The password of the certificate file. Environment variable: |
string |
|
The subject name of the signing certificate, in the certificate store. Environment variable: |
string |
|
The SHA-1 thumbprint of the signing certificate, in the certificate store. Environment variable: |
string |
|
The URL of the RFC 3161 time stamp server. Environment variable: |
string |
|
More arguments of Environment variable: |
list of string |
|
The category of the application ( Environment variable: |
string |
|
The minimum version of macOS that runs the application ( Environment variable: |
string |
|
More entries of the Environment variable: |
Map<String,String> |
|
The directory where the installer package installs the application bundle. Environment variable: |
string |
|
Whether the application bundle and the packages are signed. When they are not, whatever the identities, the bundle of a JVM application that Environment variable: |
boolean |
|
The identity that signs the application bundle and the disk image, a Environment variable: |
string |
|
The identity that signs the installer package, a Environment variable: |
string |
|
The entitlements of the application, a property list file, in place of the default ones. With a certificate, the hardened runtime only loads the libraries signed by Apple or with the identity of the application, unless an entitlement allows the others. By default, a JVM application has the entitlements that the JVM needs (just-in-time compilation, unsigned executable memory, libraries of other teams), and a native executable signed with a certificate has the one of the libraries of other teams ( Environment variable: |
string |
|
The keychain of the identities. Defaults to the keychains of the user. Environment variable: |
string |
|
The keychain profile of the credentials of the notary service, stored with Environment variable: |
string |
|
How long the build waits for the answer of the notary service, as the Environment variable: |
string |
|
The name of the package and of the command of the application : lowercase letters, digits and dashes. Defaults to the name of the application, in that form. Environment variable: |
string |
|
The directory where the Debian and RPM packages install the application, in a directory named after the package : an absolute directory other than Environment variable: |
string |
|
The categories of the desktop entry, which place the application in the menus. Environment variable: |
list of string |
|
The window class of the application ( Environment variable: |
string |
|
The release of the Debian and RPM packages : the version of the package itself, for a given version of the application. Environment variable: |
string |
|
The maintainer of the package, as a name and an email address : Environment variable: |
string |
|
The section of the package. Environment variable: |
string |
|
Whether the package depends on the packages of the shared libraries that the application is linked with, found with Environment variable: |
boolean |
|
More packages that the package depends on : the libraries that the application loads at run time ( Environment variable: |
list of string |
|
The license of the application, as RPM names it : Environment variable: |
string |
|
The group of the package. Environment variable: |
string |
|
Whether the package requires the shared libraries that the application is linked with, found by Environment variable: |
boolean |
|
More capabilities that the package requires. Environment variable: |
list of string |
|
The runtime of the AppImage, for a build without access to GitHub or with a runtime of a known version : a Environment variable: |
string |
|
The update information of the AppImage, which the AppImage updaters (AppImageUpdate, AppImageLauncher) read to download a new version : Environment variable: |
string |
|
The runtime of the application. The default one has GTK 3, which SWT needs. Environment variable: |
string |
|
The version of the runtime and of its SDK : a branch of the runtime on Flathub, such as Environment variable: |
string |
|
The SDK of the runtime, of the same version : Environment variable: |
string |
|
The branch of the application. Environment variable: |
string |
|
The permissions of the sandbox, as the options of Environment variable: |
list of string |
|
The base snap. Environment variable: |
string |
|
The confinement of the snap : Environment variable: |
string |
|
The grade of the snap : Environment variable: |
string |
|
The extensions of the application of the snap, empty for none. The Environment variable: |
list of string |
|
The interfaces that the application plugs. Environment variable: |
list of string |
|
The packages of the Ubuntu archive to add to the snap. Environment variable: |
list of string |
|
More arguments of Environment variable: |
list of string |
|
The JDK whose Environment variable: |
string |
|
The modules of the Java runtime of the application ( Environment variable: |
list of string |
|
The options of Environment variable: |
list of string |
|
A Java runtime to use rather than one built with Environment variable: |
string |
|
The options of the JVM of the application, separated by commas : Environment variable: |
list of string |