Configuration Reference

Whether the native executable is DPI aware, as a JVM started by the java launcher is.

When enabled, the sun.java2d.dpiaware system property defaults to true in the native executable (a -Dsun.java2d.dpiaware=false command line option still overrides it), and the application manifest (see quarkus.desktop.awt.windows.manifest) declares per monitor DPI awareness. Windows then lets the application scale itself to the display scale factor (crisp text and images). When disabled, Windows stretches the windows of the application as bitmaps (blurry) on displays with a scale factor above 100 %.

Environment variable: QUARKUS_DESKTOP_AWT_WINDOWS_DPI_AWARE

Whether to embed an application manifest in the native executable, as the java launcher has one.

The manifest selects the version 6 of the Windows common controls (the visual styles of the native AWT components and dialogs; without it they look like Windows 2000 controls), declares the DPI awareness of the application (see quarkus.desktop.awt.windows.dpi-aware) and the supported Windows versions. It is embedded by the linker, through -H:NativeLinkerOption options that the extension adds to the native build.

Environment variable: QUARKUS_DESKTOP_AWT_WINDOWS_MANIFEST

The Windows subsystem of the native executable.

console, the default, is the subsystem of the java launcher : started from Explorer, the application gets a console window, which shows its log. windows is the subsystem of the javaw launcher : no console window (the standard output and error streams of the application are lost unless they are redirected, so configure a log file).

Environment variable: QUARKUS_DESKTOP_AWT_WINDOWS_SUBSYSTEM

Whether to copy the Microsoft Visual C++ runtime libraries (msvcp140.dll, vcruntime140.dll and vcruntime140_1.dll) of the GraalVM used for the native build next to the native executable, when the native executable uses the AWT libraries.

The JDK AWT library awt.dll needs msvcp140.dll, which a Windows installation does not always have (it comes with the Visual C++ Redistributable). With a local copy, the native executable and its libraries can be distributed as they are, as the JDK does.

Environment variable: QUARKUS_DESKTOP_AWT_WINDOWS_COPY_VC_RUNTIME

Whether the native executable supports the Java Access Bridge, which screen readers such as JAWS or NVDA use to access the user interface of Java applications.

Users enable the Java Access Bridge with jabswitch -enable (or in the Windows accessibility settings), which configures the assistive_technologies of every Java application in %USERPROFILE%\.accessibility.properties. When enabled, the Java Access Bridge is included in the native executable, as it is in the JDK (javaaccessbridge.dll and jawt.dll are copied next to the native executable), and it is loaded when the user enabled it. When disabled, the javax.accessibility.assistive_technologies system property defaults to an empty value in the native executable, so that the native executable ignores the user setting, instead of failing to start with a java.awt.AWTError: Could not load or activate service provider.

Environment variable: QUARKUS_DESKTOP_AWT_WINDOWS_ACCESS_BRIDGE

The logical font configuration (the physical fonts behind the Dialog, SansSerif, Serif, Monospaced and DialogInput logical fonts, used by AWT components and by default in Swing).

jdk, the default, is the font configuration of the JDK used for the native build (its lib/fontconfig.properties.src file, embedded in the native executable and extracted to the temporary directory at startup) : the logical fonts display the same scripts as in JVM mode (Arabic, Hebrew, Chinese, Japanese, Korean, Thai, Indic scripts…​), and all the charsets of the JDK are included in the native executable, since the font configuration uses many of them. minimal is the minimal font configuration of the Quarkus AWT extension (Latin scripts only) : a slightly smaller native executable, with the standard charsets only (fonts whose names or character maps use a legacy encoding such as Shift_JIS or GBK, and RTF text in other charsets, are then not read as in JVM mode). On Linux and macOS, all the charsets are always included.

Environment variable: QUARKUS_DESKTOP_AWT_WINDOWS_FONT_CONFIGURATION

Whether the JDK AWT classes support the JavaBeans API in native executables : their public constructors, methods and fields are registered for reflection, so that the Introspector finds their bean properties and event sets, and that XMLEncoder, XMLDecoder, Statement, Expression, EventHandler and Beans.instantiate work with them, as in JVM mode.

