Generated Launchers

Launchers are responsible for starting your application. There are two types of launchers:

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 javaw(.exe).

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 -console 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 java(.exe).

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.

Java invocation

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:

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 -J-splash:none 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 PATH on Windows, 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.

Windows-specific features

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 configured.

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.

macOS-specific features

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 ${i18n:myLauncherName}, 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 Info.plist file. 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 java invocation.

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:

Auto-update integration

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.