Java 프로그램 배포하기

Maven 설치 

WiX Toolset 설치 

빌드 설정 - pom.xml

JAR 파일 생성 - mvn clean package

앱이름-0.0.1-jar-with-dependencies.jar

App.jar 로 이름 변경

JAR 실행 테스트 (run.bat)

Installer에 포함할 파일 준비

App.jar

lib

icon.ico

Installer 파일 생성 (install.bat)

jpackage

자바 배포용 패키지 생성 프로그램

•

Java 런타임(JRE)을 포함하여 독립 실행형 애플리케이션 생성 가능

•

.msi 또는 .exe 설치 파일 등으로 배포 가능

•

아이콘, 이름, 버전, 라이선스 등도 지정 가능

•

JavaFX 앱 배포 시 특히 유용

기본 예시

jpackage ^
  --type exe ^
  --name MyApp ^
  --input . ^
  --main-jar App.jar ^
  --main-class com.aloha.Main ^
  --icon icon.ico ^
  --win-dir-chooser ^
  --win-menu ^
  --win-shortcut
Bash
복사

주요 옵션

옵션	설명
--type <형식>	패키지 형식을 지정. 예: app-image (앱 이미지), exe (윈도우 실행 파일)
--name <name>	실행파일 또는 앱 이미지의 이름을 지정
--input <jar 파일 경로>	jar 파일의 위치를 지정. 상대 경로 또는 절대 경로 가능
--main-jar <jar 파일명>	Main 클래스를 가지고 있는 jar 파일 명을 지정
--dest <경로명>	설치파일 또는 앱 이미지가 저장될 위치를 지정 (또는 -d로 간단히 사용 가능)
--java-options <옵션>	JVM 옵션을 지정. 예: -Dfile.encoding=UTF-8 (한글 깨짐 방지)
--icon <아이콘 이름>	아이콘 파일의 이름을 상대적 또는 절대적 위치로 지정
--description <앱 설명>	앱에 대한 설명을 입력. 예: "Application to verify truth of personal custom ID"
--win-console	명령 프롬프트 창을 보여주며 실행 (디버깅용, 배포 시 불필요)
--app-version <버전>	앱 버전을 지정. 동일한 버전이 생성되면 에러 발생
--install-dir <폴더명>	실행파일이 만들어질 위치를 지정. 예: Program Files 또는 AppData 폴더의 하위 폴더
--win-shortcut	바탕화면에 바로가기를 생성

jpackage 명령어의 주요 옵션들을 정리한 것으로, 패키징 작업을 할 때 유용하게 사용할 수 있습니다.

Maven 설치

Maven

Java 기반의 프로젝트 빌드, 의존성 관리, 배포, 테스트 등을 도와주는 프로젝트 관리 도구

•

의존성 관리 (의존 라이브러리 관리)

•

빌드 자동화

◦

컴파일

◦

테스트

◦

패키징

다운로드

(Windows) apache-maven-3.9.9-bin.zip

Download Apache Maven – Maven

Apache Maven 3.9.9 is the latest release: it is the recommended version for all users.

https://maven.apache.org/download.cgi

시스템 환경 변수 추가

시스템 환경 변수 편집

PATH

C:\~\SETUP\apache-maven-3.9.9\bin

WiX Toolset 설치

WiX Toolset

Windows용 설치 프로그램(.msi 파일 등)을 만들 수 있게 해주는 오픈 소스 도구 모음입니다.

다운로드

wix3141rtm

wix314-binaries.zip 파일을 다운로드 받아 압축해제합니다.

시스템 환경변수

시스템 환경변수

PATH

C:\~\wix314-binaries

압축 해제한 폴더를 시스템 환경 변수 패스에 추가해주세요

빌드 설정 - pom.xml

