When invoking exe4j from the start menu, the desktop icon or by executing bin\exe4j.exe in the exe4j installation directory, the exe4j wizard is started. It guides you step by step through completing the required information for building the executable. You can click on step names in the wizard index to navigate quickly to a selected step.

By default, the wizard starts with an empty configuration, if you would like to load a config file at startup, you can pass the path of the desired config file on the command line.

To try out exe4j, the demo directory in the exe4j installation directory contains three sample applications:

• a GUI application in the gui directory
• a command line application in the cli directory
• a service application in the service directory

Project types

An exe4j project can be compiled in one of two modes:

• Regular mode

  In the regular mode, exe4j is a pure launcher and relies on all JAR files and resources to be present in the distribution. In other words, the exe4j executable is an addition to your distribution, and not a replacement for it.

  On the "Application info" step, you enter the distribution source directory . The distribution source directory is the topmost directory under which all other directories of your application reside. When you select directories and files in the wizard through a file chooser, the paths will be converted to paths relative to the distribution source directory. One of those relative directories is the executable directory in the "Application info" step is the directory below the distribution source directory where the executable is to be placed.

• JAR in EXE mode

  In "JAR in EXE" mode, exe4j includes the JAR files specified in the class path configuration of the "Java invocation" step into the executable. In this way, you can distribute your application as a single executable - provided it does not need additional support files and directories. In this mode, you can only select "archive" and "environment variable" in the classpath entry dialog. The JAR files are extracted to a temporary directory at runtime and deleted after use.

Executable types

Executables created by exe4j can be one of the following three types:

• GUI application

  There is no terminal window associated with a GUI application. If stdout and stderr are not redirected, both streams are inaccessible for the user. This corresponds to the behavior of javaw.exe.

  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 "Executable info->Redirection" step, that output will not be written to the console.

• 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, both streams are printed on the terminal window. This corresponds to the behavior of java.exe.

• Service

  A Windows service runs independently of logged-in users and can be run even if no user is logged on. The main method will be called when the service is started.

  To handle the shutdown of the 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 on service start options.

Executable options

In the "Executable info->32 bit or 64-bit" step of the wizard, you can configure whether your executable should be a 32-bit executable or a 64-bit executable.

Note that it is not possible to create launchers that work with both 64-bit and 32-bit JREs. Because the launcher starts the JVM with the JNI interface by loading the JVM DLL, the architecture has to be the same. If you target both 32-bit and 64-bit JREs, you have to generate different executables for them.

In other sub-steps of the "Executable info" step, you can optionally configure redirection of stdout and stderr, a version info resource for the executable and options for the executable manifest. On the "Executable info->Manifest options", a non-standard execution level can be configures as well as the DPI awareness of your process which is important for High-DPI screens.

If your application can deal with different DPI settings, you can tell exe4j to add the manifest entry to the executable that enables DPI-awareness. If that entry is not added, the GUI will be scaled up automatically and may look blurry.

VM parameters

In the "Java invocation" step of the wizard, you enter the information required to start your application, including a list of VM parameters. There are several runtime-variables you can use to specify runtime directories in the VM parameters:

• %EXE4J_EXEDIR%

  This is the directory where the executable is located.

• %EXE4J_JVM_HOME%

  This is the directory of the JRE that your executable is running with.

• %EXE4J_TEMPDIR%

  For the "JAR in EXE" mode, this variable will contain the location of the temporary directory for the JAR files. In "regular mode" this variable is not used.

exe4j can add specific VM parameters depending on the Java version. To set this up, click on the Configure version specific VM parameters button. In the dialog, add rows for each range of Java versions that should receive specific VM parameters. If the Java version of the JVM that is used at runtime matches a configured version expression, the associated VM parameters will be appended to the common VM parameters. The search is stopped at the first matching entry. The syntax for the Java version expressions is explained by the help icon on the table header.

In addition to these VM parameters, a parameter file in the same directory as the executable is read and its contents are added to the existing VM parameters. The name of this parameter file is the same as the exe file with the extension *.vmoptions. For example, if your exe file is named hello.exe, the name of the VM parameter file is hello.vmoptions. In this file, each line is interpreted as a single VM parameter. For example, the contents of the VM parameter file could be:

-Xmx128m
-Xms32m

