Erstellung eines Windows EXE-Starters

Beim Paketieren kann ein nativer Windows-Startprogramm für die geschützte Anwendung erstellt werden. Es handelt sich um eine reine Win32-Exekutabel, mit der die Anwendung mit einem Doppelklick gestartet werden kann – ohne dass der Benutzer zuerst Java installieren muss oder run.bat sehen muss.

EXE ist optional und wird standardmäßig nicht erzeugt. Wenn es aktiviert wird, bleiben die ursprünglichen Dateien run.sh / run.command / run.bat im generierten Paket erhalten. Beide Startmethoden verwenden exakt dieselben Archivierung, Classpath, Hauptklasse und JVM-Parameter.

1. Anwendungsgebiet

Es muss mindestens eine Windows-Zielplattform ausgewählt werden. Die gleichzeitige Auswahl von Linux- oder macOS-Plattformen führt nicht zum Scheitern der Aufgabe: Die Unterpakete für diese Plattformen werden wie gewohnt erstellt, es gibt jedoch keine EXE-Dateien, und die ursprünglichen Startskripte werden weiterhin verwendet. Wenn keine der Zielplattformen Windows ist, tritt direkt ein Fehler auf.

2. GUI-Bearbeitung

1. Auf der Seite zur Auswahl der Eingabedatei und der Zielplattform muss Erstellung einer Windows-EXE-Anwendung (x64/x86/ARM64) angechecked werden, und zudem muss mindestens eine Windows-Zielplattform ausgewählt werden.
2. Dieser Schalter befindet sich vor der Abzweigung zwischen dem Einfachmodus und dem Fortgeschrittenen Modus, sodass in beiden Modi EXE-Dateien erzeugt werden können.
3. Nach dem Anchecken erscheint eine zusätzliche Seite Windows EXE-Launcher, auf der der Dateinamen, der Starter-Modus, das Icon sowie die Windows-Versionsinformationen eingegeben werden können. Wenn dieser Schalter nicht angechecked wird, wird direkt zur endgültigen Bestätigungsseite übergegangen.
4. Nach Aktivierung der EXE erscheint das Eingabefeld JVM-Startparameter nur auf dieser Starter-Seite, um zu vermeiden, dass derselbe Parameter über zwei Eingänge verfügbar ist. Die eingegebenen Parameter werden gleichzeitig in die EXE sowie in das Starter-Skript geschrieben.
5. Auf der Endbestätigungsseite werden die Plattformen aufgelistet, auf denen tatsächlich eine EXE erzeugt wird, sowie die im Starter eingegebenen Felder.

3. CLI-Beispiel

Kurzform – nur --windows-exe erforderlich:

p4j --target-platform windows-x64 javaapp app.jar dist --windows-exe

Angabe von Dateinamen und Fenstermodus:

p4j --target-platform windows-x64 javaapp app.jar dist \
  --windows-exe \
  --exe-name MyApp.exe \
  --exe-mode gui \
  --exe-icon assets/app.ico

Erstellung von drei Windows-Architekturen auf einmal sowie Eingabe vollständiger Versionserfassungsdaten:

p4j --target-platform windows-x64,windows-x86,windows-aarch64 \
  springboot app.jar dist \
  --windows-exe \
  --exe-name MyService \
  --exe-file-version 1.4.2.0 \
  --exe-product-version 1.4.2.0 \
  --exe-company 'Example Inc.' \
  --exe-product 'Example Service' \
  --exe-description 'Example background service' \
  --exe-copyright 'Copyright (C) 2026 Example Inc.'

Auch Tomcat-Pakete werden unterstützt; die erzeugte EXE startet mit dem eingebetteten Tomcat im Vordergrund:

p4j --target-platform windows-x64 tomcat app.war dist --context /demo --windows-exe

4. Erläuterung der Parameter

Jede Option von --exe-* aktiviert automatisch die Erstellung eines EXE-Files – es ist daher nicht notwendig, zusätzlich --windows-exe zu verwenden.

Der Dateiname darf ausschließlich aus einem Dateinamen bestehen und darf weder /, \ noch Verzeichnisanteile enthalten; fehlt das .exe-Suffix, wird dieses automatisch hinzugefügt.