pom.xml (JavaFX 프로그램)

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.aloha</groupId>            <!-- 조직ID -->
    <artifactId>test</artifactId>           <!-- 프로젝트ID -->
    <version>0.0.1</version>                <!-- 프로젝트 버전 -->
    <!-- 속성 -->
    <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <maven.compiler.source>23</maven.compiler.source>
        <maven.compiler.target>23</maven.compiler.target>
        <jdk.version>23</jdk.version>           <!-- JDK 버전 -->
        <javafx.version>23</javafx.version>     <!-- JavaFX 버전 -->
    </properties>
    <!-- 의존성 라이브러리 -->
    <dependencies>
        <!-- javaFX -->
        <dependency>
            <groupId>org.openjfx</groupId>
            <artifactId>javafx-controls</artifactId>
            <version>${javafx.version}</version>
        </dependency>
        <dependency>
            <groupId>org.openjfx</groupId>
            <artifactId>javafx-fxml</artifactId>
            <version>${javafx.version}</version>
        </dependency>
        <!-- lombok -->
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <version>1.18.30</version>
            <scope>provided</scope>
        </dependency>
        <!-- MySQL -->
        <dependency>
            <groupId>com.mysql</groupId>
            <artifactId>mysql-connector-j</artifactId>
            <version>8.0.32</version>
        </dependency>

    </dependencies>
    <build>
        <plugins>
            <!-- Java 컴파일러 -->
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.8.0</version>
                <configuration>
                    <release>${jdk.version}</release>
                    <annotationProcessorPaths>
                        <path>
                            <groupId>org.projectlombok</groupId>
                            <artifactId>lombok</artifactId>
                            <version>1.18.30</version>
                        </path>
                    </annotationProcessorPaths>
                </configuration>
            </plugin>
            <!-- JavaFX 실행 -->
            <plugin>
                <groupId>org.openjfx</groupId>
                <artifactId>javafx-maven-plugin</artifactId>
                <version>0.0.6</version>
                <executions>
                    <execution>
                        <id>default-cli</id>
                        <configuration>
                            <mainClass>com.aloha.Main</mainClass>
                        </configuration>
                    </execution>
                </executions>
            </plugin>

            <!-- JAR 생성 -->
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-jar-plugin</artifactId>
                <version>3.2.0</version>
                <configuration>
                    <archive>
                        <manifestEntries>
                            <Main-Class>com.aloha.Main</Main-Class> 
                        </manifestEntries>
                    </archive>
                </configuration>
            </plugin>

            <!-- 라이브러리 포함 fat JAR 생성 -->
            <plugin>
                <artifactId>maven-assembly-plugin</artifactId>
                <version>3.6.0</version>
                <configuration>
                    <descriptorRefs>
                        <descriptorRef>jar-with-dependencies</descriptorRef>
                    </descriptorRefs>
                    <archive>
                        <manifest>
                            <mainClass>com.aloha.Main</mainClass>
                        </manifest>
                    </archive>
                </configuration>
                <executions>
                    <execution>
                        <id>make-assembly</id>
                        <phase>package</phase>
                        <goals>
                            <goal>single</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>

        </plugins>
    </build>
</project>
XML
복사

JAR 파일 생성 - mvn clean package

•

앱이름-0.0.1-jar-with-dependencies.jar

mvn clean package 명령어로 JAR 파일을 생성합니다.

mvn clean package
Bash
복사

mvn 주요 명령어

명령어	설명
mvn clean	이전 빌드 결과(target 디렉토리)를 삭제
mvn package	컴파일 + 테스트 후 JAR/WAR 파일로 패키징
mvn compile	src/main/java 코드 컴파일
mvn test	src/test/java에 있는 테스트 코드 실행
mvn install	패키징한 파일을 로컬 Maven 저장소에 설치 (~/.m2/repository)
mvn deploy	원격 Maven 저장소로 업로드 (CI/CD용)
mvn validate	pom.xml 파일 구조와 설정 확인
mvn verify	테스트 및 통합 검사까지 확인
mvn site	프로젝트 정보를 HTML 형태의 리포트로 생성
mvn dependency:tree	의존성 트리를 계층 구조로 출력
mvn dependency:list	프로젝트에 포함된 모든 의존성 나열
mvn archetype:generate	Maven 템플릿(archetype) 기반으로 새 프로젝트 생성
mvn help:effective-pom	실제로 적용되는 POM 설정 출력 (상속/프로파일 포함)
mvn versions:display-dependency-updates	업데이트 가능한 라이브러리 버전 확인 (추가 플러그인 필요)

App.jar 로 이름 변경

JAR 실행 테스트 (run.bat)

java -jar App.jar
Bash
복사

