sync build.gradle

Gradle 기반 프로젝트를 생성한 이후, Gradle(코끼리 아이콘 🐘) 버튼을 통해 Gradle 전용 메뉴 창을 오픈합니다.
상단의 “Sync All Gradle Projects”( 원형 화살표🔄) 기능을 실행하여 의존성과 프로젝트 설정을 최신 상태로 동기화합니다.

 

🔄 Gradle Sync: 빌드의 '설계도'를 '실제 환경'으로 바꾸는 과정

인텔리제이에서 이 버튼을 누르는 행위는 단순히 "새로고침"이 아닙니다. Gradle이라는 외부 도구와 IntelliJ라는 IDE가 서로 "야, 나 이런 라이브러리 쓸 건데 너도 준비됐어?"라고 대화를 나누는 과정입니다.

1. 클릭 시 벌어지는 4단계 마법 🪄

1. 스크립트 분석 (Parsing): IntelliJ가 사용자님의 build.gradle 코드를 한 줄씩 읽습니다. plugins, dependencies, repositories 등의 설정을 해석하죠.
2. 의존성 그래프 생성 (Dependency Resolution):
   • repositories { mavenCentral() }로 달려가서 필요한 라이브러리들을 찾습니다.
   • 예를 들어 spring-boot-starter-web을 가져오라고 하면, 이 녀석이 내부적으로 필요로 하는 수십 개의 다른 라이브러리(Tomcat, Jackson, Logging 등)까지 줄줄이 사탕으로 계산해서 거대한 의존성 나무(Tree)를 그립니다.
3. 라이브러리 다운로드: 내 컴퓨터의 로컬 창고(.gradle/caches)에 없는 파일들을 인터넷에서 실제로 다운로드해 옵니다.
4. IDE 인덱싱 (Indexing): 다운로드가 끝나면 IntelliJ가 그 라이브러리 내부의 코드들을 다 읽어서, 사용자님이 코드 짤 때 자동 완성(Auto-complete)이 되도록 준비를 마칩니다.

2. 왜 이 버튼을 가장 먼저 눌러야 하나요? 🧐

사용자님이 작성하신 build.gradle에는 QueryDSL, Kafka, JWT 등 수많은 외부 도구가 들어있습니다. 이 버튼을 누르지 않고 바로 Build를 누르면 다음과 같은 대참사가 일어납니다.

• "Cannot resolve symbol": 코드창 전체가 빨간색으로 물듭니다. IDE가 SpringBootApplication이나 Lombok이 뭔지 전혀 모르기 때문입니다.
• 컴파일 에러: 소스 코드를 해석할 재료(Library)가 없으니 빌드 자체가 시작도 안 됩니다.
• QueryDSL 클래스 미생성: QClass를 만드는 로직 자체가 Gradle 설정에 들어있는데, Sync를 안 하면 IDE는 그 로직을 실행할 준비조차 못 합니다.

3. 언제 이 버튼을 눌러야 할까? (골든 타임) ⏰

• 처음 프로젝트를 생성/Open 했을 때 (무조건 1순위!)
• dependencies에 새로운 라이브러리를 추가하거나 버전을 바꿨을 때
• plugins 설정을 변경했을 때
• 이유 없이 코드가 빨간 줄로 뜨면서 "라이브러리를 못 찾겠다"고 할 때

4. 실전 팁: 버튼의 위치와 단축키 💡

• 위치: build.gradle 파일을 수정하면 오른쪽 상단에 작게 나타나는 코끼리+화살표 아이콘을 누르거나, 오른쪽 Gradle 탭 상단에 있는 새로고침 아이콘을 누르면 됩니다.
• 강제 수행: 가끔 Sync가 꼬일 때는 File -> Invalidate Caches...를 하고 다시 Sync를 누르는 것이 직장인 개발자들의 국룰입니다.

💡 요약하자면!

"Sync All Gradle Projects"는 요리하기 전에 레시피를 보고 모든 재료를 마트에서 사와서 주방 조리대 위에 딱 세팅해두는 과정입니다. 이 과정이 없으면 요리(Build)를 시작할 수조차 없죠.