The classes are the AWT components and menu components, the layouts (GridBagConstraints included), the values of their properties (Color, Font, Insets, Point, Rectangle, Cursor, MenuShortcut…​), the AWT events, listeners and adapters. For instance Introspector.getBeanInfo(Button.class) finds the label property, XMLEncoder writes a Panel with its layout and components, and EventHandler.create(ActionListener.class, target, "text", "source.label") reads the label of the source of an ActionEvent.

It makes a native executable about 0.3 MB larger. When disabled, the Introspector finds no bean property of these classes (other than those that the extensions register for their own needs) and XMLEncoder cannot write them. The same property of the Desktop Swing extension, quarkus.desktop.swing.java-beans.jdk-classes (disabled by default), registers the Swing classes, and the AWT classes that they extend whatever the value of this property.

Environment variable: QUARKUS_DESKTOP_AWT_JAVA_BEANS_JDK_CLASSES

Whether the native build registers what the JDK desktop code looks up and may not find, for native executables built with --exact-reachability-metadata (GraalVM : a lookup that is not registered then fails with a missing registration error instead of answering "not found", even when "not found" is the expected answer).

The registered lookups are those of the JDK expected to fail (the BeanInfo, Customizer, PersistenceDelegate and Editor classes that the JavaBeans API probes for the JDK classes that the extensions register for it, the region names that Nimbus probes, the .properties files next to the resource bundles of the JDK, the META-INF/services files of the desktop services, the processInputMethodEvent methods that the text components of the JDK do not declare…​), the types whose members the JavaBeans API queries, and the var handles of the native memory accesses of Java2D and fonts. They make a native executable about 0.3 MB larger, and are useless without exact reachability metadata. The methods that AWT and Swing look up in the classes of the application and of its libraries (coalesceEvents in the components…​) are registered for every native executable, declared or not.

By default, they are registered when quarkus.native.additional-build-args or quarkus.native.additional-build-args-append contains --exact-reachability-metadata (or -H:ThrowMissingRegistrationErrors). Set this property when the option is given another way.

Environment variable: QUARKUS_DESKTOP_AWT_EXACT_REACHABILITY_METADATA

Whether the first thread of the process runs the Cocoa event loop, as with the java launcher, the Quarkus application running on a new thread named main.

AppKit, which AWT, Swing and JavaFX use on macOS, only runs on the first thread of the process : without this, the first window of an AWT or Swing application never shows. Disable it only with the Quarkus FX launcher, which then runs JavaFX on the first thread itself (AWT then runs embedded in JavaFX), or with a GraalVM version that keeps the first thread in the Cocoa event loop itself. It is ignored when the application has an SWT user interface (Desktop SWT extension), whose event loop runs on the first thread.

Environment variable: QUARKUS_DESKTOP_AWT_MACOS_PARK_MAIN_THREAD

The stack size of the thread that runs the Quarkus application (the first thread of a macOS process has 8 MiB, the other threads 512 KiB by default).

Environment variable: QUARKUS_DESKTOP_AWT_MACOS_MAIN_THREAD_STACK_SIZE

How long System.exit may take once the application has stopped before the process is halted, 0 to wait for ever. A safety net against an exit that never completes while AppKit runs on the first thread.

Environment variable: QUARKUS_DESKTOP_AWT_MACOS_EXIT_HALT_TIMEOUT

The name of the application in the menu bar and the Dock : the default value of the apple.awt.application.name system property in the native executable (the java launcher sets it to the simple name of the main class). The Quarkus application name (quarkus.application.name) by default.

Environment variable: QUARKUS_DESKTOP_AWT_MACOS_APPLICATION_NAME

Whether to embed an information property list (Info.plist) in the native executable, as the java launcher has one : bundle identifier, name and versions of the application, high resolution capability, and the description of the microphone use (Java Sound capture) that macOS shows when it asks the user for the permission.

Environment variable: QUARKUS_DESKTOP_AWT_MACOS_INFO_PLIST

