AOSP 커스텀 안드로이드 빌드 환경 구축 가이드: 환경 설정부터 에뮬레이터 구동까지

안드로이드 OS 레벨의 기능을 수정하거나 전용 하드웨어 칩셋에 맞는 커스텀 펌웨어를 제작하려면 AOSP(Android Open Source Project) 소스 코드를 통째로 내려받아 직접 빌드하는 과정을 거쳐야 합니다. 하지만 수백 기가바이트에 달하는 소스 크기와 복잡한 의존성 패키지 때문에 초기 환경 구축 단계에서 좌절하는 개발자들이 굉장히 많은데요.

이전 포스팅에서 다룬 안드로이드 아키텍처와 Soong 빌드 시스템의 이론적 토대를 바탕으로, 이번에는 실제로 Ubuntu 리눅스 환경에서 AOSP 14 소스 코드를 체크아웃하고, 나만의 커스텀 모듈을 얹어 에뮬레이터로 구동하는 전 과정을 단계별로 상세히 살펴보겠습니다.

Generated by Gemini AI.

📌 핵심 요약 3줄

1. AOSP 빌드는 의존성 패키지가 많으므로 Ubuntu 22.04 LTS 환경 권장하며, 구글 저장소 관리를 위한 repo 도구를 필수로 셋업해야 합니다.
2. repo init과 repo sync를 통해 소스코드를 동기화한 뒤, **envsetup.sh**와 lunch 명령어로 빌드 타겟 아키텍처를 지정합니다.
3. 나만의 하드웨어나 모듈을 커스텀 빌드에 포함하려면 Android.bp 모듈을 정의하고, 제품 구성 파일(PRODUCT_PACKAGES)에 명시해 주어야 합니다.

---

1. 빌드 전 필수 사양 및 개발 환경 준비

안드로이드 소스 트리는 매우 방대합니다. 빌드를 시작하기 전, 개발 장비가 아래의 최소 요구 사양을 만족하는지 반드시 확인해 주세요.

하드웨어 항목	최소 권장 사양	비고
운영체제 (OS)	Ubuntu 22.04 LTS / 20.04 LTS	WSL2 환경도 가능하나 기본 리눅스 환경 권장
저장 공간 (Disk)	최소 400GB 이상 (SSD 강력 권장)	빌드가 진행되면서 중간 산출물(out/)이 엄청나게 늘어남
메모리 (RAM)	32GB 이상	RAM이 부족하면 빌드 후반부 링크 단계에서 덤프 에러 발생

1.1 필수 소프트웨어 패키지 설치

우분투 터미널을 열고 AOSP 빌드에 필요한 도구들과 컴파일러 툴체인 의존성 패키지들을 한 번에 설치해 줍니다.

Bash

 

sudo apt update && sudo apt upgrade -y
sudo apt install -y git-core gnupg flex bison build-essential zip curl zlib1g-dev \
    gcc-multilib g++-multilib libc6-dev-i386 libncurses5 libncurses5-dev \
    x11proto-core-dev libx11-dev libgl1-mesa-dev libxml2-utils xsltproc unzip \
    python3 python3-pip python3-venv

1.2 구글 전용 repo 도구 설치

안드로이드는 수백 개의 개별 Git 저장소가 모여 하나의 거대한 소스 트리를 이룹니다. 이를 중앙 제어하기 위해 구글이 만든 repo 툴을 다운로드하고 환경 변수에 등록합니다.

Bash

 

# 개인 로컬 바이너리 디렉터리 생성 및 repo 다운로드
mkdir -p ~/bin
curl https://storage.googleapis.com/git-repo-downloads/repo > ~/bin/repo
chmod a+x ~/bin/repo

# bash 패스 등록 (셸을 재시작해도 유지되도록 .bashrc에 등록하는 것을 추천합니다)
export PATH=~/bin:$PATH

---

2. AOSP 소스 코드 다운로드

이제 소스코드를 담을 메인 디렉터리를 만들고, 안드로이드 14(Upside Down Cake) 안정화 브랜치를 타겟으로 지정하여 소스 동기화를 진행하겠습니다.

Bash

 

# 빌드 작업 공간 생성
mkdir ~/aosp && cd ~/aosp

