gradle-examples/doc/02_Gradle 프로젝트 구조와 설정 파일.md

Gradle 프로젝트

Gradle을 사용하면 프로젝트의 빌드 과정을 자동화할 수 있으며, 프로젝트의 크기와 복잡도에 따라 다양한 방식으로 구성할 수 있다.

Gradle 프로젝트란?

Gradle에서 프로젝트(Project)는 빌드가 수행되는 단위를 의미한다. 하나의 프로젝트는 애플리케이션, 라이브러리 또는 다른 빌드 가능한 항목일 수 있으며, 여러 개의 프로젝트를 포함하는 멀티 프로젝트 구조도 가능하다.

다음 명령을 사용해서 Gradle 프로젝트를 시작할 수 있다.

mkdir my-project
cd my-project
gradle init --type java-application  --dsl kotlin 

Gradle 래퍼를 사용해서 빌드 명령을 수행하는 예시이다.

./gradlew build

Gradle 프로젝트 구조

Gradle 프로젝트는 일반적으로 다음과 같은 구조를 가진다.

my-project/
├── app
│   ├── build.gradle.kts # 빌드 설정 파일 (Kotlin DSL)
│   └── src # 소스 코드 디렉터리
│       ├── main # 애플리케이션 코드
│       │   ├── java # Java 소스 코드
│       │   │   └── org
│       │   │       └── example
│       │   │           └── App.java
│       │   └── resources # 설정 파일 및 기타 리소스
│       └── test # 테스트 코드
│           ├── java # Java 테스트 코드
│           │   └── org
│           │       └── example
│           │           └── AppTest.java
│           └── resources # 테스트 관련 리소스
├── gradle
│   ├── libs.versions.toml # 버전 카탈로그 파일
│   └── wrapper
│       ├── gradle-wrapper.jar
│       └── gradle-wrapper.properties
├── gradle.properties # 프로젝트 전역 설정 파일
├── gradlew # Gradle Wrapper 실행 파일 (Linux/macOS)
├── gradlew.bat # Gradle Wrapper 실행 파일 (Windows)
├── settings.gradle.kts # 프로젝트 설정 파일

각 파일과 디렉터리의 역할을 살펴보자.

• src/main/java : 애플리케이션의 주요 소스 코드가 위치하는 곳.
• src/main/resources: 애플리케이션 실행에 필요한 설정 파일 또는 기타 리소스 파일을 포함한다.
• src/test/java : 테스트 코드가 위치하는 곳.
• build/: Gradle이 빌드한 결과물이 저장되는 디렉터리로, 컴파일된 클래스 파일과 패키징된 JAR 파일 등이 여기에 생성된다.
• gradle/: Gradle Wrapper 관련 파일이 저장되는 곳.
• gradlew, gradlew.bat: Gradle Wrapper 실행 파일로, 프로젝트에서 지정된 Gradle 버전을 사용할 수 있도록 도와준다.

설정 파일과 빌드 파일

Gradle 프로젝트에는 settings.gradle.kts와 build.gradle.kts라는 두 개의 주요 설정 파일이 있다.

settings.gradle.kts: 프로젝트 설정 파일

이 파일은 프로젝트의 전반적인 설정을 담당하며, 멀티 모듈 프로젝트를 구성할 때 각 모듈을 정의하는 역할을 한다.

plugins {
    // Apply the foojay-resolver plugin to allow automatic download of JDKs
    id("org.gradle.toolchains.foojay-resolver-convention") version "0.8.0"
}
rootProject.name = "my-project"

만약 멀티 모듈 프로젝트라면 다음과 같이 하위 모듈을 정의할 수도 있다.

rootProject.name = "my-project"
include("module1", "module2")

build.gradle.kts: 빌드 설정 파일

이 파일은 프로젝트의 빌드 과정을 정의하는 곳이다.

// build.gradle.kts
plugins {
    application  // 실행 가능한 애플리케이션 빌드를 위한 플러그인
}
repositories {
    mavenCentral()  // 라이브러리 저장소 설정
}
dependencies {
    testImplementation(libs.junit.jupiter)  // JUnit 테스트 라이브러리 추가
    testRuntimeOnly("org.junit.platform:junit-platform-launcher")
    implementation(libs.guava)
}
java {
    toolchain {
        languageVersion.set(JavaLanguageVersion.of(21))
    }
}
application {
    mainClass.set("com.example.App")  // 실행할 메인 클래스 지정
}
tasks.named<Test>("test") {
    // Use JUnit Platform for unit tests.
    useJUnitPlatform()
}