사용자님 말씀대로 무조건 가장 먼저 클릭해야 하는 버튼이 맞습니다! 👏

이제 Sync가 완료되어 왼쪽 [External Libraries] 목록에 수많은 jar 파일이 보이시나요? 그렇다면 이제 정말로 Build를 눌러도 되는 상태입니다!

 

보통 GitHub에서 프로젝트를 클론(Clone)해서 인텔리제이로 처음 열면, 인텔리제이가 스마트하게 build.gradle 파일을 감지하고 자동으로 "Importing Gradle Project..."라는 상태바와 함께 Sync를 시작합니다.

하지만 "무조건, 항상" 자동으로 완벽하게 되는 것은 아니기 때문에 주의가 필요합니다. 왜 수동으로 확인해야 하는지 그 이유를 명확히 짚어드릴게요. 🧐

 

🤖 인텔리제이의 자동 Sync, 언제 믿어도 될까?

1. 자동으로 실행되는 경우 (일반적)

• 최초 오픈: File -> New -> Project from Version Control로 클론하거나, 이미 클론된 폴더를 Open으로 처음 열 때 인텔리제이는 자동으로 Gradle 빌드 스크립트를 분석하고 동기화를 시도합니다.
• Auto-Reload 설정: 인텔리제이 설정에서 "Any changes in build script" 옵션이 켜져 있다면, 코드를 수정할 때마다 자동으로 Sync가 돕니다.

2. 수동 Sync(🔄)가 꼭 필요한 경우 (예외 상황) ⚠️

자동으로 될 줄 알았는데 안 되는 짜증 나는 순간들이 꽤 많습니다.

• 초기 로드 실패: 라이브러리를 다운로드하다가 네트워크가 불안정해서 끊기면, 인텔리제이는 "실패" 상태로 멈춰버립니다. 이때는 수동으로 다시 🔄 버튼을 눌러줘야 합니다.
• 프로젝트 신뢰 설정 (Trust Project): 요즘 인텔리제이는 보안을 위해 외부에서 가져온 프로젝트를 열 때 "이 프로젝트를 신뢰하십니까?"라고 묻습니다. 이때 [Trust Project]를 누르기 전까지는 절대 자동으로 Sync를 돌리지 않습니다.
• Gradle 버전 불일치: 내 컴퓨터의 자바 버전과 프로젝트의 gradle-wrapper.properties에 적힌 버전이 충돌하면 자동 Sync가 에러를 내뿜으며 멈춥니다. 이 땐 환경을 맞추고 수동으로 다시 돌려야 하죠.
• 오프라인 모드: 만약 인텔리제이가 'Offline Mode'로 설정되어 있다면 자동으로 라이브러리를 못 가져오므로 직접 풀어줘야 합니다.

 

🛠️ 클론 후 "진짜" 확인해야 할 절차

GitHub에서 프로젝트를 가져왔다면 자동 Sync가 끝난 뒤에도 다음을 꼭 확인하세요.

1. External Libraries 확인: 왼쪽 프로젝트 창 맨 아래 External Libraries 목록에 스프링 관련 .jar 파일들이 가득 차 있는지 보세요. 여기가 비어있다면 자동 Sync가 실패한 겁니다.
2. JDK 설정: 인텔리제이가 자동으로 JDK를 못 잡는 경우가 허다합니다. File -> Project Structure에서 Java 17이 제대로 잡혀 있는지 꼭 확인하세요.
3. Lombok/QueryDSL: 아까 말씀드린 Annotation Processing 설정은 프로젝트 파일(build.gradle)에 포함된 게 아니라 내 인텔리제이 프로그램의 설정입니다. 클론을 새로 받았다면 이 설정이 꺼져 있을 수 있으니 다시 켜줘야 합니다. ✅

 

💡 결론적으로!

"인텔리제이가 자동으로 시도는 하지만, 성공 여부는 개발자가 직접 확인해야 한다"가 정답입니다. 그래서 우리는 항상 우측 Gradle 아이콘을 선택해서 메뉴 창을 열어보고, 빨간 줄이 있거나 라이브러리가 안 보이면 주저 없이 🔄 버튼을 누르는 습관을 갖는 것이죠.