Whether the native executable declares the minimum macOS version and the SDK version of the java launcher of the JDK that builds it (its LC_BUILD_VERSION load command), as a JVM application does.

macOS does not start an executable on a version older than its minimum version, and AppKit chooses the look of the windows (the height of the title bars for instance) and its compatibility behaviors from its SDK version. When disabled, the linker writes the version of the SDK of the Xcode tools as both : the executable then only starts on that macOS version and later, and gets the look of that version.

Environment variable: QUARKUS_DESKTOP_AWT_MACOS_JDK_BUILD_VERSION

Whether the event is fired. By default it is, except in tests (@QuarkusTest, where it would open the windows of the application) : set %test.quarkus.desktop.awt.startup-event.enabled=true for user interface tests. In tests, quarkus.arc.test.disable-application-lifecycle-observers=true disables it too.

Environment variable: QUARKUS_DESKTOP_AWT_STARTUP_EVENT_ENABLED

When the event is fired : auto during the startup of the application (queued on the event dispatch thread after the StartupEvent observers : its observers may run while a @QuarkusMain runs), manual when the application calls DesktopLifecycle.start() (from its @QuarkusMain once its work before the user interface is done, or from a StartupEvent observer).

Environment variable: QUARKUS_DESKTOP_AWT_STARTUP_EVENT_MODE

Whether the application stops (Quarkus.asyncExit()) when its last visible window is closed or hidden, once a first window opened. Only for an application observing DesktopStartupEvent, never in tests, nor with Quarkus FX. Disable it for an application that stays alive without windows (a tray icon, the macOS convention), or that closes a window before showing the next one (a splash screen closed before the main window shows).

Environment variable: QUARKUS_DESKTOP_AWT_EXIT_ON_LAST_WINDOW_CLOSED

The look and feels of the JDK included in native executables : all, or a list of metal, nimbus, synth, motif, windows (with Windows Classic), gtk and multi (the multiplexing look and feel of the auxiliary look and feels).

By default, native executables include all the look and feels of the JDK for their platform. They make the native executable larger (about 10 MB for all of them : Nimbus and the multiplexing look and feel about 3 MB each), so an application can list only those it uses. Metal, the default look and feel, is always included (and Aqua on macOS, which draws the AWT components there); Nimbus and GTK include the Synth look and feel they extend, but not the loading of Synth XML files (synth). Setting a look and feel that is not included fails with a ClassNotFoundException.

This property has no effect in JVM mode.

Environment variable: QUARKUS_DESKTOP_SWING_INCLUDED_LOOK_AND_FEELS

Whether the JDK Swing classes support the JavaBeans API in native executables : their public constructors, methods and fields are registered for reflection, so that the Introspector finds their bean properties and event sets, and that XMLEncoder, XMLDecoder, Statement, Expression, EventHandler and Beans.instantiate work with them, as in JVM mode. The AWT classes that they extend are registered too (as with quarkus.desktop.awt.java-beans.jdk-classes=true), and the icons of the bean infos of the Swing components are included (BeanInfo.getIcon).

The classes are the public classes of javax.swing, javax.swing.border, javax.swing.event, javax.swing.table and javax.swing.tree (components, models, layouts, borders, actions, key strokes, icons, renderers and editors, events and listeners), the text components, documents and formatters of javax.swing.text, and the UI resources of javax.swing.plaf. For instance XMLEncoder writes a JPanel with its border, layout and components, a JTabbedPane, a JTree with its nodes, and XMLDecoder reads them.

It is disabled by default because it makes a native executable 3 to 4 MB larger (many public methods of the Swing classes are not used otherwise). When disabled, the Introspector finds no bean property of these classes (other than the properties usually transferred with new TransferHandler("text"), which are always registered) and XMLEncoder cannot write them.

Environment variable: QUARKUS_DESKTOP_SWING_JAVA_BEANS_JDK_CLASSES

The look and feel set when the application starts, before it runs (on the event dispatch thread, in JVM mode and in native executables).