gradle.properties: 전역 속성 설정 파일

이 파일은 프로젝트의 전역 설정을 관리하는 데 사용된다.

org.gradle.configuration-cache=true
org.gradle.jvmargs=-Xmx2g  # JVM 메모리 설정

이제 Gradle Wrapper를 사용하여 프로젝트를 더욱 쉽게 관리하는 방법을 살펴보자.

libs.versions.toml : 버전 카탈로그 파일

Gradle 버전 카탈로그(Version Catalog) 는 프로젝트에서 의존성 관리의 일관성을 유지하고, 중복을 줄이며, 가독성을 높이기 위해 도입된 기능이다.

Gradle 7.0부터 정식으로 지원되며, libs.versions.toml 파일을 사용하여 설정할 수 있다.

[versions]
guava = "33.3.1-jre"
junit-jupiter = "5.11.1"
springBoot = "3.1.0"

[libraries]
guava = { module = "com.google.guava:guava", version.ref = "guava" }
junit-jupiter = { module = "org.junit.jupiter:junit-jupiter", version.ref = "junit-jupiter" }
spring-boot-starter = { module = "org.springframework.boot:spring-boot-starter", version.ref = "springBoot" }
groovy-core = { module = "org.codehaus.groovy:groovy", version.ref = "groovy" }
groovy-json = { module = "org.codehaus.groovy:groovy-json", version.ref = "groovy" }
groovy-nio = { module = "org.codehaus.groovy:groovy-nio", version.ref = "groovy" }

[bundles]
groovy = ["groovy-core", "groovy-json", "groovy-nio"]

[plugins]
springBoot = { id = "org.springframework.boot", version.ref = "springBoot" }

junit-jupiter를 빌드 설정 파일에서 참조할 때에는 - 대신 .을 써서 libs.junit.jupiter와 같이 사용한다.

build.gradle.kts

plugins {
    alias(libs.plugins.springBoot)
}
dependencies {
    implementation(libs.kotlin.stdlib)
    implementation(libs.spring.boot.starter)
}

• [versions] 섹션

  • 라이브러리 및 플러그인의 버전을 정의하는 부분
  • version.ref를 사용하여 참조 가능

• [libraries] 섹션

  • 라이브러리를 정의하는 부분
  • module에 그룹과 아티팩트 ID를 명시
  • version.ref를 사용해 [versions]에서 정의한 버전 참조 가능

• [plugins] 섹션

  • Gradle 플러그인을 정의하는 부분
  • id는 플러그인의 ID, version.ref는 [versions]에서 정의한 버전 참조

Gradle Wrapper 사용하기

Gradle Wrapper(그래들 래퍼)는 프로젝트에서 일관된 Gradle 버전을 사용할 수 있도록 도와주는 기능이다.

Gradle Wrapper 생성

Gradle이 설치되어 있다면 다음 명령을 실행하여 Gradle Wrapper를 생성할 수 있다.

gradle wrapper --gradle-version 8.2

이 명령을 실행하면 gradlew, gradlew.bat, 그리고 gradle/ 디렉터리가 생성된다.

Gradle Wrapper로 빌드 실행

Gradle Wrapper를 사용하면 Gradle이 설치되지 않은 환경에서도 프로젝트를 빌드할 수 있다.

./gradlew build # Linux/macOS

gradlew.bat build # Windows

Wrapper는 지정된 Gradle 버전을 자동으로 다운로드하여 사용한다. 따라서, 개발팀 내에서 같은 Gradle 버전을 유지할 수 있으며, CI/CD 환경에서도 동일한 빌드 환경을 보장할 수 있다.

Wrapper 업데이트

Gradle 버전을 최신으로 업데이트하려면 다음 명령을 실행한다.

./gradlew wrapper --gradle-version 8.12

./gradlew wrapper --gradle-version latest

이제 gradlew 실행 시 자동으로 새로운 Gradle 버전이 적용된다.