JavaFX 의 경우 라이브러리 및 모듈과 함께 실행되어야하는 경우가 있다.

JavaFX 라이브러리

•

javaFX SDK

•

javaFX jmods

GluonJavaFX - Gluon

JavaFX - Gluon

Roadmap Release GA Date Latest version Minimum JDK Long Term Support Extended or custom support Details 25 September 2025 early access 22 no 24 March 2025 24.0.1 (April 2025) 22 no upon request details 23 September 2024 23.0.2 (January 2025) 21 no upon request details 22 March 2024 22.0.2 (July 2024) 17 no upon request […]

https://gluonhq.com/products/javafx/

javaw --module-path "lib\javafx-sdk-23.0.2\lib" --add-modules javafx.controls,javafx.fxml -jar App.jar
Bash
복사

이렇게 코드를 작성해서 lib 모듈을 포함하여 자바 프로그램을 실행해야 JavaFX 프로그램을 정상 작동시킬 수 있다.

이 명령어를 쉽게 실행시키지 위해서 배치 프로그램 run.bat 을 만들어보자.

@echo off

REM JavaFX 라이브러리 경로 설정
set FX_LIB=lib\javafx-sdk-23.0.2\lib

REM JavaFX 애플리케이션 실행
start javaw --module-path "%FX_LIB%" ^
     --add-modules javafx.controls,javafx.fxml ^
     -jar App.jar

exit
Bash
복사

Installer 에 포함할 파일 준비

📦 install
├── 📜 App.jar
├── 📜 icon.ico
└── 📁 lib
Bash
복사

graph TD
    install["📦 install"]
    install --> App["📜 App.jar"]
    install --> Icon["📜 icon.ico"]
    install --> lib["📁 lib"]
Mermaid
복사

Installer로 설치 되어야 할 파일을 준비해주세요!

Installer 를 통해 프로그램이 설치 되면 아래와 같은 경로에 프로그램이 생성됩니다.

C:\Program Files\MyApp\
├── app\
│   ├── App.jar
│   ├── icon.ico
│   └── lib\
│       ├── javafx-base-21.0.2.jar
│       └── javafx-controls-21.0.2.jar
├── MyApp.exe
├── runtime\
│   └── (사용된 JDK 모듈)
Markdown
복사

이 때, MyApp.exe 프로그램을 실행하면 app 폴더 아래 App.jar 를 실행하여 자바 프로그램을 실행시켜 줍니다.

디렉토리/파일	설명
app/	사용자가 지정한 JAR 파일, 리소스, 라이브러리 파일들이 저장되는 디렉토리
MyApp.exe	Windows 실행 파일 (바탕화면/시작메뉴 바로가기의 대상)
runtime/	모듈화된 JDK 런타임 환경 (jlink로 생성된 최소 JRE)

Installer 파일 생성 (install.bat)

jpackage ^
  --type exe ^
  --input . ^
  --name App ^
  --main-jar App.jar ^
  --main-class com.aloha.Main ^
  --java-options "--module-path app/lib/javafx-sdk-23.0.2/lib --add-modules javafx.controls,javafx.fxml -Xmx512m -Djava.awt.headless=false" ^
  --icon icon.ico ^
  --win-dir-chooser ^
  --win-menu ^
  --win-shortcut
Bash
복사

MyApp.exe 실행하일 기준 module-path 를 지정해주어야합니다.

--module-path app/lib/javafx-sdk-23.0.2/lib
Bash
복사

설치된 파일들은 app 폴더 아래 포함되기 때문에 MyApp.exe 기준에서 app 폴더 아래의 lib 를 참조하도록 지정합니다.

Installer 를 생성하는 배치 프로그램을 만들어 보자.

•

 install.bat

@echo off
setlocal

echo [INFO] Creating installer for App...

jpackage ^
  --type exe ^
  --input . ^
  --name MyApp ^
  --main-jar App.jar ^
  --main-class com.aloha.Main ^
  --java-options "--module-path app/lib/javafx-sdk-23.0.2/lib --add-modules javafx.controls,javafx.fxml -Xmx512m -Djava.awt.headless=false" ^
  --icon icon.ico ^
  --win-dir-chooser ^
  --win-menu ^
  --win-shortcut

echo [INFO] Installer build complete.

pause
Bash
복사