Launchers are responsible for starting your application. There are two types of launchers:
install4j can generate native launchers that start your application. For example, on Windows, an
.exefile will be created that among other things takes care of finding a suitable JRE, displaying appropriate error messages if required and then starts your application. Using launchers generated by install4j has numerous advantages as compared to using home-grown batch files and shell scripts.
Each launcher definition is compiled separately for each defined media file. This means that for the majority of all cases, a single launcher definition will be sufficient to start your application. If, for example, your distribution contains two GUI applications and a command line application, you have to define 3 launchers, regardless of how many media files you define.
When your application is started with a launcher generated by install4j, you can query the system property
install4j.appDirto get the installation directory and and
install4j.exeDirto get the directory where the launcher resides. Use calls like
to access these values.
External launchersIf you already have an external launcher for your application, you can let install4j use that launcher instead of generating one. Because external launchers are most likely platform-dependent, you will have to add external launchers for each platform that is targeted by your media files. Make sure to exclude the irrelevant launchers in your media file definitions in this case.
If the launcher is a binary file rather than a shell script, make sure to set its Unix mode in the distribution tree to a value that makes it executable for the owner, such as 755 or 700. This also affects the generated .desktop file whose
Execattribute will start with a shell executable unless the launcher file is executable itself.
Types of generated launchers
Executables created by install4j can be either GUI applications, console applications or service applications.
There is no terminal window associated with a GUI application. If stdout and stderr are not redirected
on the "Executable info->Redirection" step of the launcher wizard, both streams are inaccessible for the user.
This corresponds to the behavior of
On Windows, if you launch the executable from a console window, a GUI application can neither write to or
read from that console window. Sometimes it might be useful to use the console, for example for seeing debug
output or for simulating a console mode with the same executable. In that case you can select the
Allow -console parameter check box. If the user supplies the
parameter when starting the launcher from a console window, the launcher will try to acquire the console
and redirect stdout and stderr to it. If you redirect stderr and stdout in the
"Executable->Redirection" step, that output will not be written to the console.
A console application has an associated terminal window. If a console application is opened from the
Windows explorer, a new terminal window is opened. If stdout and stderr are not redirected on the
"Executable info->Redirection" step of the launcher wizard, both streams are printed on the terminal window.
This corresponds to the behavior of
Finally, a service runs independently of logged-on users and can be run even if no user is logged on at all. A service cannot rely on the presence of a console, nor can it open windows. On Microsoft Windows, a service executable will be compiled by install4, on macOS a launch daemon will be created and on Unix-like platforms a start/stop script will be generated.
When a service is started, the
main method of the configured main class will be called.
To handle the shutdown of your service, you can use the
Runtime.addShutdownHook() method to
register a thread that will be executed before the JVM is terminated.
For information on how services are installed or uninstalled, see the help topic on services.
The most important configuration of a launcher is done on the "Java invocation" step of the launcher wizard and revolves around replicating the arguments you would pass to the Java launcher in a batch file:
You can provide a fixed list of VM parameters to your launcher and also add version-specific VM parameters. Fixed VM parameters can contain compiler, launcher and installer variables.
Compiler variables are replaced at build time, launcher variables are replaced by the launcher so that the VM sees the replaced value from the very beginning, and installer variables are replaced in the main method. This means that using installer variables is not suitable for setting certain kinds of VM parameters like
-Xmx, but can be useful for replacing system properties that are only used by your code or by libraries.
See the separate help topic on VM parameters for more information on the various ways to set VM parameters for launchers.
Module or class path
On the "Java invocation" step of the launcher wizard you can configure both the module path and the class path. These settings correspond to the
-cpparameters of the standard Java launcher. The module path is only applicable for Java 9 and higher. Like for the standard Java launcher, you can add directories, single archives or directories with archives. In addition, you can add archives from environment variables and from compiler variables.
The compiler variable entry is useful if the set of JAR files that should be added to the module path or class path is calculated in your build system and these JAR files are not staged to a fixed set of directories that you could reference in install4j. In that case, the the command line compiler as well as the plugins for Gradle, Maven and Ant can set a compiler variable externally where the single JAR files are separated by a configurable separator.
Main classFor Java 9 and higher, you can choose a main class from either the module or the class path. If you choose the module path option, the syntax for the main class is
<module name>/<class name>and corresponds to the
--moduleparameter of the standard Java launcher. The chooser dialog shows all the available main classes and inserts the correct value automatically.
ArgumentsLike VM parameters, the list of fixed arguments supports compiler, launcher and installer variables. Arguments on the command line are appended to the fixed list of arguments.
Cross-platform launcher features
Generated launchers optionally support a single instance mode on all supported platforms. You can use the launcher APIto register a startup handler that receives the command line parameters if the launcher is started more than once. In this way, you can handle file associations with a single application instance. GUI launchers on macOS are always in single instance mode because that is a fundamental property of application bundles.
Icons for launchers can be generated from a set of PNG files. On Windows, an
.ico file and
on macOS an
.icon file is compiled, on Linux the generated
.desktop file references
the PNG images. You can also provide pre-built ICO and ICNS files.
A splash screen image can be configured on the "Splash screen" step of the launcher wizard. The
-splash command line parameter does not work for the generated executables, because it is part
of the standard Java launchers and not of the Java runtime itself. An exception is the argument
which is emulated by install4j Windows launchers to disable the splash screen from the command. The splash screen
supports additional high DPI images with a
@2x suffix in the file name.
In addition to the standard splash screen image, install4j allows you to position two lines of text on top of the splash screen image, a version line and a status line. The status line can be updated from your launcher with the launcher API.
If your code loads native libraries via
System.load(...) or if a native library loads
dependent libraries, the native library path has to be modified to include the directories where these native libraries
are located. In batch or shell scripts you would do this in a platform-specific way, modifying
DYLD_LIBRARY_PATH on macOS,
LD_LIBRARY_PATH on Linux and a variety
of other variable names on different Unix variants.
In install4j, you can use the "Java invocation->Native libraries" step of the launcher wizard to specify such
directories, and the launcher will take care that the appropriate environment variable is modified. These
directories end up in the
java.library.path system property in your launcher.
If you need different directories for different media files, use a compiler variable for the directory name
and override it for each media file.
JRE search sequence
By default, launchers use the bundled JRE. In case you do not bundle a JRE, the JRE search sequence determines how install4j searches for a JRE on the target system. New configurations get a pre-defined default search sequence.
Apart from searching the Windows registry, well-known standard installation locations and paths in environment variables, you can also configure a relative directory in your distribution tree. This is useful if you distribute your own JRE for a launcher that is not provided through a JRE bundle managed by install4j.
install4j has a special mechanism which allows you to bundle JREs with your media files. If you choose a particular JRE for bundling in one of the media file wizards, this JRE will always be used first and you do not need to adjust the search sequence yourself.
If you do not bundle a JRE and a launcher has special Java version requirements that differ from those of the other launchers, you can override them on the "Java invocation->Override Java version" step of the launcher wizard.
If you have problems with JRE detection at runtime, see the help topic on error handling for a description on how to get diagnostic information.
A version info resource will enable the Windows operating system to determine meta information about your executable. This information is displayed in various locations. For example, when opening the property dialog for the executable in the Windows explorer, a "Version" tab will be present in the property dialog if you have chosen to generate the version info resource.
The version info resource consists of several pieces of information. If you check
Generate version info resource on the "Executable->Windows version info" step of the
launcher wizard, there are several fields whose values must be entered.
The "original file name", the "company name", the "product name" and the "product version" fields in the
version info resource are filled in automatically by install4j and cannot be
On the "Executable->Windows manifest options" step you can adjust the contents of the executable manifest, a static resource in the executable that controls some Windows features.
With an execution level other than "As invoker", you can ask Windows to show a UAC prompt and run the launcher with elevated privileges.
The DPI awareness controls whether Windows will scale up pixels in a GUI if high DPI is used. By default, DPI awareness is enabled if the minimum Java version of your project is at least Java 9.
On Windows, executables can be 64-bit or 32-bit. A 64-bit executable can only run with a 64-bit JVM and a 32-bit executable can only run with a 32-bit JVM. By default, 64-bit executables are generated, but you can switch to 32-bit executables in the "Installer options" step of the Windows media wizard.
By default, the generated application bundle for a GUI application uses the "Executable name" property from the "Executable info" step of the launcher wizard. If you choose compact names as appropriate for Windows and Unix, you may not be happy with the appearance in the Finder on macOS.
On the "Executable info->macOS options" step, you can specify a localizable application bundle name.
If you specify an i18n variable as the application bundle name, such as
install4j will name the application bundle directory with the resolved value for the
principal language of your project.
In addition, it will take the values for all additional configured languages and set up the appropriate
localization in the application bundle.
On macOS, file associations and URL handlers are not registered with calls to an API that is provided by the
operating system, but by adding special entries to the
Info.plist file of the application bundle.
This is why macOS single bundle archives can handle "Create a file association" and "Register a URL handler"
actions at compile-time. By default, associations for all such actions that are contained in the installer
configuration on the "Installer->Screens & Actions" step are added to the
Optionally, you can choose that only selected actions should be included.
Many advanced modifications of the behavior of an application bundle can be done by adding entries to the
Info.plist file. On the macOS Options step you can specify a fragment that is added to the default
Info.plist file. For services, this fragment is written to the launcher plist file.
Modifying launcher shell scripts and secondary start files
Launchers on Unix as well as command line and service launchers on macOS are shell scripts that invoke
the standard Java launcher. To include your own modifications, you can specify a fragment that is
inserted just before the
On Linux, two conditions require the generation of additional start files for a launcher and in both cases you can add additional content to them:
The integration of a GUI launcher into a desktop environment requires the generation of a
.desktopfile. You may want to add additional content to that file to customize the interaction with the desktop environment.
In the case of a service launcher, a
.servicefile is generated if systemd is detected. To configure advanced aspects of systemd execution you can add additional content to that file.
In the Installer->Screens & Actions step, you can add a "Background update downloader" installer application that runs in the background and automatically downloads an updater installer. Such a background update downloader will not execute the downloaded update installer because that would disrupt the work of the user. Instead, it executes a "Schedule update installation" action to register the downloaded updated installer for later execution.
For GUI launchers, you can select the
Execute downloaded updater installers at startup check box
in the "Executable info->Auto update integration" step of the launcher wizard. When this GUI launcher is
started and a downloaded update installer has been scheduled for installation, the update installer will be executed.
By default, the execution mode of the update installer is set to "Unattended mode with progress dialog"
with a configurable message.
For more on auto-update functionality, see the corresponding help topic.