+
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.
+
+
+<!--
+ 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>
+ <!-- Specify path or minVersion or both. -->
+ <path>bundled JRE path (%VAR%)</path>
+ <bundledJre64Bit>true|false</bundledJre64Bit>
+ <bundledJreAsFallback>true|false</bundledJreAsFallback>
+ <minVersion>x.x.x[_xx]</minVersion>
+ <maxVersion>x.x.x[_xx]</maxVersion>
+ <jdkPreference>jreOnly|preferJre|preferJdk|jdkOnly</jdkPreference>
+ <runtimeBits>64|64/32|32/64|32</runtimeBits>
+ <!-- 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>
+ <bundledJreErr>text</bundledJreErr>
+ <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 the absolute or relative path (to the executable) of a bundled JRE, it
+ does not rely on the current directory or <chdir>.
+ Note that this path is not checked until the actual application execution.
+ If you'd like the wrapper to search for a JRE (public or SDK private)
+ use the <minVersion> property, you may also specify
+ the <maxVersion> to prevent it from using higher Java versions.
+ Launch4j will always use the highest version available (in the min/max range of course).
+ If a Sun's JRE is not available or does not satisfy the search criteria,
+ the search will be repeated on IBM runtimes.
+ You can also combine these properties to change the startup process...
+
+
+
+
+ - <path>
+ - Run if bundled JRE and javaw.exe are present, otherwise stop with error.
+ - <path> + <minVersion> [+ <maxVersion>]
+ - Use bundled JRE first, if it cannot be located search for Java,
+ if that fails display error message and open the Java download page.
+
+ - <minVersion> [+ <maxVersion>]
+ - Search for Java, if an appropriate version cannot be found display
+ error message and open the Java download page.
+
+
+
+
+
+
+ - <bundledJre64Bit>
+ - Optional, defaults to false which limits the calculated heap size to the 32-bit maximum.
+ Set to true in order to use the available memory without this limit. This option works
+ in combination with the HeapSize and HeapPercent options only if the found JRE is a bundled one.
+ In the standard JRE search based on registry the wrapper detects the type of JRE itself
+ and uses the 32-bit heap limit when needed.
+
+
+
+
+
+ - <bundledJreAsFallback>
+ - Optional, defaults to false which treats the bundled JRE as the primary runtime.
+ When set to true, the bundled JRE will only be used in case the mix/max version search fails.
+ This can be used as a fallback option if the user does not have the required Java installed
+ and the bundled JRE is provided on a CD or shared network location.
+
+
+
+
+
+ - <jdkPreference>
+ - Optional, defaults to preferJre; Allows you to specify a preference
+ for a public JRE or a private JDK runtime. Valid values are:
+
+
+
+
+ - jreOnly
+ - Always use a public JRE (equivalent to the
+ old option dontUsePrivateJres=true)
+ - preferJre
+ - Prefer a public JRE, but use a JDK private
+ runtime if it is newer than the public
+ JRE (equivalent to the old option
+ dontUsePrivateJres=false)
+ - preferJdk
+ - Prefer a JDK private runtime, but use a
+ public JRE if it is newer than the JDK
+
+ - jdkOnly
+ - Always use a private JDK runtime (fails
+ if there is no JDK installed)
+
+
+
+
+ - <runtimeBits>
+ - Optional, defaults to 64/32; Allows to select between 64-bit and 32-bit runtimes.
+ Valid values are:
+
+
+
+
+ - 64
+ - Use only 64-bit runtimes
+ - 64/32
+ - Use 64-bit runtimes if available, otherwise use 32-bit
+ - 32/64
+ - Use 32-bit runtimes if available, otherwise use 64-bit
+ - 32
+ - Use only 32-bit runtimes
+
+
+
+ - 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.
+
+
+
+
+ - <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
+It's possible to import a 1.x configuration file using the GUI
+interface. Open the file, correct the paths and save it as a new xml
+configuration.
+
+
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 minVersion="1.4.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.
+
+