Referencia de la línea de comandos
Los ejemplos de esta página usan el comando p4j que proporciona la instalación. En Windows la interfaz gráfica se instala desde el .exe y en macOS desde Protector4J.app, dentro del .dmg; la forma de instalarla no cambia la sintaxis que sigue. Si el instalador no añadió la CLI al PATH, ejecútela desde el punto de entrada de línea de comandos del directorio de instalación de Protector4J.
p4j --help
1. Comandos
p4j encode <input.jar> <output.p4jx|output.jar> [opciones]
p4j javaapp <input.jar> <directorio de salida> [opciones]
p4j springboot <input.jar> <directorio de salida> [opciones]
p4j tomcat <input.war> <directorio de salida> [opciones]
En el encode de bajo nivel puede omitirse el nombre del comando:
p4j input.jar output.p4jx [opciones]
Las opciones de nivel de arranque eligen el destino del empaquetado. Pueden ir antes del nombre del comando o agrupadas al final de la línea; la línea de comandos que exporta la interfaz usa esta segunda forma.
| Opción | Descripción |
|---|---|
--java-version <N> | La línea de Java que se incluirá: 8, 11, 17, 21 o 25. Por defecto, 21 |
--target-platform <id>[,<id>...] | Una o varias plataformas de destino, separadas por comas o repitiendo la opción. Por defecto, la plataforma actual |
--create-new-folder | Crea un subdirectorio p4jx-xxxxxxxx nuevo dentro del directorio de salida. Solo para javaapp, springboot y tomcat |
Por ejemplo:
p4j --java-version 21 --target-platform linux-x64 springboot app.jar dist
p4j springboot app.jar dist --java-version 21 --target-platform linux-x64
Ambos comandos son equivalentes. Las opciones de nivel de arranque no pueden intercalarse entre las del empaquetador: allí se interpretan como opciones desconocidas y el comando falla.
2. Opciones comunes
| Opción | Descripción |
|---|---|
--jre-home <path> | Deriva las claves del entorno de ejecución P4JX final indicado. Los comandos de nivel superior copian además ese entorno |
--keys <keys.json> | Usa un archivo de claves privadas explícito. Solo para diagnóstico y procesos internos; nunca se distribuye con la aplicación |
--no-jit | Mantiene los métodos protegidos fuera del JIT y los ejecuta en el intérprete |
--zip-overlay off|scanner | Desactiva o activa la vista de compatibilidad ZIP para escáneres. Por defecto, off |
--compat-scan | Analiza y termina; no hace falta argumento de salida |
--compat-apply | Analiza, aplica las recomendaciones conservadoras y continúa con la codificación |
--no-compat-excludes | Junto con --compat-apply: no añade automáticamente las exclusiones recomendadas |
--native-compat jxbrowser | Solo para javaapp y springboot: solicita la admisión del JxBrowser incluido. La versión, la plataforma y el hash de cinco capas se siguen verificando por completo, y no se aceptan otros valores, rutas ni hashes |
--account-email <email> | Correo electrónico de la cuenta con licencia |
--account-password <password> | Contraseña de la cuenta con licencia |
--app-id <id> | Identificador de la aplicación |
--license-expires-in <sec> | Duración de prueba solicitada, en segundos, dentro de lo que permita la política del servidor |
Los comandos de empaquetado de nivel superior admiten además:
| Opción | Descripción |
|---|---|
--archive-suffix p4jx|jar | Sufijo del archivo generado; por defecto p4jx. No cambia el formato interno |
--jvm-option <option> | Escribe la opción en los scripts de arranque de macOS, Linux y Windows. Una opción por modificador, repetible. Con el EXE de Windows activado, las mismas opciones quedan incrustadas en él |
3. encode
p4j encode input.jar output.p4jx [opciones]
| Opción | Descripción |
|---|---|
--bind-launcher <jar> | Calcula el SHA-256 del JAR del iniciador y lo vincula |
--launcher-sha256 <hex> | Proporciona directamente el SHA-256 del iniciador, para integraciones avanzadas |
--runtime-major <N> | Destino de la vista de recursos y del aplanado multiversión. Por defecto, 21 |
--bind-launcher y --launcher-sha256 no pueden usarse juntas.
4. javaapp
p4j javaapp input.jar directorio-de-salida [opciones]
| Opción | Descripción |
|---|---|
--main <class> | La clase principal con la que arrancar |
--protect <rules> | Reglas de las clases y paquetes que se protegen, separadas por comas. Por defecto, todas las clases |
--exclude <rules> | Reglas de lo que queda fuera del alcance de la protección |
--javafx [<dir>] | Activa JavaFX, opcionalmente desde un directorio local de componentes |
--javafx-webview | Incluye siempre WebView |
--no-javafx-webview | No incluye nunca WebView |
--no-javafx | Desactiva JavaFX de forma explícita |
--native-compat jxbrowser | Escribe ATTACH_THREAD para las bibliotecas IPC de JxBrowser que coinciden exactamente con el directorio incluido. Solo Java 17, 21 y 25 |
5. springboot
p4j springboot input.jar directorio-de-salida [opciones]
| Opción | Descripción |
|---|---|
--main <class> | La clase principal de Spring Boot. Por defecto se lee del manifiesto |
--protect <rules> | Protege las clases coincidentes de BOOT-INF/classes |
--exclude <rules> | Deja sin proteger las clases o paquetes coincidentes |
--protect-lib <globs> | Protege los JAR coincidentes de BOOT-INF/lib, separados por comas |
--layout p4jx-fat|fat|separate | Diseño de la salida; por defecto, p4jx-fat |
--javafx [<dir>] | Activa JavaFX, opcionalmente desde un directorio local de componentes |
--javafx-webview | Incluye siempre WebView |
--no-javafx-webview | No incluye nunca WebView |
--no-javafx | Desactiva JavaFX de forma explícita |
--native-compat jxbrowser | Igual que en javaapp; el mismo escáner cubre el BOOT-INF/lib anidado |
6. tomcat
p4j tomcat input.war directorio-de-salida [opciones]
| Opción | Descripción |
|---|---|
--exclude <rules> | Deja sin proteger las clases o paquetes coincidentes de WEB-INF/classes |
--context </path> | Ruta de contexto; por defecto, /app |
--append-app | Añade la aplicación a un paquete P4JX de Tomcat existente |
--tomcat-version auto|9|10 | Detecta automáticamente o fuerza la versión. En la CLI, por defecto auto |
--precompile-jsp | Fuerza la precompilación de JSP |
--no-precompile-jsp | Desactiva la precompilación de JSP |
7. Opciones del EXE de Windows
javaapp, springboot y tomcat pueden generar además un iniciador nativo de Windows. Las plataformas de destino deben incluir windows-x64, windows-x86 o windows-aarch64.
| Opción | Descripción |
|---|---|
--windows-exe | Genera un EXE de aplicación para Windows. Sin ella no se genera ninguno |
--exe-name <name> | Nombre del archivo EXE; por defecto, el del archivo de entrada, o tomcat en los paquetes de tomcat |
--exe-mode <mode> | console (predeterminado) o gui |
--exe-icon <ico> | Icono de Windows opcional, en formato .ico |
--exe-file-version <a.b.c.d> | Versión de archivo del PE: de uno a cuatro números, cada uno entre 0 y 65535. Vacío equivale a 0.0.0.0 |
--exe-product-version <a.b.c.d> | Versión de producto del PE, con las mismas reglas |
--exe-company <text> | Nombre de la empresa |
--exe-product <text> | Nombre del producto |
--exe-description <text> | Descripción del archivo |
--exe-copyright <text> | Aviso de copyright |
Cualquier opción --exe-* activa por sí sola la generación del EXE. En una tarea con varias plataformas, solo los paquetes de Windows reciben un EXE; los demás se generan igual y conservan sus scripts de arranque.
p4j --target-platform windows-x64 javaapp app.jar dist --windows-exe --exe-name MyApp.exe --exe-mode gui
Las instrucciones completas, el comportamiento en ejecución y los pasos de firma de código están en Crear un iniciador EXE de Windows.
8. Sintaxis de las reglas
com.example.SecretService una sola clase
com.example.service solo este paquete
com.example.service.* solo este paquete
com.example.service.** este paquete y todos sus subpaquetes
com/example/Secret.class ruta de una entrada de clase
Separe varias reglas con comas. Entrecomille las que contengan * para que la shell no las expanda:
--protect 'com.example.**' --exclude 'com.example.dto.**,com.example.config.**'
9. Variables de entorno
Las variables de entorno sirven para valores compartidos en un trabajo de CI, un contenedor o varios comandos seguidos. Cuando necesite que una ejecución concreta quede registrada y sea reproducible, indique los valores de forma explícita como opciones.
| Variable | Opción equivalente | Descripción |
|---|---|---|
P4JX_RUNTIME_JAVA_VERSION | --java-version <N> | La línea de Java para el empaquetado de nivel superior: 8, 11, 17, 21 o 25 |
P4JX_RUNTIME_PLATFORM | --target-platform <id> | Una única plataforma de destino. Para empaquetar varias a la vez, use la opción de línea de comandos |
P4JX_RUNTIME_CACHE_DIR | ninguna | Sustituye el directorio de caché de descargas del VLX JRE |
APP_JAVA_OPTS | compárese con --jvm-option | Añade opciones de la JVM para una ejecución de la aplicación generada. --jvm-option las escribe en el script al empaquetar, así que no son equivalentes |
Si se establecen a la vez una variable y su opción, prevalece la opción indicada de forma explícita. Las variables de entorno siguen plenamente admitidas, así que sus scripts de automatización actuales funcionan sin cambios.
Por ejemplo, para fijar un destino común a varios comandos en la shell actual:
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
Para usos avanzados en los que arranque directamente el JAR del empaquetador, existen las propiedades de sistema equivalentes:
-Dp4jx.runtime.java.version=<N>
-Dp4jx.runtime.platform=<platform>
-Dp4jx.runtime.cache.dir=<dir>
10. Ejemplo de automatización
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
Las opciones de protección, exclusión y diseño indicadas de forma explícita prevalecen sobre las recomendaciones automáticas. Conviene registrar las opciones finales, el SHA-256 del archivo de entrada y la versión de la herramienta como constancia del origen de la publicación.
Los ejemplos para la interfaz y la línea de comandos, y cómo editar run.sh, run.bat, los scripts de arranque de Tomcat y PowerShell, están en Opciones de inicio de la JVM.