CLI 레퍼런스
이 문서의 예제는 설치 후 쓸 수 있는 p4j 명령을 사용합니다. Windows의 GUI는 .exe로, macOS의 GUI는 .dmg 안의 Protector4J.app으로 설치하지만, GUI 설치 방식에 따라 아래 CLI 문법이 달라지지는 않습니다. 설치 프로그램이 CLI를 PATH에 추가하지 않았다면 Protector4J 설치 디렉터리에 있는 명령줄 입구에서 실행하세요.
p4j --help
1. 명령
p4j encode <input.jar> <output.p4jx|output.jar> [옵션]
p4j javaapp <input.jar> <출력 디렉터리> [옵션]
p4j springboot <input.jar> <출력 디렉터리> [옵션]
p4j tomcat <input.war> <출력 디렉터리> [옵션]
하위 수준의 encode는 명령 이름을 생략할 수도 있습니다.
p4j input.jar output.p4jx [옵션]
시작 수준 옵션은 패키징 대상을 고릅니다. 명령 이름 앞에 둘 수도 있고, 명령 전체의 끝에 이어서 둘 수도 있습니다. GUI가 내보내는 명령줄은 끝에 두는 방식을 씁니다.
| 옵션 | 설명 |
|---|---|
--java-version <N> | 함께 넣을 Java 트레인: 8, 11, 17, 21, 25. 기본값은 21 |
--target-platform <id>[,<id>...] | 하나 이상의 대상 플랫폼. 쉼표로 구분하거나 옵션을 반복합니다. 기본값은 현재 플랫폼 |
--create-new-folder | 출력 디렉터리 안에 p4jx-xxxxxxxx 하위 디렉터리를 새로 만듭니다. javaapp, springboot, tomcat에만 해당 |
예:
p4j --java-version 21 --target-platform linux-x64 springboot app.jar dist
p4j springboot app.jar dist --java-version 21 --target-platform linux-x64
두 명령은 같은 뜻입니다. 시작 수준 옵션을 패키저 옵션 사이에 끼워 넣을 수는 없습니다. 그렇게 하면 알 수 없는 패키저 옵션으로 처리되어 오류가 납니다.
2. 공통 옵션
| 옵션 | 설명 |
|---|---|
--jre-home <path> | 지정한 P4JX 최종 JRE 런타임에서 키를 파생합니다. 상위 패키징 명령은 이 런타임도 복사합니다 |
--keys <keys.json> | 명시적인 비공개 키 파일을 씁니다. 진단과 내부 절차 전용이며 애플리케이션과 함께 배포하면 안 됩니다 |
--no-jit | 보호 대상 메서드를 JIT로 넘기지 않고 인터프리터로 실행합니다 |
--zip-overlay off|scanner | 스캐너 ZIP 호환 뷰를 끄거나 켭니다. 기본값은 off |
--compat-scan | 검사만 하고 종료합니다. 출력 인수가 필요 없습니다 |
--compat-apply | 검사한 뒤 보수적인 권장을 적용하고 그대로 인코딩합니다 |
--no-compat-excludes | --compat-apply와 함께 쓰며, 권장되는 제외 규칙을 자동으로 추가하지 않습니다 |
--native-compat jxbrowser | javaapp와 springboot 전용. 내장 JxBrowser의 허용을 요청합니다. 버전, 플랫폼, 5계층 해시는 여전히 완전히 검증되며 다른 값이나 경로, 해시는 받지 않습니다 |
--account-email <email> | 라이선스 계정 이메일 |
--account-password <password> | 라이선스 계정 비밀번호 |
--app-id <id> | 애플리케이션 식별자 |
--license-expires-in <sec> | 요청할 평가 기간(초). 서버 정책의 범위 안에서 적용됩니다 |
상위 패키징 명령에서는 다음도 쓸 수 있습니다.
| 옵션 | 설명 |
|---|---|
--archive-suffix p4jx|jar | 생성할 아카이브의 확장자. 기본값은 p4jx이며 내부 형식은 바뀌지 않습니다 |
--jvm-option <option> | macOS, Linux, Windows의 실행 스크립트에 기록합니다. 옵션마다 한 번씩 쓰며 반복할 수 있습니다. Windows EXE를 쓰면 같은 내용이 EXE에도 들어갑니다 |
3. encode
p4j encode input.jar output.p4jx [옵션]
| 옵션 | 설명 |
|---|---|
--bind-launcher <jar> | 실행기 JAR의 SHA-256을 계산해 묶습니다 |
--launcher-sha256 <hex> | 실행기의 SHA-256을 직접 전달합니다. 고급 연동용 |
--runtime-major <N> | 리소스 뷰와 멀티 릴리스 평탄화의 대상. 기본값은 21 |
--bind-launcher와 --launcher-sha256은 함께 쓸 수 없습니다.
4. javaapp
p4j javaapp input.jar 출력디렉터리 [옵션]
| 옵션 | 설명 |
|---|---|
--main <class> | 시작할 메인 클래스 |
--protect <rules> | 보호할 클래스와 패키지 규칙. 쉼표로 구분하며 기본값은 모든 클래스 |
--exclude <rules> | 보호 범위에서 뺄 규칙 |
--javafx [<dir>] | JavaFX를 사용합니다. 로컬 구성 요소 디렉터리를 지정할 수 있습니다 |
--javafx-webview | 항상 WebView를 포함합니다 |
--no-javafx-webview | WebView를 포함하지 않습니다 |
--no-javafx | JavaFX를 명시적으로 끕니다 |
--native-compat jxbrowser | 내장 디렉터리와 완전히 일치하는 JxBrowser IPC 라이브러리에 ATTACH_THREAD를 기록합니다. Java 17, 21, 25만 지원 |
5. springboot
p4j springboot input.jar 출력디렉터리 [옵션]
| 옵션 | 설명 |
|---|---|
--main <class> | Spring Boot 메인 클래스. 기본적으로 매니페스트에서 읽습니다 |
--protect <rules> | BOOT-INF/classes 안에서 조건에 맞는 클래스를 보호합니다 |
--exclude <rules> | 조건에 맞는 클래스나 패키지를 보호 대상에서 뺍니다 |
--protect-lib <globs> | BOOT-INF/lib 안에서 조건에 맞는 JAR를 보호합니다. 쉼표로 구분 |
--layout p4jx-fat|fat|separate | 출력 레이아웃. 기본값은 p4jx-fat |
--javafx [<dir>] | JavaFX를 사용합니다. 로컬 구성 요소 디렉터리를 지정할 수 있습니다 |
--javafx-webview | 항상 WebView를 포함합니다 |
--no-javafx-webview | WebView를 포함하지 않습니다 |
--no-javafx | JavaFX를 명시적으로 끕니다 |
--native-compat jxbrowser | javaapp와 같습니다. 중첩된 BOOT-INF/lib도 같은 스캐너가 다룹니다 |
6. tomcat
p4j tomcat input.war 출력디렉터리 [옵션]
| 옵션 | 설명 |
|---|---|
--exclude <rules> | WEB-INF/classes 안에서 조건에 맞는 클래스나 패키지를 보호 대상에서 뺍니다 |
--context </path> | 컨텍스트 경로. 기본값은 /app |
--append-app | 기존 P4JX Tomcat 패키지에 애플리케이션을 추가합니다 |
--tomcat-version auto|9|10 | 자동 감지 또는 버전 지정. CLI 기본값은 auto |
--precompile-jsp | JSP를 반드시 미리 컴파일합니다 |
--no-precompile-jsp | JSP 사전 컴파일을 끕니다 |
7. Windows EXE 옵션
javaapp, springboot, tomcat은 네이티브 Windows 실행기를 추가로 만들 수 있습니다. 대상 플랫폼에 windows-x64, windows-x86, windows-aarch64 중 하나가 있어야 합니다.
| 옵션 | 설명 |
|---|---|
--windows-exe | Windows 애플리케이션 EXE를 만듭니다. 지정하지 않으면 만들지 않습니다 |
--exe-name <name> | EXE 파일 이름. 기본값은 입력 파일 이름이며 tomcat 패키지는 tomcat |
--exe-mode <mode> | console (기본값) 또는 gui |
--exe-icon <ico> | 선택 사항인 Windows 아이콘 (.ico 형식) |
--exe-file-version <a.b.c.d> | PE 파일 버전. 10.0.0.0 |
--exe-product-version <a.b.c.d> | PE 제품 버전. 규칙은 같습니다 |
--exe-company <text> | 회사 이름 |
--exe-product <text> | 제품 이름 |
--exe-description <text> | 파일 설명 |
--exe-copyright <text> | 저작권 고지 |
--exe-* 중 하나라도 지정하면 EXE 생성이 자동으로 켜집니다. 여러 플랫폼을 지정한 작업에서는 Windows 패키지에만 EXE가 만들어지고, 나머지 플랫폼은 평소대로 만들어지며 실행 스크립트가 남습니다.
p4j --target-platform windows-x64 javaapp app.jar dist --windows-exe --exe-name MyApp.exe --exe-mode gui
자세한 설명, 실행 동작, 코드 서명 절차는 Windows EXE 실행기 생성을 참고하세요.
8. 규칙 표기
com.example.SecretService 단일 클래스
com.example.service 이 패키지만
com.example.service.* 이 패키지만
com.example.service.** 이 패키지와 모든 하위 패키지
com/example/Secret.class 클래스 항목 경로
여러 규칙은 쉼표로 구분합니다. *가 들어간 규칙은 셸이 확장하지 않도록 따옴표로 감싸세요.
--protect 'com.example.**' --exclude 'com.example.dto.**,com.example.config.**'
9. 환경 변수
환경 변수는 CI 작업, 컨테이너, 연달아 실행하는 여러 명령에 공통 기본값을 줄 때 적합합니다. 어떤 한 번의 패키징을 기록하고 재현해야 한다면 값을 CLI 옵션으로 명시하는 편이 확실합니다.
| 환경 변수 | 대응하는 CLI 옵션 | 설명 |
|---|---|---|
P4JX_RUNTIME_JAVA_VERSION | --java-version <N> | 상위 패키징에서 쓸 Java 트레인: 8, 11, 17, 21, 25 |
P4JX_RUNTIME_PLATFORM | --target-platform <id> | 단일 대상 플랫폼. 여러 플랫폼을 한 번에 패키징하려면 CLI 옵션을 쓰세요 |
P4JX_RUNTIME_CACHE_DIR | 없음 | VLX JRE 다운로드 캐시 디렉터리를 덮어씁니다 |
APP_JAVA_OPTS | --jvm-option과 비교 | 생성된 애플리케이션을 실행할 때 JVM 옵션을 임시로 더합니다. --jvm-option은 패키징 시점에 실행 스크립트에 기록하는 것이라 서로 같지 않습니다 |
환경 변수와 대응하는 CLI 옵션을 모두 설정하면 명시한 CLI 옵션이 우선합니다. 환경 변수는 계속 완전히 지원되므로 기존 자동화 스크립트를 그대로 쓸 수 있습니다.
예를 들어 현재 셸에서 이어지는 여러 패키징 명령에 공통 대상을 설정하려면:
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
패키저 JAR를 직접 실행하는 고급 사용에서는 그에 해당하는 Java 시스템 속성도 쓸 수 있습니다.
-Dp4jx.runtime.java.version=<N>
-Dp4jx.runtime.platform=<platform>
-Dp4jx.runtime.cache.dir=<dir>
10. 자동화 예제
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
직접 지정한 보호, 제외, 레이아웃 옵션은 자동 권장보다 우선합니다. 최종 옵션, 입력 파일의 SHA-256, 도구 버전을 릴리스 이력으로 남겨 두는 것이 좋습니다.
GUI와 CLI 예제, 그리고 run.sh, run.bat, Tomcat 실행 스크립트, Windows PowerShell 편집 방법은 JVM 시작 옵션을 참고하세요.