오늘 안드로이드 앱 빌드를 돌렸는데 끝까지 가지 못했습니다. 그런데 저는 이걸 “빌드 실패”로 적지 않았습니다. 멈춘 지점이 코드가 아니라 빌드 도구를 내려받는 단계였기 때문입니다. 이 글은 제가 실패를 두 종류로 나눠 기록하는 이유와, 그렇게 나눴을 때 다음 작업이 어떻게 달라지는지에 대한 기록입니다.
멈춘 지점이 코드가 아니었다
빌드 스크립트를 실행하자 Gradle을 내려받는 단계에서 중단됐습니다. 원인은 배포 서버 주소를 찾지 못한 네트워크 문제였습니다. 즉 제 코드는 한 줄도 컴파일되지 않은 상태였습니다.
여기서 “빌드 실패”라고 적으면 나중에 기록을 다시 볼 때 코드를 의심하게 됩니다. 실제로는 코드를 아무리 고쳐도 같은 지점에서 멈춥니다. 그래서 저는 이 상태를 환경 차단으로 따로 표시했습니다.
두 실패는 다음 행동이 다르다
코드 실패는 제가 지금 손댈 수 있습니다. 오류 메시지를 따라가 고치면 통과합니다. 반면 환경 차단은 코드를 고쳐도 그대로입니다. 네트워크, 권한, 설치 여부처럼 코드 바깥을 바꿔야 풀립니다.
이 둘을 같은 칸에 적으면 며칠 뒤에 원인을 다시 추적해야 합니다. 나눠 적으면 “지금 할 수 있는 일”과 “환경이 준비돼야 하는 일”이 자동으로 갈립니다.
통과하지 않은 것을 통과로 적지 않았다
같은 날 코드 자체를 검증하는 테스트는 통과했습니다. 하지만 저는 그것으로 “빌드 완료”라고 쓰지 않았습니다. 실제 기기용 빌드는 아직 한 번도 성공하지 못했기 때문입니다.
비슷한 이유로 설치 도구가 요구하는 라이선스 동의도 자동으로 넘기지 않았습니다. 자동으로 넘기면 당장은 진행되지만, 무엇에 동의했는지 모르는 상태가 기록에 남습니다. 확인하지 않은 것은 확인하지 않았다고 두는 편이 나중에 훨씬 쌉니다.
그래서 이렇게 남긴다
저는 막힌 작업을 기록할 때 네 가지를 함께 적습니다. 무엇을 시도했는지, 어디서 멈췄는지, 코드 문제인지 환경 문제인지, 다음에 무엇을 확인할지입니다. 이렇게 적어두면 환경이 준비된 날 바로 그 지점부터 이어갈 수 있습니다.
아직 실제 기기 빌드와 실행은 확인하지 못했습니다. 그 단계는 미검증으로 남겨 두었고, 환경이 갖춰지면 그때 결과를 다시 기록할 예정입니다.
공식 문서가 설명하는 Gradle 내려받기 단계
이 글에서 멈춘 지점은 Gradle을 내려받는 단계였습니다. Android 개발자 문서에 따르면 Gradle Wrapper(gradlew)는 소스에 함께 들어 있는 작은 프로그램으로, 필요한 Gradle 배포판을 내려받아 실행합니다. 어느 버전을 받을지는 gradle/wrapper/gradle-wrapper.properties의 distributionUrl에 적혀 있습니다. Gradle 공식 문서도 같은 설명이며, 배포판이 GRADLE_USER_HOME에 없으면 내려받고, 이후 빌드는 주소가 바뀌지 않는 한 받아 둔 사본을 다시 씁니다. 그래서 네트워크가 막힌 환경에서 처음 빌드하면 코드를 컴파일하기도 전에 이 단계에서 멈출 수 있습니다.
Gradle 공식 문서는 내려받는 동안의 기본 네트워크 제한 시간이 10,000밀리초이고 재시도는 기본으로 꺼져 있다고 안내합니다. gradle-wrapper.properties에 retries와 retryBackOffMs를 넣어 재시도를 켤 수 있고, 배포판 주소는 회사 내부 서버를 가리키도록 바꿀 수도 있습니다. distributionSha256Sum에 SHA-256 값을 적어 두면 내려받은 배포판이 맞는지 검사하며, 값이 다르면 빌드가 실패합니다. 다만 이 검사는 배포판을 아직 받지 않았을 때만 수행됩니다.
| 멈춘 단계 | 공식 문서 기준 설명 | 기록할 분류 |
|---|---|---|
| Gradle 배포판 내려받기 | distributionUrl 주소에서 받고, 이미 받은 사본은 재사용합니다. | 환경 차단(네트워크) |
| 의존성 내려받기 | settings 파일에 적힌 저장소(google(), mavenCentral() 등)에서 받습니다. | 환경 차단 또는 설정 문제 |
| 빌드 파일 수정 뒤 동기화 | Android Studio가 변경을 가져오고 설정 오류를 검사합니다. | 코드·설정 실패 |
Android 문서는 빌드 도구가 로컬 파일과 원격 저장소의 의존성을 관리해 사용자가 바이너리를 직접 내려받지 않아도 된다고 설명합니다. 기본 settings 파일에는 플러그인용으로 gradlePluginPortal(), google(), mavenCentral()이, 의존성용으로 google()과 mavenCentral()이 적혀 있습니다. 즉 이 저장소 주소 중 하나에 닿지 못하는 환경이라면 코드를 바꿔도 같은 자리에서 멈춥니다. 이 문서들은 실패를 코드 실패와 환경 차단으로 나누는 방법을 직접 안내하지는 않습니다. 그 분류는 이 글의 기록 방식이며, 공식 문서는 어느 단계에서 무엇을 내려받는지의 근거로만 읽어 주세요.
확인 자료
기준일: 2026-10-18