Launcher Wizard: Configure Executable

  In this step of the launcher wizard, you enter the properties of the executable that is to be generated.
  The following properties of the executable can be edited in the Executable section of this step:
  • Executable type
    Executables created by install4j can be either GUI applications, console applications or service applications
    • GUI application
      There is no terminal window associated with a GUI application. If stdout and stderr are not redirected (see the redirection advanced step), 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 this 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 window and redirect stdout and stderr to it. If you redirect stderr and stdout in the redirection settings, that output will not be written to the console.

      If your GUI application uses SWT or QT Jambi instead of Swing, please select the uses SWT or QT check box below this radio button. This is mainly important for correct behavior on macOS where the application must be started differently in this case.

    • Console application
      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 (see the redirection advanced step), both streams are printed on the terminal window. This corresponds to the behavior of java(.exe).
    • Service application
      A service runs independently of logged-on users and can be run even if no user is logged on. 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 startup item will be created and on Unix-like platforms a start/stop script will be generated.

      When you develop a service please note the following requirement: The main method will be called when the service is started.

      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, please see the help on help topic on services.

  • Executable name
    Enter the desired name of the executable without any trailing .exe or .sh.
  • File set
    Choose the file set to which the launcher should be added. File sets are defined in the distribution tree. If you do not use different file sets, "Default file set" will be the only option which is activated by default.
  • Directory
    Enter the directory in the distribution tree where the executable should be generated. If you leave this field empty, the executable will be generated in the installation root directory. You can select a directory from the distribution tree by clicking the ... chooser button.
  • Allow only a single running instance of the application
    If you select this check box, the generated executable can only be started once. Subsequent user invocations will bring the application to the front. In the StartupNotification class of the install4j launcher client API you can register a startup handler to receive the command line parameters. In this way, you can handle file associations with a single application instance. This feature is only available on Microsoft Windows, on macOS, single bundle media files always behave this way.
  • Fail if an exception in the main thread is thrown
    Executables created by install4j can monitor whether the main method throws an exception and show an error dialog in that case. This provides a generic startup error notification facility for the developer that handles a range of errors that would otherwise not be notified correctly. For example, if an uncaught exception is thrown during application startup, a GUI application might simply hang, leaving the user in the dark about the reasons for the malfunction. With the error message provided by the install4j executable, reasons for startup errors are found much more easily.
  • Working directory
    For some applications (especially GUI applications) you might want to change the working directory to a specific directory relative to the executable, for example to read config files that are in a fixed location. To do so, please select the Change working directory to check box and enter a directory relative to the executable in the adjacent text field. To change the current directory to the same directory where the executable is located, please enter a single dot.