# 안드로이드 14 특정 릴리즈 브랜치로 레포지토리 초기화
repo init -u https://android.googlesource.com/platform/manifest -b android-14.0.0_r3

# 전체 소스 다운로드 (PC의 CPU 코어 수를 자동으로 감지하여 풀 병렬 다운로드 진행)
repo sync -j$(nproc --all)

⚠️ 주의: 네트워크 환경에 따라 소스 다운로드에 수 시간이 걸릴 수 있으므로 배터리 전원 설정을 확인하고 기다려 주셔야 합니다.

---

3. 빌드 타겟 설정 (Lunch 메뉴 선택)

소스 다운로드가 끝났다면 안드로이드 빌드 시스템이 제공하는 환경 변수 초기화 스크립트를 로드해야 합니다. 이전 포스팅에서 다루었던 Soong 엔진의 기초 뼈대를 잡는 작업입니다.

Bash

 

source build/envsetup.sh

스크립트를 로드하면 lunch라는 명령어를 사용할 수 있게 됩니다. lunch 뒤에 타겟 제품군과 빌드 타입을 결합한 파라미터를 입력합니다. 여기서는 PC에서 가상으로 돌려볼 수 있는 x86_64 기반 에뮬레이터용 타겟을 지정하겠습니다.

Bash

 

lunch aosp_x86_64-userdebug

💡 빌드 타입(Build Variant) 구별법

주목해야 할 점은 타겟명 뒤에 붙는 접미사(userdebug)입니다. 안드로이드는 목적에 따라 빌드 보안 단계를 다르게 가져갑니다.

빌드 타입 (Variant)	루트(root) 권한 여부	디버깅(adb) 활성화 여부	주요 사용 목적
eng	기본 활성화	기본 활성화 (개발 전용 로깅 탑재)	프레임워크 자체를 엔지니어링하고 개발할 때 사용
userdebug	정식 전환 가능	활성화 (디버그 포트 오픈)	일반적인 앱 연동 테스트 및 내부 필드 테스트용
user	비활성화 (정형 격리)	비활성화 (보안 최고 등급)	일반 소비자가 구매하는 상용 스마트폰 출시용

---

4. 나만의 커스텀 모듈 주입하기

커스텀 OS의 묘미는 내가 만든 로직을 시스템 레이어에 임베딩하는 것입니다. 제조사나 하드웨어 벤더 트리를 구성한다고 가정하고, 커스텀 C++ 바이너리 모듈을 소스 트리 내부에 심어보겠습니다.

4.1 디렉터리 및 Android.bp 생성

보통 제조사 전용 코드는 device/[제조사명]/[기기명] 구조를 따릅니다. 디렉터리를 만들고 소스 파일과 빌드 파일을 작성합니다.

Bash

 

mkdir -p device/custom/device_name
cd device/custom/device_name

여기에 소스 코드가 준비되었다면, Soong 빌드 시스템이 인식할 수 있도록 Android.bp 파일을 아래 형식으로 깔끔하게 작성해 줍니다.

코드 스니펫

 

// C++ 바이너리 실행 파일 모듈 정의
cc_binary {
    name: "custom_module",       // 시스템 내부에서 고유하게 식별될 모듈명
    srcs: ["custom_code.cpp"],   // 컴파일할 타겟 소스 코드
    cflags: ["-Wall"],           // 모든 컴파일 경고 활성화
    shared_libs: ["liblog"],     // 안드로이드 네이티브 로그 시스템(Logcat) 라이브러리 링크
}

4.2 모듈 패키지 등록

모듈을 만들기만 하면 컴파일만 되고 실제 시스템 이미지에 포함되지 않습니다. 기기 빌드 설정 파일(device.mk 혹은 제품 매니페스트 파일)을 열어 PRODUCT_PACKAGES 리스트에 우리가 정의한 모듈명을 추가해 주어야 최종 안드로이드 /system/bin/ 폴더에 안착합니다.

Makefile

 

PRODUCT_PACKAGES += custom_module

---

5. 풀 빌드(Full Build) 가동 및 에뮬레이터 확인

모든 준비가 완료되었으니 전체 시스템 이미지를 구워낼 차례입니다.

Bash

 

make -j$(nproc --all)