Für beide Versionsschlüsselfelder gelten dieselben Regeln: Zahlen von 1 bis 4, getrennt durch englische Punkte, wobei jeder Wert zwischen 0 und 65535 liegen muss, wie z. B. 1.0.0.1. Windows speichert jeden Wert als 16-Bit-ungesicherten Integer, weshalb Formate mit Buchstaben oder Leerzeichen wie v1.0 oder 1.0-beta nicht akzeptiert werden. Ein leeres Feld bedeutet 0.0.0.0. Diese beiden Felder werden vor dem Start des Paketierungsprozesses überprüft, sodass Fehler nicht erst während des Prozesses auftreten.

5. Ausgabestruktur

Am Beispiel einer Java Application: EXE-Dateien und Startskripte befinden sich gemeinsam im Wurzelverzeichnis des Pakets:

dist/
├── MyApp.exe             # Der neu hinzugefügte Starter Windows
├── app.p4jx
├── vlxjre/
├── lib/
├── run.sh
├── run.command
├── run.bat
└── README.md

README.md im Paket listet die Namen der erzeugten EXE-Dateien auf und gibt Hinweise zur Code-Signierung.

6. Laufverhalten

Das Verzeichnis, in dem sich die EXE befindet, ist gleichzeitig das Wurzelverzeichnis der Anwendung. Der Starter akzeptiert nur Laufzeitumgebungen, Archivformate, Classpath-Verzeichnisse und Arbeitsverzeichnisse innerhalb des Wurzelverzeichnisses; Pfade außerhalb des Pakets sowie Pfade, die durch Symbolverknüpfungen oder Junctions ersetzt wurden, werden abgelehnt, wodurch der Prozess nicht gestartet wird. Das bedeutet, dass das gesamte Paket verschoben oder umbenannt werden kann, aber die EXE nicht einzeln kopiert und verwendet werden darf.

Die JVM-Parameter des EXE werden bei der Paketierung festgelegt und zusammen mit dem Parameterblock signiert; eine Änderung ist nach dem Deployieren nicht möglich. APP_JAVA_OPTS ist nur für run.bat gültig und wird vom EXE nicht gelesen. Falls die JVM-Parameter des EXE geändert werden müssen, ist eine erneute Paketierung erforderlich.

Aus demselben Grund ist das Schreiben von Startparametern in das EXE für -javaagent, -agentlib, -agentpath, -Xbootclasspath und --patch-module nicht zulässig. Wenn diese Parameter über --jvm-option übergeben werden, scheitert die Paketierung direkt.

7. Code-Signing

Protector4J fügt dem generierten EXE weder einen Veröffentlichersignatur hinzu noch greift es auf irgendwelche Authenticode-Zertifikate zu. Alle PE-Änderungen wie Icon, Versionsressourcen und Startparameter werden bereits in der Paketierungsphase vorgenommen, weshalb der Signierungsschritt zuletzt erfolgen sollte:

1. Fertigen Sie die Paketierung ab und überprüfen Sie, ob das EXE die Anwendung ordnungsgemäß starten kann.
2. Führen Sie eine Authenticode-Signierung mit Ihrem eigenen Zertifikat durch und fügen Sie einen RFC3161-Timestamp hinzu.
3. Überprüfen Sie die Signatur mithilfe der Windows-Policy /pa.

Ändern Sie diese PE-Datei nach Abschluss der Signierung nicht mehr – jede Änderung macht die Signierung ungültig. Wenn Sie ein anderes Icon oder eine andere Versionnummer benötigen, packen Sie die Datei erneut zusammen und signieren Sie sie erneut.

8. Felder der Aufgabendatei

Die exportierte p4j-task.yml verwendet Version 2; bei Aktivierung von EXE werden die folgenden Felder gespeichert. Aufgabendateien von Version 1 können weiterhin normal gelesen werden.

windowsExe: true
exeName: MyApp.exe
exeMode: console
exeIcon: assets/app.ico
exeFileVersion: 1.4.2.0
exeProductVersion: 1.4.2.0
exeCompany: Example Inc.
exeProduct: Example Service
exeDescription: Example background service
exeCopyright: Copyright (C) 2026 Example Inc.

9. Häufige Fragen

Weitere Informationen zu den vollständigen CLI-Optionen finden Sie unter Referenz für CLI-Parameter, zum GUI-Assistentenverfahren unter GUI-Benutzerhandbuch.