Generación de un iniciador EXE para Windows

Al empacar, se puede generar un iniciador nativo de Windows para la aplicación protegida. Se trata de un archivo ejecutable puramente Win32 que permite ejecutar la aplicación con un doble clic; no es necesario que el usuario instale Java ni que vea run.bat.

El formato EXE es opcional y no se genera por defecto. Al activarlo, el paquete resultante mantiene los archivos run.sh / run.command / run.bat originales, y ambas formas de inicio utilizan exactamente los mismos archivos de archivado, classpath, clase principal y parámetros de JVM.

1. Ámbito de aplicación

Es necesario seleccionar al menos una plataforma de destino Windows. Seleccionar simultáneamente plataformas Linux o macOS no causará fallo en la tarea: los subpaquetes para estas plataformas se generarán como de costumbre, pero sin archivos EXE, utilizando aún los scripts de inicio originales. Si ninguna de las plataformas de destino es Windows, la tarea generará un error inmediato.

2. Operaciones GUI

1. En la página para seleccionar el archivo de entrada y la plataforma de destino, marque Generar archivos EXE de aplicaciones para Windows (x64/x86/ARM64) y elija al menos una plataforma de destino Windows.
2. Este interruptor se encuentra antes de la división entre el modo simple y el modo avanzado, por lo que ambos modos pueden generar archivos EXE.
3. Al marcarlo, aparecerá una página adicional Iniciador de Windows EXE para ingresar el nombre del archivo, el modo del iniciador, el ícono e información sobre la versión de Windows. Si no se marca, se pasa directamente a la página de confirmación final.
4. Al habilitar el EXE, el campo de entrada Parámetros de inicio de la JVM solo aparece en esta página de iniciador, evitando que existan dos entradas para el mismo parámetro. Los parámetros ingresados se escriben tanto en el EXE como en el script de inicio.
5. La página de confirmación final muestra las plataformas en las que realmente se generará el EXE, así como los campos del iniciador que se han completado.

3. Ejemplo de CLI

Forma simplificada, solo se necesita --windows-exe:

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

Se especifica el nombre del archivo y el modo de ventana:

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

Se generan tres arquitecturas de Windows a la vez, completando además los recursos de la versión:

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.'

El paquete Tomcat también es compatible; el EXE generado inicia Tomcat incrustado en modo de interfaz principal:

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

4. Descripción de los parámetros

Cualquiera de las opciones --exe-* activará automáticamente la generación del EXE; no es necesario escribir --windows-exe por separado.

El nombre del archivo debe ser únicamente un nombre, sin incluir /, \ ni partes de directorio; si no hay el sufijo .exe, se agrega automáticamente.

Las reglas para los dos campos de versión son las mismas: dígitos separados por puntos y coma, de 1 a 4 segmentos, con un rango de 0 a 65535 para cada segmento, por ejemplo 1.0.0.1. Windows almacena cada segmento como un entero sin signo de 16 bits, por lo que no acepta formatos con letras o espacios como v1.0 o 1.0-beta. Dejarlo en blanco significa 0.0.0.0. Estos dos campos se verifican antes de comenzar el empaquetado, por lo que no habrá errores hasta ese momento.

5. Estructura de salida

Tomando como ejemplo una Java Application, el EXE y el script de inicio se encuentran juntos en el directorio raíz del paquete:

dist/
├── MyApp.exe             # El iniciador Windows recién añadido
├── app.p4jx
├── vlxjre/
├── lib/
├── run.sh
├── run.command
├── run.bat
└── README.md

README.md dentro del paquete muestra el nombre del archivo EXE generado e incluye una indicación sobre la firma de código.

6. Comportamiento al ejecutar

El directorio donde se encuentra el EXE es el directorio raíz de la aplicación. El iniciador solo acepta los directorios de tiempo de ejecución, archivado, classpath y trabajo que estén dentro del directorio raíz; las rutas que apunten fuera del paquete, así como aquellas reemplazadas por enlaces simbólicos o puntos de conexión, serán rechazadas y el proceso no se iniciará. Esto significa que se puede mover o renombrar todo el paquete, pero no se puede copiar el EXE por separado para usarlo.

Los parámetros JVM del EXE se fijan durante el empaquetado y se firman junto con el bloque de parámetros; se verifican en tiempo de ejecución y no se pueden modificar después del despliegue. APP_JAVA_OPTS solo es válido para run.bat, ya que el EXE no lo lee. Si es necesario cambiar los parámetros JVM del EXE, se debe volver a empaquetar.

Por la misma razón, no se permite escribir parámetros de inicio en el EXE con -javaagent, -agentlib, -agentpath, -Xbootclasspath y --patch-module. Al introducir estos parámetros mediante --jvm-option, el empaquetado fallará directamente.

7. Firmado de código

Protector4J no agrega una firma del editor al EXE generado, ni accede a ninguna credencial Authenticode. Todas las modificaciones en el formato PE, como los iconos, los recursos de versión y los parámetros de inicio, se realizan durante la fase de empaquetado; por lo tanto, el paso de firma debe realizarse al final.

1. Finalizar el empaquetado y verificar que el EXE pueda iniciar la aplicación correctamente.
2. Realizar la firma Authenticode con su propio certificado e incluir un sello de tiempo RFC3161.
3. Verificar la firma utilizando la política /pa de Windows.

Una vez completada la firma, no modifique este archivo PE; cualquier cambio invalidará la firma. Si es necesario cambiar el ícono o el número de versión, por favor, reempaquete el archivo y vuelva a firmarlo.

8. Campos del archivo de tarea

El p4j-task.yml exportado utiliza la versión 2; al habilitar el formato EXE, se guardarán los siguientes campos. Los archivos de tarea de la versión 1 siguen pudiéndose leer sin problemas.

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. Preguntas frecuentes

Para ver las opciones completas de la CLI, consulte Referencia de parámetros de la CLI; para el proceso del asistente gráfico, consulte Guía de uso de la GUI.