Referência da linha de comando
Os exemplos desta página usam o comando p4j que a instalação fornece. No Windows a interface gráfica é instalada pelo .exe e no macOS pelo Protector4J.app, dentro do .dmg; a forma de instalação não muda a sintaxe abaixo. Se o instalador não colocou a CLI no PATH, execute-a pelo ponto de entrada de linha de comando da pasta de instalação do Protector4J.
p4j --help
1. Comandos
p4j encode <input.jar> <output.p4jx|output.jar> [opções]
p4j javaapp <input.jar> <pasta de saída> [opções]
p4j springboot <input.jar> <pasta de saída> [opções]
p4j tomcat <input.war> <pasta de saída> [opções]
No encode de baixo nível o nome do comando pode ser omitido:
p4j input.jar output.p4jx [opções]
As opções de nível de inicialização escolhem o alvo do empacotamento. Podem vir antes do nome do comando ou agrupadas no fim da linha; a linha de comando exportada pela interface usa esta segunda forma.
| Opção | Descrição |
|---|---|
--java-version <N> | A linha do Java a incluir: 8, 11, 17, 21 ou 25. Padrão: 21 |
--target-platform <id>[,<id>...] | Uma ou mais plataformas-alvo, separadas por vírgulas ou repetindo a opção. Por padrão, a plataforma atual |
--create-new-folder | Cria uma subpasta p4jx-xxxxxxxx dentro da pasta de saída. Apenas para javaapp, springboot e tomcat |
Por exemplo:
p4j --java-version 21 --target-platform linux-x64 springboot app.jar dist
p4j springboot app.jar dist --java-version 21 --target-platform linux-x64
Os dois comandos são equivalentes. As opções de nível de inicialização não podem ficar no meio das opções do empacotador: ali seriam lidas como opções desconhecidas e o comando falharia.
2. Opções comuns
| Opção | Descrição |
|---|---|
--jre-home <path> | Deriva as chaves do tempo de execução P4JX final indicado. Os comandos de nível mais alto também copiam esse tempo de execução |
--keys <keys.json> | Usa um arquivo de chaves privadas explícito. Só para diagnóstico e processos internos; nunca distribua com o aplicativo |
--no-jit | Mantém os métodos protegidos fora do JIT e os executa no interpretador |
--zip-overlay off|scanner | Desliga ou liga a visão de compatibilidade ZIP para scanners. Padrão: off |
--compat-scan | Examina e encerra; não é preciso argumento de saída |
--compat-apply | Examina, aplica as recomendações conservadoras e segue com a codificação |
--no-compat-excludes | Junto com --compat-apply: não acrescenta automaticamente as exclusões recomendadas |
--native-compat jxbrowser | Só para javaapp e springboot: solicita a admissão do JxBrowser embutido. A versão, a plataforma e o hash de cinco camadas continuam sendo verificados por inteiro, e nenhum outro valor, caminho ou hash é aceito |
--account-email <email> | E-mail da conta licenciada |
--account-password <password> | Senha da conta licenciada |
--app-id <id> | Identificador do aplicativo |
--license-expires-in <sec> | Duração de avaliação pedida, em segundos, dentro do que a política do servidor permitir |
Os comandos de empacotamento de nível mais alto aceitam ainda:
| Opção | Descrição |
|---|---|
--archive-suffix p4jx|jar | Sufixo do arquivo gerado; padrão p4jx. O formato interno não muda |
--jvm-option <option> | Grava a opção nos scripts de inicialização de macOS, Linux e Windows. Uma opção por parâmetro, repetível. Com o EXE do Windows ativado, as mesmas opções ficam embutidas nele |
3. encode
p4j encode input.jar output.p4jx [opções]
| Opção | Descrição |
|---|---|
--bind-launcher <jar> | Calcula o SHA-256 do JAR do iniciador e o vincula |
--launcher-sha256 <hex> | Informa diretamente o SHA-256 do iniciador, para integrações avançadas |
--runtime-major <N> | Alvo da visão de recursos e do achatamento multiversão. Padrão: 21 |
--bind-launcher e --launcher-sha256 não podem ser usadas juntas.
4. javaapp
p4j javaapp input.jar pasta-de-saída [opções]
| Opção | Descrição |
|---|---|
--main <class> | A classe principal a iniciar |
--protect <rules> | Regras das classes e pacotes a proteger, separadas por vírgulas. Por padrão, todas as classes |
--exclude <rules> | Regras do que fica fora do alcance da proteção |
--javafx [<dir>] | Ativa o JavaFX, opcionalmente a partir de uma pasta local de componentes |
--javafx-webview | Sempre inclui o WebView |
--no-javafx-webview | Nunca inclui o WebView |
--no-javafx | Desativa o JavaFX explicitamente |
--native-compat jxbrowser | Grava ATTACH_THREAD para as bibliotecas IPC do JxBrowser que correspondem exatamente à pasta embutida. Apenas Java 17, 21 e 25 |
5. springboot
p4j springboot input.jar pasta-de-saída [opções]
| Opção | Descrição |
|---|---|
--main <class> | A classe principal do Spring Boot. Por padrão, lida do manifesto |
--protect <rules> | Protege as classes correspondentes em BOOT-INF/classes |
--exclude <rules> | Deixa sem proteção as classes ou pacotes correspondentes |
--protect-lib <globs> | Protege os JAR correspondentes em BOOT-INF/lib, separados por vírgulas |
--layout p4jx-fat|fat|separate | Disposição da saída; padrão p4jx-fat |
--javafx [<dir>] | Ativa o JavaFX, opcionalmente a partir de uma pasta local de componentes |
--javafx-webview | Sempre inclui o WebView |
--no-javafx-webview | Nunca inclui o WebView |
--no-javafx | Desativa o JavaFX explicitamente |
--native-compat jxbrowser | Como em javaapp; o mesmo scanner cobre o BOOT-INF/lib aninhado |
6. tomcat
p4j tomcat input.war pasta-de-saída [opções]
| Opção | Descrição |
|---|---|
--exclude <rules> | Deixa sem proteção as classes ou pacotes correspondentes em WEB-INF/classes |
--context </path> | Caminho de contexto; padrão /app |
--append-app | Acrescenta o aplicativo a um pacote Tomcat P4JX existente |
--tomcat-version auto|9|10 | Detecta automaticamente ou fixa a versão. Na linha de comando, auto por padrão |
--precompile-jsp | Força a pré-compilação de JSP |
--no-precompile-jsp | Desliga a pré-compilação de JSP |
7. Opções do EXE do Windows
javaapp, springboot e tomcat podem gerar também um iniciador nativo do Windows. As plataformas-alvo precisam incluir windows-x64, windows-x86 ou windows-aarch64.
| Opção | Descrição |
|---|---|
--windows-exe | Gera um EXE de aplicação para Windows. Sem ela, nenhum é gerado |
--exe-name <name> | Nome do arquivo EXE; por padrão o do arquivo de entrada, ou tomcat nos pacotes tomcat |
--exe-mode <mode> | console (padrão) ou gui |
--exe-icon <ico> | Ícone do Windows opcional, no formato .ico |
--exe-file-version <a.b.c.d> | Versão de arquivo do PE: de um a quatro números, cada um entre 0 e 65535. Em branco equivale a 0.0.0.0 |
--exe-product-version <a.b.c.d> | Versão de produto do PE, com as mesmas regras |
--exe-company <text> | Nome da empresa |
--exe-product <text> | Nome do produto |
--exe-description <text> | Descrição do arquivo |
--exe-copyright <text> | Aviso de direitos autorais |
Qualquer opção --exe-* já ativa a geração do EXE por si só. Numa tarefa com várias plataformas, só os pacotes do Windows recebem um EXE; os demais são gerados normalmente e mantêm seus scripts de inicialização.
p4j --target-platform windows-x64 javaapp app.jar dist --windows-exe --exe-name MyApp.exe --exe-mode gui
As instruções completas, o comportamento em execução e os passos de assinatura de código estão em Criar um iniciador EXE do Windows.
8. Sintaxe das regras
com.example.SecretService uma única classe
com.example.service somente este pacote
com.example.service.* somente este pacote
com.example.service.** este pacote e todos os subpacotes
com/example/Secret.class caminho de uma entrada de classe
Separe várias regras por vírgulas. Coloque entre aspas as que tiverem *, para o shell não expandi-las:
--protect 'com.example.**' --exclude 'com.example.dto.**,com.example.config.**'
9. Variáveis de ambiente
As variáveis de ambiente servem para valores comuns num job de CI, num contêiner ou em vários comandos executados em sequência. Quando um empacotamento específico precisa ficar registrado e ser reproduzível, informe os valores explicitamente como opções.
| Variável | Opção equivalente | Descrição |
|---|---|---|
P4JX_RUNTIME_JAVA_VERSION | --java-version <N> | A linha do Java para o empacotamento de nível mais alto: 8, 11, 17, 21 ou 25 |
P4JX_RUNTIME_PLATFORM | --target-platform <id> | Uma única plataforma-alvo. Para empacotar várias de uma vez, use a opção de linha de comando |
P4JX_RUNTIME_CACHE_DIR | nenhuma | Substitui a pasta de cache dos downloads do VLX JRE |
APP_JAVA_OPTS | compare com --jvm-option | Acrescenta opções da JVM numa execução do aplicativo gerado. --jvm-option as grava no script durante o empacotamento, então as duas não são equivalentes |
Se uma variável e a opção correspondente estiverem definidas, prevalece a opção informada explicitamente. As variáveis de ambiente continuam plenamente suportadas, de modo que os seus scripts de automação atuais seguem funcionando.
Por exemplo, para fixar um alvo comum a vários comandos no shell atual:
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 avançados em que você inicia diretamente o JAR do empacotador, existem as propriedades de sistema equivalentes:
-Dp4jx.runtime.java.version=<N>
-Dp4jx.runtime.platform=<platform>
-Dp4jx.runtime.cache.dir=<dir>
10. Exemplo de automação
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
As opções de proteção, exclusão e disposição informadas explicitamente prevalecem sobre as recomendações automáticas. Convém registrar as opções finais, o SHA-256 do arquivo de entrada e a versão da ferramenta como prova da origem da publicação.
Os exemplos para a interface e a linha de comando, e como editar run.sh, run.bat, os scripts de inicialização do Tomcat e o PowerShell, estão em Opções de inicialização JVM.