컴파일이 정상적으로 완료되면 out/target/product/generic_x86_64/ 경로 밑에 system.img, vendor.img, boot.img 등 OS 가동에 필요한 핵심 이미지 파일들이 나란히 생성됩니다.

5.1 가상 기기(에뮬레이터) 가동

따로 안드로이드 스튜디오를 켜지 않아도, AOSP 터미널 환경에서 곧바로 빌드된 신끈끈한 이미지를 기반으로 가상 머신을 구동할 수 있습니다.

Bash

 

emulator -avd aosp_x86_64

잠시 후 안드로이드 부팅 애니메이션이 지나가고 순정 홈 화면이 나타나면 커스텀 안드로이드 OS 빌드에 완전히 성공한 것입니다! 만약 실제 개발용 하드웨어 보드가 준비되어 있다면 기기를 다운로드 모드로 전환한 뒤 아래 명령어로 플래싱을 수행할 수 있습니다.

Bash

 

fastboot flashall

---

💡 AOSP 커스텀 빌드를 위한 실전 팁

1. ccache 활성화로 빌드 시간 반토막 내기: AOSP 최초 빌드는 수 시간이 걸리지만, 컴파일러 캐시 도구인 ccache를 셋업해 두면 두 번째 빌드(Rebuild)부터는 캐싱된 바이너리를 활용하므로 속도가 기하급수적으로 빨라집니다. ~/.bashrc 파일에 아래 설정을 넣고 캐시 공간을 지정해 두는 것을 적극 권장합니다.
2. Bash

    

   export USE_CCACHE=1
   export CCACHE_DIR=~/.ccache
   # 최초 1회 캐시 최대 용량 설정 (안드로이드 14 기준 50G 이상 추천)
   ccache -M 50G
   

3. 특정 모듈만 찝어서 빌드하기: 전체 빌드(make)를 매번 돌릴 필요는 전혀 없습니다. 위에서 우리가 추가한 custom_module 코드만 수정했다면 전체 소스를 검사하지 말고 m custom_module 명령어를 치세요. 변경된 해당 바이너리만 단 몇 초 만에 컴파일하여 출력 폴더에 덮어씌워 줍니다.

⚠️ 흔히 하는 실수

1. repo sync 도중 네트워크 단절로 인한 소스 깨짐 현상: 직장이나 가정의 와이파이 환경에서 repo sync를 진행하다가 네트워크가 불안정해져 중간에 패킷이 누락되는 경우가 자주 발생합니다. 이 상태로 빌드를 돌리면 원인 모를 문법 에러나 파일 누락 에러가 발생하므로, 소스 동기화 단계에서는 가급적 안정적인 유선 랜 환경을 사용하시고, 에러가 난다면 repo sync -c --force-sync 명령어로 소스 동기화를 깔끔하게 강제 재시도해야 합니다.
2. Java / Python 버전 충돌 대란: 최신 안드로이드 14 시스템 빌드 툴체인은 내부적으로 특정 버전의 자바(OpenJDK)와 파이썬 환경을 내장하여 구동합니다. 만약 개발자 PC에 개인적으로 설치한 구형 Java 버전이나 별도의 가상 환경(Anaconda 등)이 PATH 환경 변수 상단에 먼저 잡혀있으면, AOSP 내부 빌드 스크립트가 꼬여 컴파일 도중 런타임 에러를 뿜어냅니다. 빌드 전에 java -version을 확인하여 AOSP가 요구하는 호환 버전과 충돌이 없는지 체크해야 아까운 시간을 버리지 않습니다.

---

6. 결론

지금까지 우분투 리눅스 환경에서 안드로이드 소스 코드를 온전히 내려받아 나만의 커스텀 바이너리를 심고 에뮬레이터 환경에서 확인하는 빌드 파이프라인의 전 과정을 정복해 보았습니다. 처음 보면 수많은 에러 메시지와 명령어가 낯설고 두렵겠지만, 부팅 단계와 빌드 계층 구조를 명확히 이해하고 접근한다면 시스템 레벨을 쥐락펴락하는 고급 안드로이드 엔지니어로 도약할 수 있습니다.

이제 여러분만의 맞춤형 시스템 서비스나 테마를 가동할 준비가 끝났습니다.