+
Running launch4j
+
Configuration file
+
Importing 1.x configuration
+
Ant Task
+
Additional JVM options at runtime
+
Runtime options
+
Settings
+
+
Running launch4j
+Run
launch4j.exe or
launch4j script without command
+line arguments to enter the GUI mode.
+
+
launch4j.exe
+
+To wrap a jar in console mode use
launch4jc.exe and
+specify the configuration file.
+
+
launch4jc.exe config.xml
+
+On Linux use the
launch4j script.
+
+
launch4j ./demo/l4j/config.xml
+
+
Configuration file
+Launch4j requires an xml configuration file for each output executable.
+You can create and edit it conveniently using the graphic user
+interface or your favorite editor. Alternatively it's possible to pass
+all of the configuration parameters through the Ant task. All files
+may be absolute paths or relative to the configuration file path.
+
Launch4j 3.50 Configuration changes:
+
+ - Removed <bundledJreAsFallback>, path search is always first and registry search second
+ in order to improve compatibility with modern runtimes.
+ - Replaced <bundledJre64Bit> and <runtimeBits> with <requires64Bit>
+ which works during path and registry search.
+ - Replaced <jdkPreference> with <requiresJdk> which works during path and registry search.
+ - Replaced <bundledJreErr> with <jreNotFoundErr>.
+
- <minVersion> and <maxVersion> are now used during path and registry search, previously
+ they were only checked during registry search.
+
+
+
+<!--
+ Bold elements are required.
+ Underlined values are the default when the element is not specified.
+ %VAR% expands environment/special variables and registry keys.
+-->
+<launch4jConfig>
+ <headerType>gui|console|jniGui32|jniConsole32</headerType>
+ <outfile>file.exe</outfile>
+ <jar>file</jar>
+ <dontWrapJar>true|false</dontWrapJar>
+ <errTitle>application name</errTitle>
+ <downloadUrl>http://java.com/download</downloadUrl>
+ <supportUrl>url</supportUrl>
+ <cmdLine>text</cmdLine>
+ <chdir>path</chdir>
+ <priority>normal|idle|high</priority>
+ <stayAlive>true|false</stayAlive>
+ <restartOnCrash>true|false</restartOnCrash>
+ <icon>file</icon>
+ <obj>header object file</obj>
+ ...
+ <lib>w32api lib</lib>
+ ...
+ <var>var=text (%VAR%)</var>
+ ...
+ <classPath>
+ <mainClass>main class</mainClass>
+ <cp>classpath (%VAR%)</cp>
+ ...
+ </classPath>
+ <singleInstance>
+ <mutexName>text</mutexName>
+ <windowTitle>text</windowTitle>
+ </singleInstance>
+ <jre>
+ <path>JRE path (%VAR%)</path>
+ <requiresJdk>true|false</requiresJdk>
+ <requires64Bit>true|false</requires64Bit>
+ <minVersion>1.x.x[_xxx]|xxx[.xxx[.xxx]]</minVersion>
+ <maxVersion>1.x.x[_xxx]|xxx[.xxx[.xxx]]</maxVersion>
+ <!-- Heap sizes in MB and % of available memory. -->
+ <initialHeapSize>MB</initialHeapSize>
+ <initialHeapPercent>%</initialHeapPercent>
+ <maxHeapSize>MB</maxHeapSize>
+ <maxHeapPercent>%</maxHeapPercent>
+ <opt>text (%VAR%)</opt>
+ ...
+ </jre>
+ <splash>
+ <file>file</file>
+ <waitForWindow>true|false</waitForWindow>
+ <timeout>seconds [60]</timeout>
+ <timeoutErr>true|false</timeoutErr>
+ </splash>
+ <versionInfo>
+ <fileVersion>x.x.x.x</fileVersion>
+ <txtFileVersion>text</txtFileVersion>
+ <fileDescription>text</fileDescription>
+ <copyright>text</copyright>
+ <productVersion>x.x.x.x</productVersion>
+ <txtProductVersion>text</txtProductVersion>
+ <productName>text</productName>
+ <companyName>text</companyName>
+ <internalName>filename</internalName>
+ <originalFilename>filename.exe</originalFilename>
+ <trademarks>text</trademarks>
+ <language>
+ ALBANIAN|ARABIC|BAHASA|DUTCH_BELGIAN|FRENCH_BELGIAN|BULGARIAN|
+ FRENCH_CANADIAN|CASTILIAN_SPANISH|CATALAN|CROATO_SERBIAN_LATIN|
+ CZECH|DANISH|DUTCH|ENGLISH_UK|ENGLISH_US|FINNISH|FRENCH|GERMAN|
+ GREEK|HEBREW|HUNGARIAN|ICELANDIC|ITALIAN|JAPANESE|KOREAN|
+ NORWEGIAN_BOKMAL|NORWEGIAN_NYNORSK|POLISH|PORTUGUESE_BRAZIL|
+ PORTUGUESE_PORTUGAL|RHAETO_ROMANIC|ROMANIAN|RUSSIAN|
+ SERBO_CROATIAN_CYRILLIC|SIMPLIFIED_CHINESE|SLOVAK|SPANISH_MEXICO|
+ SWEDISH|FRENCH_SWISS|GERMAN_SWISS|ITALIAN_SWISS|THAI|
+ TRADITIONAL_CHINESE|TURKISH|URDU
+ </language>
+ </versionInfo>
+ <messages>
+ <startupErr>text</startupErr>
+ <jreNotFoundErr>text</jreNotFoundErr>
+ <jreVersionErr>text</jreVersionErr>
+ <launcherErr>text</launcherErr>
+ <!-- Used by console header only. -->
+ <instanceAlreadyExistsMsg>text</instanceAlreadyExistsMsg>
+ </messages>
+</launch4jConfig>
+
+
+
+ - <headerType>
+ -
+ Type of the header used to wrap the application.
+
+
+
+ | Header type |
+ Launcher |
+ Splash screen |
+ Wait for the application to close |
+
+
+
+
+ | gui |
+ javaw |
+ yes |
+ wrapper waits only if stayAlive is set to true,
+ otherwise it terminates immediately or after closing
+ the splash screen.
+ |
+
+
+ | console |
+ java |
+ no |
+ always waits and returns application's exit code. |
+
+
+ | jniGui32 (beta) |
+ launch4j |
+ yes |
+ always waits and returns application's exit code. |
+
+
+ | jniConsole32 (beta) |
+ launch4j |
+ no |
+ always waits and returns application's exit code. |
+
+
+
+
+ When JNI headers are used the JVM is created directly by the launch4j wrapper executable instead of running java/javaw launchers.
+ The process name will be the same as the wrapper. The JNI headers are in BETA and some features are not available which is signaled
+ during wrapper build based on the configuration.
+ For production use consider the classic gui/console headers.
+
+ Missing features:
+
+ - Only '.' is allowed in change directory (chdir).
+ - Command line arguments cannot be passed to the executable.
+ - Constant command line arguments (cmdLine).
+ - stayAlive should be ignored by JNI headers.
+ - Restart of appplication based on exit code (restartOnCrash).
+ - Process priority - only normal is supported (priority).
+ - Jar manifest is ignored, mainclass and classpath must be defined.
+ - 64-bit JRE are not supported.
+
+
+
+
+ - <outfile>
+ - Output executable file.
+
+
+ - <jar>
+ -
+ Optional, by default specifies the jar to wrap. To launch a jar without
+ wrapping it enter the runtime path of the jar relative to
+ the executable and set <dontWrapJar> to true.
+ For example, if the executable launcher and the application jar named
+ calc.exe and calc.jar are in the same directory
+ then you would use <jar>calc.jar</jar>
+ and <dontWrapJar>true</dontWrapJar>.
+
+
+
+ - <dontWrapJar>
+ -
+ Optional, defaults to false. Launch4j by default wraps jars in native
+ executables, you can prevent this by setting <dontWrapJar> to true.
+ The exe acts then as a launcher and starts the application specified in
+ <jar> or <classPath><mainClass>
+
+
+
+ - <errTitle>
+ -
+ Optional, sets the title of the error message box that's displayed if Java cannot
+ be found for instance. This usually should contain the name of your
+ application. The console header prefixes error messages with this
+ property (myapp: error...)
+
+
+
+ - <cmdLine>
+ - Optional, constant command line arguments.
+
+
+ - <chdir>
+ - Optional. Change current directory to an arbitrary path relative to the executable.
+ If you omit this property or leave it blank it will have no effect.
+ Setting it to . will change the current dir to the same directory
+ as the executable. .. will change it to the parent directory, and so on.
+
+ -
+
<chdir>.</chdir>
+
+ -
+
<chdir>../somedir</chdir>
+
+
+
+ - <stayAlive>
+ - Optional, defaults to false in GUI header, always true in console header.
+ When enabled the launcher waits for the Java application
+ to finish and returns it's exit code.
+
+
+
+ - <restartOnCrash>
+ - Optional, defaults to false.
+ When the application exits, any exit code other than 0 is considered a crash and the application will be started again.
+
+
+
+ - <icon>
+ - Application icon in ICO format. May contain multiple color depths/resolutions.
+
+
+ - <obj>
+ - Optional, custom headers only. Ordered list of header object files.
+
+
+ - <lib>
+ - Optional, custom headers only. Ordered list of libraries used by header.
+
+
+ - <singleInstance>
+ - Optional, allow to run only a single instance of the application.
+
+
+
+ - <mutexName>
+ - Unique mutex name that will identify the application.
+ - <windowTitle>
+ - Optional, recognized by GUI header only. Title or title part of a window
+ to bring up instead of running a new instance.
+
+
+
+
+ - <jre>
+ - Required element that groups JRE settings.
+
+
+
+ - <path>, <minVersion>, <maxVersion>
+ - The <path> property is used
+ to specify absolute or relative JRE paths, it
+ does not rely on the current directory or <chdir>.
+ Note that this path is not checked until the actual application execution.
+ Launch4j 3.50 <path> is now required and
+ always used for searching before the registry in order to ensure compatibility
+ with latest runtimes which by default do not add registry keys during installation.
+ Launch4j 3.50 <minVersion> and <maxVersion>
+ are now considered during path and registry search, previously the version was checked only
+ during registry search. The first runtime version matching the given range will be used.
+
+
+
+
+ - <path> alone
+ - Search for JREs using specified paths, if not found stop with error.
+ Default: <path>%JAVA_HOME%;%PATH%</path>
+ Bundled: <path>jre</path>
+ Advanced: <path>%HKEY_LOCAL_MACHINE\SOFTWARE\UnusualJavaVendor\JavaHome%;%JAVA_HOME%;%PATH%</path>
+
+ - <path> + <minVersion> [+ <maxVersion>]
+ - Use path search first, if Java cannot be located then perform a registry search.
+ If that fails display an error message and optionally open the Java download page.
+
+
+
+
+
+
+ - <minVersion>, <maxVersion> format - Java < 9
+ - The traditional version scheme supported by launch4j is 1.x.x[_xxx] and requires at least 3 parts, for example:
+
+1.6.0
+1.7.0_51
+1.8.0_121
+
+
+
+
+
+
+ - <minVersion>, <maxVersion> format - Java >= 9
+ - The new version format is xxx[.xxx[.xxx]] where only 1 part is required and the update version after the underscore is not allowed.
+
+1.6
+9
+10.0.1
+
+
+
+
+
+
+ - <requiresJdk>
+ - Optional, defaults to false. When true only a JDK will be used for execution.
+ Launch4j 3.50 An additional check will be performed if javac is available
+ during path and registry search.
+
+
+
+
+
+ - <requires64Bit>
+ - Optional, defaults to false. True limits the runtimes to 64-Bit only, false will use
+ 64-Bit or 32-Bit depending on which is found.
+ Launch4j 3.50 This option works with path and registry search.
+
+
+
+
+
+ - HeapSize, HeapPercent
+ - If size and percent are specified, then the setting which yields
+ more memory will be chosen at runtime. In other words, setting both values
+ means: percent of available memory no less than size in MB.
+ Launch4j 3.50 If the runtime is 32-Bit then a 32-Bit limit
+ will be imposed even if more memory is available during path and registry search.
+
+
+
+
+ - <initialHeapSize>
+ - Optional, initial heap size in MB.
+
+
+ - <initialHeapPercent>
+ - Optional, initial heap size in % of available memory.
+
+
+ - <maxHeapSize>
+ - Optional, max heap size in MB.
+
+
+ - <maxHeapPercent>
+ - Optional, max heap size in % of available memory.
+
+
+
+ - <opt>
+ - Optional, accepts everything you would normally pass to
+ java/javaw launcher: assertion options, system properties and X options.
+ Here you can map environment and special variables EXEDIR
+ (exe's runtime directory), EXEFILE (exe's runtime full file path)
+ to system properties. All variable references must be surrounded with
+ percentage signs and quoted.
+
+<opt>-Dlaunch4j.exedir="%EXEDIR%"</opt>
+<opt>-Dlaunch4j.exefile="%EXEFILE%"</opt>
+<opt>-Denv.path="%Path%"</opt>
+<opt>-Dsettings="%HomeDrive%%HomePath%\\settings.ini"</opt>
+
+
+
+
+
+
+ - <splash>
+ - Optional, groups the splash screen settings. Allowed only in GUI header.
+
+
+
+ - <file>
+ - Splash screen image in BMP format.
+
+
+ - <waitForWindow>
+ - Optional, defaults to true. Close the splash screen when an application
+ window or Java error message box appears. If set to false,
+ the splash screen will be closed on timeout.
+
+
+
+ - <timeout>
+ - Optional, defaults to 60. Number of seconds after which the splash screen
+ must be closed. Splash timeout may cause an error depending on
+ <timeoutErr>.
+
+
+
+ - <timeoutErr>
+ - Optional, defaults to true. True signals an error on splash timeout,
+ false closes the splash screen quietly.
+
+
+
+
+
+ - <versionInfo>
+ - Optional, version information
+ to be displayed by the Windows Explorer.
+
+
+
+ - <fileVersion>
+ - Version number 'x.x.x.x'
+
+
+ - <txtFileVersion>
+ - Free form file version, for example '1.20.RC1'.
+
+
+ - <fileDescription>
+ - File description presented to the user.
+
+
+ - <copyright>
+ - Legal copyright.
+
+
+ - <productVersion>
+ - Version number 'x.x.x.x'
+
+
+ - <txtProductVersion>
+ - Free form file version, for example '1.20.RC1'.
+
+
+ - <productName>
+ - Text.
+
+
+ - <companyName>
+ - Optional text.
+
+
+ - <internalName>
+ - Internal name without extension, original filename or module name for example.
+
+
+ - <originalFilename>
+ - Original name of the file without the path. Allows to determine
+ whether a file has been renamed by a user.
+
+
+
+ - <trademarks>
+ - Trademarks that apply to the file.
+
+
+ - <language>
+ - One of the language codes.
+
+
+
+
Importing 1.x configuration
+1.x configuration is no longer supported by launch4j 3.50. You can convert it to 3.14 and then to 3.50.
+
+
Importing 2.x/3.x configuration to 3.50
+It's possible to import a 2.x/3.x configuration file using the GUI interface.
+Open the file, review all settings carefully as some of them cannot always
+be imported automatically and the search algorithm has changed in version 3.50.
+
+
Ant task
+You may set a launch4j directory property or change the task definition.
+
+
<property name="launch4j.dir" location="/opt/launch4j" />
+
+Define the task in your Ant build script.
+
+
+<taskdef name="launch4j"
+ classname="net.sf.launch4j.ant.Launch4jTask"
+ classpath="${launch4j.dir}/launch4j.jar
+ :${launch4j.dir}/lib/xstream.jar" />
+
+
+Execute the task!
+
+
<launch4j configFile="./l4j/demo.xml" />
+
+You can set or override the following configuration properties...
+
+ jar="absolute path or relative to basedir"
+ jarPath="relative path"
+ outfile
+ fileVersion
+ txtFileVersion
+ productVersion
+ txtProductVersion
+ bindir="alternate bin directory..."
+ tmpdir="alternate working directory..."
+
+
+
+<launch4j configFile="./l4j/demo.xml" outfile="mydemo.exe"
+ fileVersion="1.0.0.0" txtFileVersion="1.0 RC2" />
+
+
+You can also define the entire configuration in the task, but it will
+not be possible to edit such a file in the GUI mode. All paths except
+for
<chdir>,
<jre><path> and
jarPath
+are calculated using the
basedir project attribute.
+
+
+<launch4j>
+ <config headerType="gui" outfile="demo.exe"
+ dontWrapJar="true" jarPath="demo.jar" >
+ <var>SETTINGS="%HomeDrive%%HomePath%\\settings.ini"</var>
+ <classPath mainClass="org.demo.DemoApp">
+ <cp>./lib/looks.jar</cp>
+ <cp>%USER_LIBS%/*.jar</cp>
+ </classPath>
+ <jre path="%JAVA_HOME%;%PATH%" minVersion="1.8.0">
+ <opt>-Dlaunch4j.exedir="%EXEDIR%"</opt>
+ <opt>-Dlaunch4j.exefile="%EXEFILE%"</opt>
+ </jre>
+ </config>
+</launch4j>
+
+
+
Additional JVM options at runtime
+When you create a wrapper or launcher all configuration details are compiled into the
+executable and cannot be changed without recreating it or hacking with a resource editor.
+Launch4j 2.1.2 introduces a new feature that allows to pass additional JVM options
+at runtime from an .l4j.ini file. Now you can specify the options in the configuration file,
+ini file or in both, but you cannot override them. The ini file's name must correspond
+to the executable's
(myapp.exe : myapp.l4j.ini).
+The arguments should be separated with spaces or new lines, environment variable
+expansion is supported, for example:
+
+# Launch4j runtime config
+-Dswing.aatext=true
+-Dsomevar="%SOMEVAR%"
+-Xms16m
+
+
+
Environemnt variables
+The following variables can be used in the configuration file (elements which contain %VAR%).
+They are substitued during runtime, so for example the EXEDIR is the directory where the user installed the wrapped application.
+
+ - %VAR%
+ -
+ Any environment variable, for example %HOMEPATH%.
+
+
+ - %EXEDIR%
+ -
+ Wrapper directory path.
+
+
+ - %EXEFILE%
+ -
+ Wrapper executable file path.
+
+
+ - %PWD%
+ -
+ Current directory, after chdir was applied.
+
+
+ - %OLDPWD%
+ -
+ Directory before chdir was applied.
+
+
+ - %JREHOMEDIR%
+ -
+ Path to the JRE which was selected for executing the application.
+
+
+ - %HKEY_...\...%
+ -
+ Registry key value, e.g.
+ %HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\MemoryDiagnostic\LastScanTime%
+
+
+
+
Runtime options
+
+ - --l4j-debug
+ -
+ To make sure the output executable is configured correctly you can use the
+ debug launching mode to log various information to the launch4j.log file.
+ Environment variable can also be used...
+ SET Launch4j=debug
+
+
+ - --l4j-debug-all
+ -
+ Same as above, but additionally log loaded resources (options stored during wrapper creation).
+ Environment variable can also be used...
+ SET Launch4j=debug-all
+
+
+ - --l4j-dont-wait
+ -
+ Disable the "stay alive" function.
+
+
+ - --l4j-no-splash
+ -
+ Disable the splash screen.
+
+
+ - --l4j-no-splash-err
+ -
+ Disable splash screen error on timeout, might be useful on very slow computers.
+
+
+
+
Settings
+These settings are only used during building of the launcher or wrapper, not during their execution.
+
+ - Alternate bin directory: launch4j.bindir
+ -
+ It's possible to override the default bin directory location which contains windres and ld
+ tools using the launch4j.bindir system property. The property can have two forms:
+ a path relative to Launch4j's directory (altbin for example) or an absolute path.
+
-
+
+
- Working directory: launch4j.tmpdir
+ - Change the working directory if the default path contains spaces which windres cannot handle.
+
+