CLI-Referenz
Die Beispiele auf dieser Seite verwenden den Befehl p4j, den die Installation bereitstellt. Unter Windows wird die GUI aus der .exe installiert, unter macOS aus Protector4J.app in der .dmg; die Art der GUI-Installation ändert nichts an der folgenden CLI-Syntax. Hat das Installationsprogramm die CLI nicht in den PATH aufgenommen, starten Sie sie über den Kommandozeilen-Einstiegspunkt im Installationsverzeichnis von Protector4J.
p4j --help
1. Befehle
p4j encode <input.jar> <output.p4jx|output.jar> [Optionen]
p4j javaapp <input.jar> <Ausgabeverzeichnis> [Optionen]
p4j springboot <input.jar> <Ausgabeverzeichnis> [Optionen]
p4j tomcat <input.war> <Ausgabeverzeichnis> [Optionen]
Beim systemnahen encode darf der Befehlsname auch entfallen:
p4j input.jar output.p4jx [Optionen]
Optionen auf Startebene wählen das Paketierungsziel. Sie dürfen vor dem Befehlsnamen stehen oder gesammelt am Ende der Kommandozeile — die von der GUI exportierte Kommandozeile nutzt die zweite Form.
| Option | Beschreibung |
|---|---|
--java-version <N> | Die mitzuliefernde Java-Linie: 8, 11, 17, 21 oder 25. Standard ist 21 |
--target-platform <id>[,<id>...] | Eine oder mehrere Zielplattformen, durch Kommas getrennt oder durch Wiederholen der Option. Standard ist die aktuelle Plattform |
--create-new-folder | Legt im Ausgabeverzeichnis ein neues Unterverzeichnis p4jx-xxxxxxxx an. Gilt nur für javaapp, springboot und tomcat |
Beispiel:
p4j --java-version 21 --target-platform linux-x64 springboot app.jar dist
p4j springboot app.jar dist --java-version 21 --target-platform linux-x64
Beide Befehle sind gleichwertig. Optionen auf Startebene dürfen nicht zwischen den Packager-Optionen stehen; dort werden sie als unbekannte Packager-Optionen gelesen und der Befehl schlägt fehl.
2. Allgemeine Optionen
| Option | Beschreibung |
|---|---|
--jre-home <path> | Leitet die Schlüssel aus der angegebenen finalen P4JX-JRE-Runtime ab. Die übergeordneten Paketierungsbefehle kopieren diese Runtime zusätzlich |
--keys <keys.json> | Verwendet eine explizite private Schlüsseldatei. Nur für Diagnose und interne Abläufe — niemals mit der Anwendung ausliefern |
--no-jit | Hält geschützte Methoden vom JIT fern und führt sie im Interpreter aus |
--zip-overlay off|scanner | Schaltet die Scanner-ZIP-Kompatibilitätssicht aus oder ein. Standard ist off |
--compat-scan | Scannt und endet; ein Ausgabeargument ist nicht nötig |
--compat-apply | Scannt, übernimmt die konservativen Empfehlungen und encodiert anschließend |
--no-compat-excludes | Zusammen mit --compat-apply: fügt die empfohlenen Ausschlüsse nicht automatisch hinzu |
--native-compat jxbrowser | Nur für javaapp und springboot: fordert die Zulassung des mitgelieferten JxBrowser an. Version, Plattform und der fünfschichtige Hash werden weiterhin vollständig geprüft; andere Werte, Pfade oder Hashes werden nicht akzeptiert |
--account-email <email> | E-Mail-Adresse des lizenzierten Kontos |
--account-password <password> | Kennwort des lizenzierten Kontos |
--app-id <id> | Anwendungskennung |
--license-expires-in <sec> | Gewünschte Testdauer in Sekunden, im Rahmen der Serverrichtlinie |
Die übergeordneten Paketierungsbefehle unterstützen zusätzlich:
| Option | Beschreibung |
|---|---|
--archive-suffix p4jx|jar | Suffix des erzeugten Archivs, Standard p4jx. Das interne Format ändert sich dadurch nicht |
--jvm-option <option> | Schreibt die Option in die Startskripte für macOS, Linux und Windows. Eine Option je Schalter, beliebig wiederholbar. Bei aktivierter Windows-EXE landen dieselben Optionen auch in der EXE |
3. encode
p4j encode input.jar output.p4jx [Optionen]
| Option | Beschreibung |
|---|---|
--bind-launcher <jar> | Berechnet den SHA-256 des Starter-JAR und bindet ihn ein |
--launcher-sha256 <hex> | Übergibt den SHA-256 des Starters direkt, für fortgeschrittene Integrationen |
--runtime-major <N> | Ziel für Ressourcensicht und Multi-Release-Reduktion. Standard 21 |
--bind-launcher und --launcher-sha256 lassen sich nicht gemeinsam verwenden.
4. javaapp
p4j javaapp input.jar Ausgabeverzeichnis [Optionen]
| Option | Beschreibung |
|---|---|
--main <class> | Die zu startende Hauptklasse |
--protect <rules> | Regeln für die zu schützenden Klassen und Pakete, durch Kommas getrennt. Standard sind alle Klassen |
--exclude <rules> | Regeln für das, was außerhalb des Schutzumfangs bleibt |
--javafx [<dir>] | Aktiviert JavaFX, optional aus einem lokalen Komponentenverzeichnis |
--javafx-webview | Nimmt WebView immer auf |
--no-javafx-webview | Nimmt WebView nie auf |
--no-javafx | Deaktiviert JavaFX ausdrücklich |
--native-compat jxbrowser | Schreibt ATTACH_THREAD für die JxBrowser-IPC-Bibliotheken, die dem mitgelieferten Verzeichnis exakt entsprechen. Nur Java 17, 21 und 25 |
5. springboot
p4j springboot input.jar Ausgabeverzeichnis [Optionen]
| Option | Beschreibung |
|---|---|
--main <class> | Die Spring-Boot-Hauptklasse. Wird standardmäßig aus dem Manifest gelesen |
--protect <rules> | Schützt die passenden Klassen in BOOT-INF/classes |
--exclude <rules> | Lässt die passenden Klassen oder Pakete ungeschützt |
--protect-lib <globs> | Schützt die passenden JARs in BOOT-INF/lib, durch Kommas getrennt |
--layout p4jx-fat|fat|separate | Ausgabelayout, Standard p4jx-fat |
--javafx [<dir>] | Aktiviert JavaFX, optional aus einem lokalen Komponentenverzeichnis |
--javafx-webview | Nimmt WebView immer auf |
--no-javafx-webview | Nimmt WebView nie auf |
--no-javafx | Deaktiviert JavaFX ausdrücklich |
--native-compat jxbrowser | Wie bei javaapp; derselbe Scanner erfasst auch das verschachtelte BOOT-INF/lib |
6. tomcat
p4j tomcat input.war Ausgabeverzeichnis [Optionen]
| Option | Beschreibung |
|---|---|
--exclude <rules> | Lässt die passenden Klassen oder Pakete in WEB-INF/classes ungeschützt |
--context </path> | Kontextpfad, Standard /app |
--append-app | Fügt die Anwendung einem vorhandenen P4JX-Tomcat-Paket hinzu |
--tomcat-version auto|9|10 | Automatisch erkennen oder Version erzwingen. Auf der CLI ist auto der Standard |
--precompile-jsp | Erzwingt die JSP-Vorkompilierung |
--no-precompile-jsp | Schaltet die JSP-Vorkompilierung ab |
7. Optionen für die Windows-EXE
javaapp, springboot und tomcat können zusätzlich einen nativen Windows-Starter erzeugen. Die Zielplattformen müssen windows-x64, windows-x86 oder windows-aarch64 enthalten.
| Option | Beschreibung |
|---|---|
--windows-exe | Erzeugt eine Windows-Anwendungs-EXE. Ohne diese Option entsteht keine |
--exe-name <name> | Dateiname der EXE; standardmäßig der Name der Eingabedatei, bei tomcat-Paketen tomcat |
--exe-mode <mode> | console (Standard) oder gui |
--exe-icon <ico> | Optionales Windows-Symbol im .ico-Format |
--exe-file-version <a.b.c.d> | PE-Dateiversion: ein bis vier Zahlen, jede zwischen 0 und 65535. Leer bedeutet 0.0.0.0 |
--exe-product-version <a.b.c.d> | PE-Produktversion, gleiche Regeln |
--exe-company <text> | Firmenname |
--exe-product <text> | Produktname |
--exe-description <text> | Dateibeschreibung |
--exe-copyright <text> | Copyright-Hinweis |
Jede --exe-*-Option aktiviert die EXE-Erzeugung von selbst. Bei einer Aufgabe mit mehreren Plattformen erhalten nur die Windows-Pakete eine EXE; die übrigen entstehen wie gewohnt und behalten ihre Startskripte.
p4j --target-platform windows-x64 javaapp app.jar dist --windows-exe --exe-name MyApp.exe --exe-mode gui
Die vollständige Anleitung, das Laufzeitverhalten und die Schritte zur Codesignatur beschreibt Windows-EXE-Starter erzeugen.
8. Regelsyntax
com.example.SecretService eine einzelne Klasse
com.example.service nur dieses Paket
com.example.service.* nur dieses Paket
com.example.service.** dieses Paket und alle Unterpakete
com/example/Secret.class Pfad eines Klasseneintrags
Mehrere Regeln trennen Sie durch Kommas. Setzen Sie Regeln mit * in Anführungszeichen, damit die Shell sie nicht expandiert:
--protect 'com.example.**' --exclude 'com.example.dto.**,com.example.config.**'
9. Umgebungsvariablen
Umgebungsvariablen eignen sich für gemeinsame Vorgaben in einem CI-Job, einem Container oder bei mehreren nacheinander ausgeführten Befehlen. Soll ein einzelner Paketierungslauf dokumentiert und reproduzierbar sein, geben Sie die Werte besser ausdrücklich als CLI-Optionen an.
| Variable | Entsprechende CLI-Option | Beschreibung |
|---|---|---|
P4JX_RUNTIME_JAVA_VERSION | --java-version <N> | Die Java-Linie für die übergeordnete Paketierung: 8, 11, 17, 21 oder 25 |
P4JX_RUNTIME_PLATFORM | --target-platform <id> | Eine einzelne Zielplattform. Für mehrere Plattformen in einem Lauf nutzen Sie die CLI-Option |
P4JX_RUNTIME_CACHE_DIR | keine | Überschreibt das Cache-Verzeichnis für den VLX-JRE-Download |
APP_JAVA_OPTS | vergleiche --jvm-option | Ergänzt JVM-Optionen für einen einzelnen Lauf der erzeugten Anwendung. --jvm-option schreibt Optionen beim Paketieren ins Startskript; die beiden sind daher nicht gleichwertig |
Sind eine Variable und die zugehörige CLI-Option gesetzt, gewinnt die ausdrücklich angegebene CLI-Option. Die Umgebungsvariablen werden weiterhin vollständig unterstützt, bestehende Automatisierungsskripte funktionieren also unverändert.
Beispiel: ein gemeinsames Ziel für mehrere Paketierungsbefehle in der aktuellen Shell setzen:
export P4JX_RUNTIME_JAVA_VERSION=21
export P4JX_RUNTIME_PLATFORM=linux-x64
p4j springboot service-a.jar release/service-a
p4j springboot service-b.jar release/service-b
Für fortgeschrittene Fälle, in denen Sie das Packager-JAR direkt starten, gibt es entsprechende Java-Systemeigenschaften:
-Dp4jx.runtime.java.version=<N>
-Dp4jx.runtime.platform=<platform>
-Dp4jx.runtime.cache.dir=<dir>
10. Automatisierungsbeispiel
p4j --java-version 21 \
--target-platform linux-x64 \
springboot build/app.jar release/linux-x64 \
--compat-apply \
--protect 'com.example.service.impl.**' \
--exclude 'com.example.dto.**,com.example.config.**' \
--jvm-option -Xms1g \
--jvm-option -Xmx2g \
--app-id com.example.app
Ausdrücklich gesetzte Optionen für Schutz, Ausschluss und Layout überschreiben die automatischen Empfehlungen. Halten Sie die endgültigen Optionen, den SHA-256 der Eingabedatei und die Werkzeugversion als Nachweis zur Herkunft Ihres Releases fest.
Beispiele für GUI und CLI sowie das Bearbeiten von run.sh, run.bat, den Tomcat-Startskripten und Windows PowerShell finden Sie unter JVM-Startoptionen.