[Spring boot] Gradle Toolchains (1/3)

Java Toolchains 개념과 프로젝트 설정

---

Gradle 6.7부터 도입된 Java Toolchain 기능은, 여러 Java 버전을 다루는 프로젝트에서 빌드 환경을 일관되게 유지하고 예기치 않은 오류를 방지하기 위해 사용됩니다.

 

🧩 Java Toolchain이란?

---

여러 프로젝트에서 동시에 작업하거나, 하나의 프로젝트 내에서도 하위 모듈별로 서로 다른 Java 언어 수준을 요구하는 경우가 있습니다. 이는 하위 호환성 등의 이유로 코드베이스의 일부가 특정 Java 버전에 고정되어야 하기 때문입니다.

이러한 상황에서는 빌드 머신마다 여러 버전의 동일한 도구(즉, Toolchain)를 설치하고 관리해야 합니다.

Java Toolchain은 Java 프로젝트를 빌드하고 실행하는 데 필요한 도구들의 집합이며, 일반적으로 로컬 JRE 또는 JDK 설치를 통해 환경에 제공됩니다.

• 컴파일 작업: javac 사용
• 테스트/실행 작업: java 명령어 사용
• 문서화 작업: javadoc 사용

 

⚙️ Gradle의 기본 동작

---

Gradle은 기본적으로 Gradle 자체를 실행할 때 사용하는 Java toolchian 과, JVM 프로젝트를 빌드할 때 사용하는 toolchian 을 동일하게 설정합니다.

그러나 이 방식이 항상 이상적인 것은 아닙니다. 다음과 같은 문제가 발생할 수 있습니다:

• 서로 다른 Java 버전으로 프로젝트를 빌드해야 할 때, 개발자 환경 및 CI 서버에서 예기치 않은 문제가 생김
• Gradle 실행은 특정 Java 버전을 요구하나, 프로젝트는 다른 Java 버전에서 빌드되어야 할 때 충돌 발생

 

🧭 해결: Toolchian 설정

---

Gradle은 프로젝트 단위와 작업(Task) 단위 모두에서 toolchian 을 설정할 수 있도록 지원합니다.
또한 Gradle 자체가 실행되는 JVM도 Daemon JVM 기준을 사용하여 제어할 수 있습니다.

이 기능은 빌드의 재현성을 높이고, 빌드 요구사항을 명확하게 문서화하는 데 유리합니다.

 

📦 프로젝트용 Toolchain 설정 방법

---

Gradle은 Java 프로젝트의 컴파일과 실행에 사용할 Java 버전을 설정하는 여러 방법을 제공합니다.
다섯 가지 주요 메커니즘은 다음과 같습니다:

1. Java Toolchains (toolchain 블록)
2. --release 플래그
3. sourceCompatibility, targetCompatibility
4. 환경 변수 JAVA_HOME
5. IDE 설정

이 설정들은 상호 배타적이지 않으며, 특정 상황에서는 함께 사용해야 할 수도 있습니다.

 

1. toolchain 사용

Java 언어 버전을 명시하려면 java 확장 블록에 다음과 같이 설정합니다:

java {
  toolchain {
    languageVersion = JavaLanguageVersion.of(17)
  }
}

해당 java 블록은 다른 구성 옵션들도 유연하게 지원합니다.

 

2. --release 플래그

보다 엄격한 크로스 컴파일을 위해 sourceCompatibility와 targetCompatibility 대신 --release 플래그 사용을 권장합니다:

tasks.withType(JavaCompile).configureEach {
  options.release = 8
}

• 이 플래그는 지정된 버전에서 제공되지 않는 새로운 API를 실수로 사용하는 것을 방지합니다.
• 단, 어떤 JDK를 사용할지 제어하진 않습니다.

필요한 경우 toolchian 과 --release를 함께 사용할 수 있습니다.

 

3. 소스 및 타겟 호환성

sourceCompatibility와 targetCompatibility는 컴파일러에 특정 Java 버전 호환 바이트코드를 생성하도록 지시하지만, Gradle이 사용하는 JDK에는 영향을 주지 않습니다:

java {
  sourceCompatibility = JavaVersion.VERSION_1_8
  targetCompatibility = JavaVersion.VERSION_1_8
}

이 방식은 JDK가 올바르게 선택된다는 보장이 없으며, 구버전 Java로 백포팅된 API가 있는 경우 문제를 유발할 수 있습니다.

 

4. 환경 변수 JAVA_HOME

시스템에 기본 JDK를 설정하려면 환경 변수 JAVA_HOME을 사용할 수 있습니다:

export JAVA_HOME=/path/to/java17

• 이는 Gradle, Maven을 포함한 모든 Java 도구에 적용됩니다.
• 단, toolchain 설정이나 프로젝트별 구성보다 우선되지 않습니다.

toolchian 을 사용하지 않는 레거시 프로젝트에 적합합니다.
하지만 프로젝트마다 다른 JDK가 필요한 경우에는 적절하지 않으며, 그럴 경우 toolchain을 사용하는 것이 더 좋습니다.

 

5. IDE 설정

대부분의 현대 IDE는 Gradle을 실행하는 데 사용할 JVM을 설정할 수 있습니다.
이는 Gradle 자체의 실행 JVM에 영향을 줄 뿐, 빌드가 어떤 JDK로 컴파일되는지는 빌드 스크립트의 설정에 따릅니다.

• toolchian 이 정의되어 있지 않다면, IDE에서 설정한 Java 버전이 사용될 수 있습니다.
• 이는 의도하지 않은 비재현성 문제로 이어질 수 있습니다.

📌 추천: IDE의 Gradle JVM 설정을 명령줄 JAVA_HOME 또는 시스템 기본 Java와 일치시켜 환경 간 일관성을 유지하세요.

 

🧮 설정 방식 비교표

---

설정 방법	JDK 정확성 보장	JDK 자동 다운로드	새로운 API 실수 방지
toolchain	✅	✅	❌
--release	❌	❌	✅
sourceCompatibility 등	❌	❌	❌
환경 변수 JAVA_HOME	✅ (글로벌)	❌	❌
IDE 설정	✅ (IDE 한정)	❌	❌

 

🔁 Toolchian 결합 사용 예시

---

특정 JDK를 사용하면서, 구버전과의 호환성도 확보해야 한다면 toolchain과 --release를 함께 사용할 수 있습니다:

java {
  toolchain {
    languageVersion = JavaLanguageVersion.of(17)
  }
}

tasks.withType(JavaCompile).configureEach {
  options.release = 11
}

위 설정은 Java 17을 사용해 컴파일하면서, Java 11과 호환되는 바이트코드를 생성합니다.

 

 

👉 다음 글(2/3)에서는 작업(Task) 단위의 Toolchain 설정과 고급 사용 방법(벤더 필터링, GraalVM 지원 등)에 대해 다룹니다.

 

관련 문서

---

Toolchains for JVM projects