It is possible to include other .vmoptions files from a .vmoptions file with the syntax

-include-options [path to other .vmoptions file]

You can use multiple includes in a single file, recursive includes are also supported. You can also add this option to the fixed VM parameters. In that way, you can prevent having to use the .vmoptions file right next to the executable.

This allows you to to centralize the user-editable VM options for multiple launchers and to have .vmoptions files in a location that can be edited by the user if the installation directory is not writable. You can use environment variables to find a suitable directory, for example

-include-options ${APPDATA}\My Application\my.vmoptions

-include-options ${USERPROFILE}\.myapp\my.vmoptions

In addition to the VM parameters you can also modify the classpath in the .vmoptions files with the following options:

• -classpath [classpath]

  Replace the classpath of the generated launcher.

• -classpath/a [classpath]

  Append to the classpath of the generated launcher.

• -classpath/p [classpath]

  Prepend to the classpath of the generated launcher.

You can use environment variables in the VM parameters with the following syntax: ${VARIABLE_NAME} where you replace VARIABLE_NAME with the desired environment variable.

Java invocation

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 --module-path and the -cp parameters 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.

For 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 --module parameter of the standard Java launcher. The chooser dialog shows all the available main classes and inserts the correct value automatically.

Like VM parameters, the list of fixed arguments supports launcher variables. Arguments on the command line are appended to the fixed list of arguments.

The launcher needs a runtime JAR file which is automatically added to the executable and extracted to a temporary directory at runtime. If you use the regular mode and not the "JAR in EXE" mode, you can prevent the extraction of files at runtime by deselecting the "Bundle runtime" option. In that case, you have to distribute the runtime file exe4jlib.jar and add it to the classpath or module path.

JRE selection

In the "JRE" step of the wizard, you enter the version requirements for the JRE or JDK that your application will be started with on the target system.

The minimum Java version must be specified, but the maximum Java version can be left empty, so that any JRE or JDK with a higher version than the minimum version is acceptable.

In the "JRE->Search sequence" step, you can configure the way the exe4j executable looks for an appropriate JRE or JDK to start your Java application.

The following types of search sequence entries are available:

• Search registry

  Search the Windows registry for installed JREs and JDKs by Oracle.

• Directory

  Look in the specified directory. This is especially useful if you distribute your own JRE along with your application. In that case, be sure to supply a relative path. Note that for path selections through the file chooser (... button), exe4j will try to convert the path to be relative to the distribution source directory.

• Environment variable

  Look for a JRE of JDK in a location that is defined by an environment variable like JAVA_HOME or MYAPP_JAVA_HOME.

To distribute your own JRE, put the JRE in your distribution and define a  directory search sequence entry with the appropriate relative path (for example jre) as the first item.

It is possible to generate a log file that contains information about the JRE search sequence and any potential problems. To switch on logging, start the executable with the /create-i4j-log argument. The launcher will notify the user where the log is created and will offer to open an explorer window with the log file selected. After the message box, the launcher will continue to start up. If it is not possible to pass arguments, define the environment variableEXE4J_LOG=yes and look for the newest text file whose name starts withi4j_nlog_ in the Windows %TEMP% directory.

If the entire search sequence fails, exe4j will try the location defined by the environment variable EXE4J_JAVA_HOME. If that fails too, an error message will be displayed asking the user to define this variable. To supply a custom variable, define an appropriate environment variable search sequence entry and customize the corresponding error message in the "Messages" step of the wizard.

Splash screen

Splash screens for executables generated by exe4j cannot be configured with the -splash VM parameter, but must be configured on the "Splash screen" step.

In addition, you can overlay lines of text for status and version information on the splash screen, by configuring them on the "Splash screen->Text lines" step. The Status line and Version line sections allow you to position the text lines on the splash screen and configure their font. The status line is dynamically updatable with exe4j's launcher API. If you include the variable %VERSION% in the version line text, it will be replaced with the product version defined in the "Executable info->Version info" step of the wizard. With the -r flag, you can override this setting for the command line compiler.

Messages

In the "Messages" step of the wizard you can configure all messages that may be displayed by the generated executable. Default message sets for the exe4j executable are available in several languages. You can double-click on any message to edit it. If a message is modified from its default, a customization indicator and a Reset button is displayed in the table row.