[Gradle] Gradle Wrapper 개념 정리

토이 프로젝트를 해보고 있는데, 단순히 gradle을 실행하는 것 보다는 gradle wrapper를 사용하는 것이 훨씬 좋다는 의견을 접하게 되었다.

 

그래서 프로젝트에 gradle wrapper를 적용하면서 이 기능의 개념과 사용 방법, 알면 좋은 기능들을 문서를 보면 정리해보았다. (문서 번역 기반)

 

더 자세한 내용은 Gradle wrapper 문서를 참고하는 것이 좋을 듯 싶다.

 

Gradle Wrapper

개념

필요시 선언된 gradle을 다운로드 받을 수 있게 해주는 도구로, 어떤 환경에서든 동일한 gardle 환경으로 프로젝트 빌드를 가능하게 해주는 도구

장점

1. 사용자의 환경과 무관하게 동일한 gradle 버전으로 빌드 표준화
2. 다양한 사용자 및 환경에서의 gradle 버전 제공은 간단하게 wrapper를 변경함으로써 가능

사용 방법

1. Gradle Wrapper 추가

gradle wrapper

# Options
# 1) --gradle-wrapper 버전
# wrapper에서 사용할 gradle 버전 지정
# 버전 종류
# lastest: 가장 최신 버전
# release-candidate: 배포되었던 버전 (Ex. 8.12-rc-2)
# nightly: 안정화가 검증되지 않는 최신 버전
# release-nightly: 안정화가 검증되지 않는 버전

# 2) --distribution-type 타입
# wrapper를 다운로드 타입으로, 얼만큼 큰 파일을 다운로드할 지 결정
# 타입 종류
# bin(기본값): gradle 실행에 필요한 bin 파일만 다운로드
# all: bin 파일과 문서 모두 다운로드

# 3) --gradle-distribution-url URL
# Gradle zip 파일을 다운로드 받은 URL을 제공
# 이 옵션과 --gradle-version, --distribution-type임 함께 사용될 경우
# URL은 https로 HEAD request가 전송되거나 파일 방식일 경우 해당 파일이 존재하는지 확인한다.
# 따라서 이 옵션은 gradlew을 다운로드 받는 경로가 사내망에 위치하는 경우와 같이 특별한 경우에만 사용

# 4) --validate-url 
# gradle 다운로드 URL을 검증할 것인지 설정. 기본값임

# 5) --networkd-timeout ms초
# 다운로드 시 time-out 되기까지의 시간 설정. 기본값은 10000.

# 그 외에도 --gradle-distribution-sha256-sum, --no-validate-url이 있다.

위 명령어를 통해 wrapper 파일이 생성된다.

 

Gradle Wrapper 파일 추가는 자신의 개발 환경에 설치된 gradle 버전을 필요로 한다. 초기에 한 번만 wrapper file을 생성하면 그 이후 다시 생성할 필요는 없다.

 

├── a-subproject
│   └── build.gradle.kts
├── settings.gradle.kts
├── gradle
│   └── wrapper
│       ├── gradle-wrapper.jar
│       └── gradle-wrapper.properties
├── gradlew
└── gradlew.bat

# gradle-wrapper.jar: gradle 다운로드 URL에서 다운받은 wrapper jar 파일
# gradle-wrapper.properties: 다운로드 받을 gradle에 대한 설정 파일
# gradlew, gradlew.bat: wrapper로 빌드를 실행하는 shell script 및 window batch script

Gradle 프로젝트에는 setting.gradle 파일과 하나의 서브 프로젝트당 하나의 build.gradle 파일이 생성된다.

wrapper 파일은 프로젝트의 root 디렉토리에 위치한 gradle 디렉토리 내부에 위치한다.

 

** wrapper 파일에는 jar와 같은 파일이 있는데 이 파일들이 version control에 포함되게 해야 한다. (커밋에 포함되어야 한다.)

그래야 wrapper에 설정된 gradle 버전이 즉시즉시 적용되니까..

 

2. Gradle Wrapper 사용

# Mac
./gradlew task타입

# Window
gardlew.bat task타입

Gradle Wrapper는 Gradle을 설치한 후 build하는 것처럼 동작한다.

 

한 번 gradle 파일이 다운로드 되었다면, 해당 파일은 로컬에 저장되며 이후 gradle wrapper가 수정될 때까지 로컬에 저장된 gradle을 사용하게 된다.

3. Gradle Wrapper 업그레이드

gradle의 버전을 업그레이드 하는 방법

1. gradle-wrapper.properties에서 distributionUrl의 값을 변경하기
2. “gradle wrapper” 명령어를 실행해서 버전 지정해주기 (강력 추천)

2번을 사용했을 경우, 해당 gradle 버전에 적용된 shell 및 batch script의 최적화가 프로젝트에 적용된다.

 

“gradle wrapper” 명령어를 한 번 실행하면 gradle-wrapper.properties 파일만 수정되며, gradle-wrapper과 관련된 모든 파일을 수정하고 싶다면 이 명령어를 한 번 더 수행해야 한다. (완벽한 적용을 위해서는 총 2번 실행 필요)

 

gradle wrapper 커스텀화

아래 URL에 나와있는 API를 build.gradle에 적용하여 gradle wrapper의 과정을 커스텀하게 변경할 수 있다.

https://docs.gradle.org/current/dsl/org.gradle.api.tasks.wrapper.Wrapper.html

 

 

인증이 필요한 Gradle 배포판 다운로드

gradle wrapper는 서버에서 gradle을 다운로드 받을 때 HTTP Basic 인증을 사용하여 인증을 할 수 있다.

방법

1. distributionUrl에 인증 정보 담기 (권장 X)
2. system properties 사용하기

2번을 사용할 경우, grdle properties 파일(주로 .gradle/gradle.properties)을 통해 설정할 수 있다.

systemProp.gradle.wrapperUser=사용자 이름
systemProp.gradle.wrapperPassword=사용자 비밀번호

 

 

Gradle 배포판에 대한 검증

gradle 배포판에 대한 중간자 공격을 방어하기 위해 SHA-256 hash sum 비교를 통해 다운로드 받은 gradle 파일이 올바른지 검증할 수 있다.

방법

1. 사용중인 버전에 맞는 SHA-256 버전 다운로드
   https://services.gradle.org/distributions-snapshots/
   https://services.gradle.org/distributions
2. 다운로드 받은 SHA-256 hash checksum을 gradle-wrapper.properties 파일의 distributionSha256Sum 프로퍼티 값으로 추가 or gradlew CLI의 gradle-distribution-sha256-sum 옵션 값으로 추가

# gradle.proeprties
distributionSha256Sum=hash checksum 값

# Gradle CLI
gradle wrapper --gradle-distribution-sha256-sum=hash checksum 값

 

이 검증 로직은 gradle 배포판을 다운로드 받을 때 한 번 수행된다.

 

만약 gradle.properties에서는 distributionSha256Sum 값이 정의되어 있지만 wrapper 실행 시 다른 버전 지정과 같이 설정한 distributionSha256Sum의 값과 호환되지 않는다면 "wrapper" task는 실패하게 된다.

 

 

출처

https://docs.gradle.org/current/userguide/gradle_wrapper.html