system (the look and feel of the platform : Windows on Windows, Aqua on macOS, GTK on a GNOME desktop, Metal otherwise), cross-platform (Metal), metal, nimbus, motif, windows, windows-classic, gtk, or the class name of a look and feel (an application look and feel, or a library one such as FlatLaf). When not set, Swing uses its default look and feel (Aqua on macOS, Metal elsewhere, unless the swing.defaultlaf system property sets another one), and the application can set the look and feel itself with UIManager.setLookAndFeel.

A look and feel that this platform does not support (for instance windows on Linux) or that cannot be created is reported as a warning, and the default look and feel is kept. The look and feel classes of the JDK are included in native executables as quarkus.desktop.swing.included-look-and-feels configures them (all of them by default ; the build warns when this property names one that is not included) ; an application look and feel class is registered for reflection when it is in the Jandex index of the application, or when this property names it at build time.

Environment variable: QUARKUS_DESKTOP_SWING_LOOK_AND_FEEL

Where the native executable finds the native libraries of SWT (swt-win32-<version>.dll, libswt-gtk-<version>.so, libswt-cocoa-<version>.jnilib…​).

embedded : the libraries are resources of the native executable, a single file. SWT extracts them on the first run, as it does in JVM mode, into ~/.swt/lib/<os>/<arch> (or into swt.library.path when this system property is set). next-to-executable : the libraries are copied next to the native executable when it is built, and the executable loads them from its directory : nothing is written to the home directory, and the libraries can be signed with the executable (a macOS application bundle). They are then distributed with the executable.

Environment variable: QUARKUS_DESKTOP_SWT_NATIVE_LIBRARIES

The subsystem of the native executable : console (the default of native executables), or windows for a user interface application without a console window, as with javaw. A windows executable has no standard output and error streams when it is not started from a console : log to a file (quarkus.log.file.enabled).

Environment variable: QUARKUS_DESKTOP_SWT_WINDOWS_SUBSYSTEM

Whether the native executable declares the minimum macOS version and the SDK version of the java launcher of the JDK that builds it (its LC_BUILD_VERSION load command), as a JVM application does.

macOS does not start an executable on a version older than its minimum version, and AppKit chooses the look of the windows and controls (the height of the title bars, the size of the controls, the background color of the widgets for instance) from its SDK version : the executable starts on the macOS versions that the JDK supports, and looks as in JVM mode. When disabled, the linker writes the version of the SDK of the Xcode tools as both : the executable then only starts on that macOS version and later, and gets the look of that version. With the Desktop AWT extension, quarkus.desktop.awt.macos.jdk-build-version applies instead : that extension writes the versions.

Environment variable: QUARKUS_DESKTOP_SWT_MACOS_JDK_BUILD_VERSION

Whether the user interface runs. By default it does, except in tests (@QuarkusTest and @QuarkusMainTest, where it would open the shells of the application) : set %test.quarkus.desktop.swt.startup-event.enabled=true for user interface tests. A @QuarkusTest then runs it on a thread of the extension (except on macOS, where it needs the first thread of the process), a @QuarkusMainTest on the thread running the main, as in production. In tests, quarkus.arc.test.disable-application-lifecycle-observers=true disables it too. When it does not run, SwtLifecycle.run() returns at once (an application without @QuarkusMain then stops at once), and the tasks for the user interface thread are rejected.

Environment variable: QUARKUS_DESKTOP_SWT_STARTUP_EVENT_ENABLED

Whether the application stops (Quarkus.asyncExit()) when its last visible shell is closed or hidden, once a first shell opened. Never in tests. Disable it for an application that stays alive without shells (a tray icon, the macOS convention), or that closes a shell before opening the next one (a splash screen closed before the main shell opens).

Environment variable: QUARKUS_DESKTOP_SWT_EXIT_ON_LAST_SHELL_CLOSED

The name of the application, given to SWT (Display.setAppName) before the Display is created : the name of the application menu and of the Dock on macOS, the program name and the WM_CLASS of the windows on Linux (matched with the .desktop file of the application), the application identifier of the taskbar on Windows. Defaults to quarkus.application.name.

Environment variable: QUARKUS_DESKTOP_SWT_APPLICATION_NAME