Updated README.

This commit is contained in:
LoRd_MuldeR 2020-10-02 21:46:35 +02:00
parent e52bbc740e
commit 2c14b5a28d
6 changed files with 60 additions and 18 deletions

View File

@ -1,12 +1,13 @@
![Launch5j](etc/logo.png) ---
title: "![Launch5j](etc/img/logo.png)"
**Java JAR wrapper for creating Windows native executables subtitle: "**Java JAR wrapper for creating Windows native executables**"
created by LoRd_MuldeR &lt;<mulder2@gmx.de>&gt;** ---
# Introduction # Introduction
**Launch5j** is a reimagination of “Launch4j”, *with full Unicode support*. This is a tool for wrapping Java applications distributed as JARs in lightweight Windows native executables. The executable can be configured to search for a certain JRE version or use a bundled one. The wrapper also provides better user experience through an application icon, a native pre-JRE splash screen, and a Java download page in case the appropriate JRE cannot be found. **Launch5j** is a reimagination of “Launch4j”, *with full Unicode support*. This is a tool for wrapping Java applications distributed as JARs in lightweight Windows native executables. The executable can be configured to search for a certain JRE version or use a bundled one. The wrapper also provides better user experience through an application icon, a native pre-JRE splash screen, and a Java download page in case the appropriate JRE cannot be found.
# Usage # Usage
There currently are two different ways to use Launch5j with your application code: There currently are two different ways to use Launch5j with your application code:
@ -34,6 +35,7 @@ There currently are two different ways to use Launch5j with your application cod
**Warning:** Code signing, as with Microsoft&reg;'s `SignTool`, probably does **not** work with the “wrapped” executable file! If code signing is a requirement, please use a *separate* JAR file and just sing the launcher executable. **Warning:** Code signing, as with Microsoft&reg;'s `SignTool`, probably does **not** work with the “wrapped” executable file! If code signing is a requirement, please use a *separate* JAR file and just sing the launcher executable.
# Variants # Variants
Launch5j executables come in a number of variants, allowing you to pick the most suitable one for you project: Launch5j executables come in a number of variants, allowing you to pick the most suitable one for you project:
@ -59,13 +61,14 @@ All of the above Launch5j variants are available as `x86` (32-Bit) and `x64` (64
*Note:* Launch5j has been tested to work correctly on Windows XP (Service Pack 2), or a compatible newer version. *Note:* Launch5j has been tested to work correctly on Windows XP (Service Pack 2), or a compatible newer version.
# Customizations # Customizations
Launch5j comes with a *default* executable icon and a *default* splash screen bitmap. These just server as an example and you probably want to replace them with your own *application-specific* graphics. Launch5j comes with a *default* executable icon and a *default* splash screen bitmap. These just server as an example and you probably want to replace them with your own *application-specific* graphics.
It is ***not*** necessary to re-build the executable files for that purpose. Instead, you can simply use a resource editor, such as [**XN Resource Editor**](https://web.archive.org/web/20100419201225/http://www.wilsonc.demon.co.uk/d10resourceeditor.htm) ([mirror](https://stefansundin.github.io/xn_resource_editor/)) or [**Resource Hacker&trade;**](http://www.angusj.com/resourcehacker/), to *modify* the pre-compiled executable files as needed: It is ***not*** necessary to re-build the executable files for that purpose. Instead, you can simply use a resource editor, such as [**XN Resource Editor**](https://web.archive.org/web/20100419201225/http://www.wilsonc.demon.co.uk/d10resourceeditor.htm) ([mirror](https://stefansundin.github.io/xn_resource_editor/)) or [**Resource Hacker&trade;**](http://www.angusj.com/resourcehacker/), to *modify* the pre-compiled executable files as needed:
![reshack](etc/reshacker-example.png) ![Resource Hacker](etc/img/reshacker-example.png)
## Additional options ## Additional options
@ -131,6 +134,7 @@ Some options can be configured via the launcher executable's [STRINGTABLE](https
*Note:* We use the convention that the default resource string value `"?"` is used to represent an “undefined” value, because resource strings cannot be empty. You can replace the default value as needed! *Note:* We use the convention that the default resource string value `"?"` is used to represent an “undefined” value, because resource strings cannot be empty. You can replace the default value as needed!
# Unicode command-line arguments # Unicode command-line arguments
There is a *long-standing* bug in Java on the Windows&trade; platform, which causes *Unicode* command-line arguments to be “mangled”. Even if the Unicode command-line arguments are properly passed to the Java executable (`java.exe`), they are **not** passed trough correctly to the `main()` method of your Java program! This problem can be reproduced in *all* Java versions ranging from Java 7 (1.7) up to and including the latest Java 15, as of October 2020. There is a *long-standing* bug in Java on the Windows&trade; platform, which causes *Unicode* command-line arguments to be “mangled”. Even if the Unicode command-line arguments are properly passed to the Java executable (`java.exe`), they are **not** passed trough correctly to the `main()` method of your Java program! This problem can be reproduced in *all* Java versions ranging from Java 7 (1.7) up to and including the latest Java 15, as of October 2020.
@ -164,15 +168,31 @@ public class YourMainClass {
} }
``` ```
***Example:***
![Unicode command-line arguments](etc/img/unicode-args.png)
## The JAR file name ## The JAR file name
Be aware that the same problem of “mangled” Unicode characters applies when the path of the JAR file is passed to the Java executable. In other words, the Java runtime *fails* to execute any JAR files whose path &ndash; file name or directory name anywhere in the path &ndash; contains any Unicode characters that cannot be represented in the computer's *local* ANSI codepage! Unfortunately, we can **not** encode the path of the JAR file as we do with the other command-line arguments, because the Jave executable requires the path of the JAR file to be passed in a non-encoded form. Be aware that the same problem of “mangled” Unicode characters applies when the path of the JAR file is passed to the Java executable. In other words, the Java runtime *fails* to execute any JAR files whose path &ndash; file name or directory name anywhere in the path &ndash; contains any Unicode characters that cannot be represented in the computer's *local* ANSI codepage! Unfortunately, we can **not** encode the path of the JAR file as we do with the other command-line arguments, because the Jave executable requires the path of the JAR file to be passed in a non-encoded form.
Therefore, it is recommended to ***only*** use ASCII characters in the name of your JAR file and in the “install” path !!! Therefore, it is recommended to ***only*** use ASCII characters in the name of your JAR file and in the “install” path !!!
# Source code
The source code of **Launch5j** is available from the official Git mirrors at:
* `git clone https://github.com/lordmulder/Launch5j.git`
* `git clone https://bitbucket.org/muldersoft/launch5j.git`
* `git clone https://gitlab.com/lord_mulder/launch5j.git`
# Build instructions # Build instructions
In order to build Launch5j from the sources, it is recommended to use the [*GNU C Compiler* (GCC)](https://gcc.gnu.org/) for Windows, as provided by the [*Mingw-w64*](http://mingw-w64.org/) project. Other C compilers may work, but are **not** officially supported. In order to build **Launch5j** from the sources, it is recommended to use the [*GNU C Compiler* (GCC)](https://gcc.gnu.org/) for Windows, as provided by the [*Mingw-w64*](http://mingw-w64.org/) project. Other C compilers may work, but are **not** officially supported.
Probably the most simple way to set up the required build environment is by installing the [**MSYS2**](https://www.msys2.org/) distribution, which includes *GCC* (Mingw-w64) as well as all the required build tools, such as *Bash* and *GNU make*. Probably the most simple way to set up the required build environment is by installing the [**MSYS2**](https://www.msys2.org/) distribution, which includes *GCC* (Mingw-w64) as well as all the required build tools, such as *Bash* and *GNU make*.
@ -188,11 +208,20 @@ Once the build environment has been set up, just run the provided Makefile:
*Note:* In order to create 32-Bit or 64-Bit binaries, use the `mingw32` or `mingw64` sub-system of MSYS2, respectively. *Note:* In order to create 32-Bit or 64-Bit binaries, use the `mingw32` or `mingw64` sub-system of MSYS2, respectively.
# Contact
**Launch5j** was created by LoRd_MuldeR &lt;<mulder2@gmx.de>&gt;.
For help and support, please visit:
<https://github.com/lordmulder/Launch5j/issues>
# Acknowledgment # Acknowledgment
This project is partly inspired by the “Launch4j” project, even though it has been re-written from scratch: This project is partly inspired by the “Launch4j” project, even though it has been re-written from scratch:
<https://sourceforge.net/p/launch4j/> <https://sourceforge.net/p/launch4j/>
# License # License
This work has been released under the MIT license: This work has been released under the MIT license:

View File

Before

Width:  |  Height:  |  Size: 23 KiB

After

Width:  |  Height:  |  Size: 23 KiB

View File

Before

Width:  |  Height:  |  Size: 72 KiB

After

Width:  |  Height:  |  Size: 72 KiB

BIN
etc/img/unicode-args.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 43 KiB

View File

@ -1,6 +1,15 @@
@echo off @echo off
setlocal enabledelayedexpansion
cd /d "%~dp0" cd /d "%~dp0"
set "PANDOC_DIR=C:\Program Files (x86)\Pandoc"
if not exist "%PANDOC_DIR%\pandoc.exe" (
echo Pandoc not found. Please check PANDOC_DIR and try again^^!
pause
goto:eof
)
REM ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ REM ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
REM Get current date REM Get current date
REM ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ REM ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -58,18 +67,22 @@ REM Copy binaries
REM ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ REM ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
mkdir "%~dp0.\out\~package" mkdir "%~dp0.\out\~package"
mkdir "%~dp0.\out\~package\example"
mkdir "%~dp0.\out\~package\x86"
mkdir "%~dp0.\out\~package\x64" mkdir "%~dp0.\out\~package\x64"
copy /Y "%~dp0.\*.txt" "%~dp0.\out\~package" copy /Y "%~dp0.\bin\launch5j_x86*.exe" "%~dp0.\out\~package"
copy /Y "%~dp0.\*.md" "%~dp0.\out\~package"
copy /Y "%~dp0.\bin\launch5j_x86*.exe" "%~dp0.\out\~package\x86"
copy /Y "%~dp0.\bin\launch5j_x64*.exe" "%~dp0.\out\~package\x64" copy /Y "%~dp0.\bin\launch5j_x64*.exe" "%~dp0.\out\~package\x64"
copy /Y /B "%~dp0.\bin\launch5j_x86_wrapped_registry.exe" + "%~dp0.\etc\example\dist\example.jar" "%~dp0.\out\~package\example\example.exe" mkdir "%~dp0.\out\~package\etc"
copy /Y "%~dp0.\etc\example\src\com\muldersoft\l5j\example\Main.java" "%~dp0.\out\~package\example\example.java" mkdir "%~dp0.\out\~package\etc\example"
mkdir "%~dp0.\out\~package\etc\img"
copy /Y "%~dp0.\*.txt" "%~dp0.\out\~package"
copy /Y "%~dp0.\etc\img\*.png" "%~dp0.\out\~package\etc\img"
copy /Y /B "%~dp0.\bin\launch5j_x86_wrapped_registry.exe" + "%~dp0.\etc\example\dist\example.jar" "%~dp0.\out\~package\etc\example\example.exe"
copy /Y "%~dp0.\etc\example\src\com\muldersoft\l5j\example\Main.java" "%~dp0.\out\~package\etc\example\example.java"
"%PANDOC_DIR%\pandoc.exe" -f markdown-implicit_figures -t html -T "Launch5j" --toc "%~dp0.\README.md" > "%~dp0.\out\~package\README.html"
attrib +R "%~dp0.\out\~package\*.*" /S attrib +R "%~dp0.\out\~package\*.*" /S

View File

@ -49,8 +49,8 @@ END
///////////////////////////////////////////////////////////////////////////// /////////////////////////////////////////////////////////////////////////////
VS_VERSION_INFO VERSIONINFO VS_VERSION_INFO VERSIONINFO
FILEVERSION 0,5,1,0 FILEVERSION 0,6,0,0
PRODUCTVERSION 0,5,1,0 PRODUCTVERSION 0,6,0,0
FILEFLAGSMASK 0x17L FILEFLAGSMASK 0x17L
#ifdef _DEBUG #ifdef _DEBUG
FILEFLAGS 0x3L FILEFLAGS 0x3L
@ -67,8 +67,8 @@ BEGIN
BEGIN BEGIN
VALUE "ProductName", "Launch5j" VALUE "ProductName", "Launch5j"
VALUE "FileDescription", "Launch5j" VALUE "FileDescription", "Launch5j"
VALUE "ProductVersion", "0.5.1" VALUE "ProductVersion", "0.6.0"
VALUE "FileVersion", "0.5.1" VALUE "FileVersion", "0.6.0"
VALUE "InternalName", "Launch5j" VALUE "InternalName", "Launch5j"
VALUE "OriginalFilename", "launch5j.exe" VALUE "OriginalFilename", "launch5j.exe"
VALUE "LegalCopyright", "Created by LoRd_MuldeR <MuldeR2@GMX.de>" VALUE "LegalCopyright", "Created by LoRd_MuldeR <MuldeR2@GMX.de>"