Mac.apk 딥다이브
— Android의 약속을 macOS 위에서 다시 구현하다

1프로젝트 한줄 요약

Mac.apk는 Apple Silicon Mac에서 Android 앱을 일반 macOS 프로세스로 실행하도록 만드는 호환성 계층입니다. APK 속 DEX 코드는 JVM 바이트코드로 바꾸고, Android의 android.* API는 Java로 다시 구현하며, 네이티브 코드는 아키텍처에 맞는 로더·변환기를 거칩니다. 화면과 소리는 Cocoa·Metal·macOS 미디어 기능으로 연결합니다.

같은 CPU 명령어를 쓴다는 사실만으로는 부족하고, 앱이 기대하는 운영체제의 약속까지 맞춰야 실행됩니다. Android와 macOS는 실행 파일 형식, 시스템 라이브러리, 파일 경로, 스레드 규칙이 다릅니다. 이 차이를 메우는 코드가 이 저장소의 주인공입니다.

APK 안의 세 가지 짐을 분리해서 보자

구현의 시작점은 runtime/src/main.cpp::main()입니다. APK 준비와 JVM 생성을 거쳐 com.macapk.loader.Boot.run()을 호출합니다. Java 쪽에서는 앱 클래스 로더와 실행 환경을 만들고 Activity 실행으로 이어집니다. 끝에는 Mac의 이벤트 루프가 창과 입력을 처리합니다.

README는 프로젝트를 Alpha로 명시합니다. “모든 Android 앱을 실행한다”는 제품으로 이해하면 곤란합니다. 어떤 기능을 구현했고 어떤 기능은 비어 있는지 읽어 가며, 완전한 플랫폼 호환성이 얼마나 넓은 문제인지 배우기에 적합합니다.

2왜 주목받는가

2-1. “Android를 부팅하지 않고 앱을 띄운다”는 접근

TrendShift Weekly #20의 선정 대상이며, 2026-10-23 GitHub 기준 스타는 2,537개, 포크는 80개입니다. 2026-05-19 생성된 저장소에 이 정도 관심이 모였다는 점은 눈에 띕니다. 다음은 소스 구조와 공개 기능을 바탕으로 해석한 관심 요인이며, 특정 사건이 인기 상승의 원인이라는 뜻은 아닙니다.

• Mac과의 통합: SwiftUI 런처, 앱별 .app 번들, Cocoa 창, 호스트 파일 선택·미디어 제어를 한 제품으로 연결합니다.
• 운영체제 경계를 직접 다루는 공개 코드: DEX 변환기뿐 아니라 ARM 로더와 Bionic 호환 코드까지 읽을 수 있습니다.
• 역할을 나눈 기술 조합: Java는 Android API, Swift는 설치와 관리 화면, C++·Objective-C++는 CPU·OS·그래픽 경계를 맡습니다.
• 구체적인 사용 사례: 호환성 문서에는 게임·음악·메신저·앱 스토어별 결과와 알려진 오류가 기록되어 있습니다.

2-2. 비슷한 목표, 다른 실행 환경

비교 근거는 Android Emulator 공식 안내와 Waydroid 공식 문서입니다. 여기서 Mac.apk의 장점은 시스템 부팅을 생략하고 호스트 기능을 연결하는 설계입니다. 동일 앱·동일 하드웨어로 측정한 자료 없이 “항상 더 빠르다”, “메모리가 몇 배 적다”는 결론은 내릴 수 없습니다.

2-3. “네이티브”를 세 가지 뜻으로 나눠 읽기

Mac.apk의 “네이티브 실행”은 모든 코드를 변환 없이 실행한다는 뜻이 아니라, Android 게스트 운영체제 없이 호스트에서 실행한다는 뜻으로 읽어야 합니다. ARM64 라이브러리는 원래 기계어를 주로 실행하지만 로딩·재배치·시스템 호출 처리가 필요합니다. ARM32는 ARM64로 바뀌며, DEX도 JVM용 코드로 변환됩니다.

2-4. 호환성 숫자는 시험 범위를 읽어야 의미가 있다

COMPATIBILITY.md는 2026-10-20 갱신 기준으로 71개 앱: 동작 58개, 부분 동작 10개, 미동작 3개라고 요약합니다. 이는 프로젝트의 수동 시험 집계입니다. 같은 앱의 여러 버전이 별도 행으로 나오므로 표의 행 수를 앱 수로 세면 안 됩니다.

또한 “동작” 표시 옆에도 세부 결함이 적혀 있습니다. AntennaPod는 재생 화면 문제, Mindustry는 온라인 멀티플레이 문제를 기록합니다. 숫자를 Android 생태계 전체의 성공률로 일반화하지 말고, 어떤 버전에서 어떤 동작을 시험했는지를 함께 읽어야 합니다.

3기술 스택 전체 지도

이 저장소에는 package.json, Cargo.toml, pyproject.toml, go.mod, Package.swift, Dockerfile이 없습니다. Node 서버나 Rust 데스크톱 셸을 가정하고 읽으면 구조를 놓칩니다. 빌드 설정과 의존성 출처는 CMake 파일과 셸 스크립트, 사전 빌드 산출물의 PROVENANCE.txt에 나뉘어 기록되어 있습니다.

3-1. 백엔드에 해당하는 실행 엔진

JDK 25 선택 경로도 있지만 기본값은 MACAPK_JDK_DEFAULT=21입니다. JDK의 실제 버전은 디렉토리 이름이 아니라 release 파일의 JAVA_VERSION으로 검사합니다. 따라서 “JDK 25 전면 전환”으로 쓰면 부정확합니다. Java API 컴파일 기준과 실행 JVM의 선택도 서로 다른 설정입니다.

3-2. 프론트엔드와 호스트 통합

SwiftUI는 Mac.apk의 관리 화면에 쓰입니다. 모든 Android View를 SwiftUI 컴포넌트로 바꾼다는 뜻은 아닙니다. Android 앱 자체의 화면은 프레임워크·Canvas·Surface·그래픽 브리지를 통해 그려집니다. 이 구분을 해야 UI 오류가 생겼을 때 올바른 파일부터 찾을 수 있습니다.

3-3. 그래픽에는 여러 통로가 있다

ANGLE은 그래픽 API 번역 계층이며, MoltenVK는 Vulkan의 일부 기능을 Metal 위에 제공합니다. 각각의 상류 프로젝트가 지원하는 범위와 Mac.apk가 실제 연결한 범위는 같지 않을 수 있습니다. API 이름이 보인다고 모든 확장 기능의 지원까지 결론 내리지 마세요.

Capstone·libpng·libvpx는 Homebrew 경로에서 찾지만 CMake에 정확한 패치 버전 고정은 없습니다. Swift 컴파일러 버전도 고정 매니페스트로 선언하지 않습니다. 따라서 표에 임의의 최신 버전을 채우지 않습니다. 고정된 것과 환경에 맡긴 것을 나눠 기록하는 것도 의존성 분석입니다.

3-4. 인프라·빌드·검증

• CMake 최소 3.20: 두 CMakeLists.txt가 선언합니다. 런타임과 translator는 별도 대상으로 빌드됩니다.
• 직접 Swift 컴파일: scripts/build_launcher.sh가 swiftc -O -parse-as-library를 호출합니다. 대상은 arm64-apple-macos26.0입니다.
• 작은 JRE 묶기: scripts/stage_jre.sh가 jlink로 모듈을 묶습니다. 최종 사용자에게 개발용 JDK 전체가 필요한 구조는 아닙니다.
• 플랫폼 리소스: 권장 API 36 빌드는 android-16.0.0_r2 태그를 사용합니다. scripts/build_framework_res.sh의 인자 없는 기본값은 API 30이므로 구분해야 합니다.
• 공개 자동화: .github/workflows/cla.yml은 CLA 서명 처리이며 contributor-assistant/github-action@v2.6.1을 사용합니다. 여기에 빌드·호환성 CI가 있다고 읽으면 안 됩니다.
• 공개 검사: debug/AgslRenderingSmoke.java와 debug/LayerColorFilterTest.java는 픽셀 결과를 검사합니다. 전체 회귀 시험과 APK 모음은 BUILDING.md 기준 비공개입니다.

의존성 목록만 외우기보다, 각 기술이 어느 경계를 해결하고 무엇을 아직 보장하지 않는지 연결해 읽는 것이 핵심입니다.

4아키텍처 심화 분석

4-1. 시스템 전체 구조도

구조도는 책임을 구분한 그림입니다. 모든 코드가 위에서 아래로 한 번씩만 실행되는 것은 아닙니다. 앱의 Java 코드가 JNI로 네이티브 함수를 부르고, 그 네이티브 코드가 다시 Java 메서드를 호출하기도 합니다. 리소스는 화면 생성 중에도 읽힙니다.

4-2. 설계 ① 변환 파이프라인: 복잡한 문제를 단계로 나눈다

runtime/java/com/macapk/dex/DexConverter.java는 변환기의 진입점입니다. open(byte[]... dexes)로 세션을 만들고, Session.classBytes()로 한 클래스를, convertAll()로 전체를 변환합니다. 세션은 여러 DEX의 클래스를 모아 부모 타입과 중첩 클래스 관계를 함께 판단합니다.

왜 이름만 바꿔서는 안 될까요? DEX는 레지스터 기반이고, JVM 명령은 피연산자 스택을 사용하기 때문입니다. 같은 덧셈도 값을 어디에서 꺼내고 어디에 남길지 다시 표현해야 합니다. 아래는 개념 설명용 대응이며 실제 변환 출력의 복사본은 아닙니다.

# DEX 개념: v2에 v0 + v1을 저장
add-int v2, v0, v1

# JVM 개념: 두 값을 스택에 올려 더한 뒤 로컬 슬롯에 저장
iload_0
iload_1
iadd
istore_2

Session은 BATCH=512, MAX_THREADS=8로 전체 변환의 배치와 병렬도를 제한합니다. 출력 클래스를 전부 쥐고 있기보다 forEach()의 소비자에게 넘기는 통로도 둡니다. 컴파일러를 공부하면서 메모리 사용과 동시성까지 함께 볼 수 있는 부분입니다.

실패 처리도 읽을 만합니다. Translator.emitUnsupportedBody()는 처리하지 못하는 메서드에 UnsupportedOperationException을 던지는 몸체를 만들 수 있습니다. “클래스를 로드했다”와 “그 안의 모든 메서드가 올바르게 작동한다”는 서로 다른 성공 조건입니다.

4-3. 같은 네이티브 코드라도 ARM64와 ARM32는 다르다

주의해서 읽을 오래된 설명: runtime/translator/CMakeLists.txt의 첫 주석에는 LLVM IR과 외부 clang 경로가 남아 있습니다. 그러나 실제 runtime/translator/src/main.cpp의 ARM32 분기는 arm32rc가 유일한 코드 생성기라고 명시하고, runtime/translator/README.md도 직접 Mach-O 생성을 설명합니다. 빌드 파일의 오래된 주석보다 현재 분기와 호출을 우선해야 합니다.

4-4. 설계 ② 어댑터: Android의 겉모양, macOS의 실제 기능

runtime/java/android/webkit/WebView.java는 Android 앱에 익숙한 인터페이스를 제공합니다. 내부 MacApkWebViewBridge.nativeCreate()가 JNI 경계를 넘어가면 runtime/src/webview_bridge.mm::NativeCreate()가 WKWebViewConfiguration을 만들고 호스트 WebKit 뷰를 준비합니다.

// MacApkWebViewBridge.java의 실제 선언 일부
static native void nativeCreate(int viewId, String pkg,
                                String userAgent, boolean jsEnabled);
static native void nativeDestroy(int viewId);

네이티브 구현은 dispatch_async(dispatch_get_main_queue(), ...)로 AppKit 주 스레드에 작업을 보냅니다. 반대쪽 이벤트는 Java의 Handler로 WebView의 UI 스레드에 전달합니다. API 결과만 맞추는 어댑터가 아니라 실행 스레드의 규칙까지 맞추는 어댑터인 셈입니다.

4-5. 설계 ③ 캐시: 파일의 존재보다 만들어진 조건을 확인한다

runtime/src/apk_unpacker.cpp::CacheIsFresh()는 .source-mtime에 적힌 APK 수정 시각, ABI 선택, JAVA_ID를 확인합니다. classes.jar의 존재만 보지 않고, DEX가 없는 앱이나 지연 변환 경로도 따로 처리합니다. 불완전한 결과를 정상 캐시로 오인하지 않으려는 설계입니다. 다만 현재 JAVA_ID를 구하지 못하면 경고를 남기고 식별값 비교를 생략합니다.

runtime/scripts/build_ids.py는 변환기와 프레임워크의 빌드 식별값을 분리합니다. 프레임워크 메서드의 내부 구현을 고친 것과 부모 타입·인터페이스 구조를 고친 것은 변환 결과에 미치는 영향이 다릅니다. JAVA_ID는 변환기, 클래스 형태, JDK 버전에 기반하고, NATIVE_ID는 translator·Bionic shim 산출물의 캐시를 구분합니다.

# 소스의 책임을 요약한 개념식: 실제 해시 문자열은 생략
CONVERTER_ID = 변환기 바이트코드 + 변환 호출 방식
FRAMEWORK_ID = 클래스 이름·접근 플래그·부모·인터페이스 + JDK 버전
JAVA_ID      = f(CONVERTER_ID, FRAMEWORK_ID)
NATIVE_ID    = 네이티브 변환기 + shim 내용

# “파일이 있다”만으로 재사용하지 않는다
DEX 캐시 재사용(현재 식별값을 알 때)
  = APK 조건 일치 + ABI 조건 일치 + 변환 식별값 일치

선택 기능도 놓치지 마세요. LazyDexEnabled()에서 MACAPK_LAZY_DEX가 없으면 false입니다. 지연 변환을 기본이라고 설명하면 틀립니다. 다만 전체 변환이 실패해 lazydex 상태로 대체되는 예외 경로도 있습니다. runtime/java/dalvik/system/LazyDexSource.java는 필요해진 클래스만 변환하고 없는 클래스의 조회 결과도 캐시합니다.

4-6. 설계 ④ 공유 런타임과 중단 복구가 가능한 설치

launcher/AppStubMain.swift::main()은 앱별 작은 실행 파일에서 공용 런타임으로 execv()합니다. 실행 파일을 다른 프로그램으로 바꾸는 방식이므로, 앱마다 JVM·그래픽 라이브러리 전체를 복제할 필요가 줄어듭니다. BundleGenerator.generate()는 작은 stub과 앱 정보로 .app을 구성합니다.

각 이동은 같은 디렉토리의 이름 변경을 활용하지만, 설치 전체가 단일 원자 연산은 아닙니다. 여러 이동 사이에 중단될 수 있어서 recoverInterruptedSwap()가 필요합니다. 이전 데이터를 인계하지 못했으면 .previous를 삭제하지 않고 다음 시도를 위해 보존합니다. 현재 앱 데이터는 번들 밖의 ~/Library/Application Support/MacApk/에 저장됩니다. 교체 과정은 이를 가리키는 Contents/android 링크나 이전 버전의 내부 데이터 폴더도 보존합니다.

이 아키텍처에서 재사용할 만한 생각은 “무엇을 공유하고, 어떤 조건에서 다시 만들며, 실패하면 무엇을 남길까”를 명시하는 습관입니다.

입문자는 먼저 WebView 어댑터와 설치 상태 전이를 읽고, 그다음 DEX 변환기로 들어가세요. 처음부터 ARM64 로더 전체를 따라가면 포인터·메모리 매핑·재배치·신호 처리 문제가 한꺼번에 등장합니다.

5디렉토리 구조 해부

5-1. 증상에서 폴더로 거꾸로 찾아가기

ResourceIndex는 설치된 APK와 split APK의 리소스 테이블·ZIP 항목을 다룹니다. 현재 경로를 “apktool로 모든 XML을 풀어 놓고 폴더를 읽는다”고만 설명하면 오래된 구조를 옮기게 됩니다. ArscReader·BinaryXmlParser와 실제 리소스 선택 코드를 함께 읽어야 합니다.

5-2. 코드 규모와 집계 범위

커밋 5a503e1의 확장자별 물리 줄 수이며, 파일 끝에 개행이 없는 마지막 줄도 1줄로 셉니다. 다음 표는 경로 구성요소가 thirdparty인 폴더를 모두 제외한 값입니다. 빈 줄·주석·생성 코드·API 스텁·JDK 패치도 포함하므로, 순수한 자체 구현량이나 완성도를 뜻하지 않습니다.

thirdparty 경로까지 포함하면 같은 확장자 범위에서 3,246개 파일, 840,519줄입니다. CMake·JSON·문서·바이너리는 이 집계에서 제외했습니다. 특히 사전 빌드 라이브러리의 원본 구현량은 바이너리 크기만으로 환산할 수 없습니다.

가장 넓은 Java 코드 영역은 runtime/java/의 578,305줄입니다. 하지만 처음부터 모두 읽을 필요는 없습니다. 증상 하나 → 진입 함수 하나 → 관련 인터페이스 하나로 좁히는 것이 이 규모의 저장소를 읽는 현실적인 방법입니다.

6학습 포인트 (기술별)

6-1. Java: API 모양과 실제 행동은 별개다

먼저 runtime/java/com/google/firebase/analytics/FirebaseAnalytics.java를 보세요. logEvent()는 공개 메서드로 존재하지만 이벤트를 서버로 전송하지 않습니다. 일부 SDK를 멈추지 않게 하려고 호출 표면만 유지하는 스텁을 제공하는 사례입니다.

// FirebaseAnalytics.java의 실제 구현 일부
public void setUserProperty(String name, String value) {}
public void setUserId(String id) {}
public void setAnalyticsCollectionEnabled(boolean enabled) {}

앱이 이 메서드를 찾을 수 있다는 사실과 Firebase 분석 서비스가 실제 작동한다는 사실은 다릅니다. 같은 기준으로 Android API 구현도 읽어 보세요. 빈 몸체, 고정 반환값, 호스트 브리지 호출, 완전한 상태 관리 중 어느 유형인지 구분하면 호환성의 깊이가 보입니다.

6-2. 클래스 로더: 이름이 같아도 어디서 왔는지가 중요하다

AppClassLoader.findClass()는 클래스 이름의 슬래시를 점으로 정규화하고, 필요한 재작성과 정의를 거칩니다. 지연 DEX 경로에서도 ClassFileRewriter.maybeRewrite()를 통과합니다. 변환 방식이 달라져도 공통으로 코드를 보정하는 지점을 유지하는 설계를 볼 수 있습니다.

findLibrary()는 System.loadLibrary()에 대응하는 네이티브 라이브러리 위치를 찾습니다. 따라서 ClassNotFoundException과 네이티브 라이브러리 로딩 오류는 서로 다른 질문으로 출발해야 합니다. 클래스 파일과 .so를 같은 탐색 경로라고 생각하지 마세요.

• 배울 것: 부모 로더에 위임하는 규칙, 클래스 정의, 이름 정규화, Java와 네이티브 탐색의 차이.
• 실습 아이디어: findClass()에서 JAR·지연 DEX·상위 구현으로 갈라지는 분기를 종이에 그립니다.
• 확인 질문: 같은 클래스가 두 번 정의되면 왜 문제가 되는지, 정의 전에 어떤 조회가 필요한지 설명해 봅니다.

6-3. 컴파일러: 타입은 분기와 예외를 따라 흘러간다

runtime/java/com/macapk/dex/TypeInference.java는 각 명령 진입 시점의 레지스터 타입을 추론합니다. 한 명령의 결과를 다음 명령으로 전달하고, 여러 경로가 합쳐지는 곳에서는 상태를 병합합니다. 더 이상 상태가 바뀌지 않을 때까지 반복하는 고정점 계산입니다.

특히 예외 경로를 보세요. 명령 실행 도중 실패할 수 있으므로 예외 처리기로 전달할 상태는 그 명령이 완성된 뒤의 결과가 아닙니다. 소스 주석과 상태 전파 코드는 명령 실행 전 상태를 강조합니다. 이것이 단순 opcode 치환보다 변환기가 훨씬 복잡한 이유입니다.

• 배울 것: 기본 블록, 합류, 공통 상위 타입, 예외 간선, JVM 스택 맵.
• 실습 아이디어: 대입 하나와 분기 하나, 예외 하나를 만든 뒤 명령별 “실행 전·후 타입” 표를 손으로 작성합니다.
• 완료 기준: 예외 처리기가 아직 계산되지 않은 결과를 이미 가진 것으로 취급하면 어떤 오류가 생기는지 설명합니다.

6-4. C++·운영체제: 포인터와 파일 형식이 만나는 지점

runtime/translator/src/elf64_reader.cpp와 arm64_native.cpp를 연결해 읽으면 파일의 바이트가 메모리의 실행 가능한 영역으로 바뀌는 과정을 볼 수 있습니다. 로더는 “파일을 연다”에서 끝나지 않습니다. 영역을 배치하고, 주소를 고치고, 외부 심볼을 찾고, 초기화 함수를 실행해야 합니다.

ARM32 경로는 포인터 폭이 추가 난점입니다. 32비트 게스트가 생각하는 주소와 64비트 호스트의 실제 포인터를 연결해야 합니다. runtime/translator/src/arm32rc/regmap.cpp는 게스트 레지스터와 호스트 레지스터의 대응을 다룹니다. 처음에는 코드 생성 세부보다 입력 상태·출력 상태·보존할 레지스터만 표로 정리해도 충분합니다.

실습 아이디어: 동적 라이브러리를 설명하는 카드에 “CPU 아키텍처, 파일 형식, 외부 심볼, 초기화 함수” 네 항목을 적고 ELF와 Mach-O의 차이를 정리합니다. 실제 바이너리를 실행하지 않아도 로더의 책임을 공부할 수 있습니다.

6-5. 그래픽: GPU를 쓰는 것과 전송 비용은 함께 봐야 한다

MacApkSkia.java의 GpuEngine은 Metal 장치·큐와 Skia 컨텍스트를 만듭니다. 렌더 타깃 풀은 TARGET_CACHE_COUNT=8, TARGET_CACHE_BYTES=64L * 1024 * 1024로 제한합니다. target()에서 오래된 타깃을 내보내고, finish()에서 너무 큰 일회성 타깃의 보유를 정리합니다.

BUILDING.md는 셰이더·효과의 GPU 결과를 Java2D Canvas용으로 다시 읽는다고 설명합니다. 빠른 GPU 연산 뒤에도 결과를 CPU 쪽으로 가져오는 readback과 동기화 비용이 남습니다. 일반 Canvas 전체를 Metal로 옮겼다는 설명과 구분해야 합니다.

• 배울 것: 렌더 타깃 수명, GPU·CPU 동기화, 알파 합성, 색 공간, 캐시 용량 제한.
• 실습 아이디어: AgslRenderingSmoke.transparentTiles()에서 투명한 결과가 이전 프레임의 불투명 픽셀을 남기지 않는지 어떻게 검사하는지 읽습니다.
• 확인 질문: 메모리를 재사용하면서 초기화를 잘못하면 왜 이전 그림의 흔적이 나타날까요?

6-6. Swift·제품 설계: 성공보다 실패 뒤 상태를 먼저 그린다

BundleGenerator.generate()의 정상 경로와 recoverInterruptedSwap()의 복구 경로를 나란히 읽으세요. 새 번들을 준비하는 책임과 기존 데이터를 인계하는 책임을 나눕니다. InstallPipeline.Hooks에 클로저로 번들 동작을 연결하는 부분에서는 UI와 공통 설치 로직을 분리하는 방법도 보입니다.

학습할 핵심은 Swift 문법보다 실패했을 때 지우면 안 되는 데이터입니다. “오류를 잡았다”는 것만으로 복구가 되지는 않습니다. 사용자의 유일한 데이터가 있는 폴더를 보존하고, 다음 실행에서 그 상태를 알아볼 수 있어야 합니다.

기능이 한 번 성공하는 코드를 넘어, 실패해도 진단하고 다시 시도할 수 있는 코드를 읽는 것이 이 저장소의 가장 실용적인 공부입니다.

7하드웨어 / 시스템 요구사항

7-1. 배포 앱을 사용하는 조건

runtime/src/jvm_loader.cpp에는 -Xmx1g 설정이 있습니다. 이것은 Java 힙의 상한 설정이며, 프로세스 전체 메모리나 Mac의 최소 RAM이 1 GB라는 뜻이 아닙니다. 네이티브 코드·그래픽 메모리·JIT·공유 라이브러리 등은 별도 영역을 사용합니다.

7-2. 왜 macOS 26.4가 경계인가

BUILDING.md는 ARM64 경로에 com.apple.security.custom-x18-abi-toggle entitlement가 필요하고, 이 기능 때문에 26.4를 최소로 둔다고 설명합니다. runtime/scripts/jit-entitlements.plist에 해당 키가 있으며, arm64_native.cpp::macapk_x18_capability_ok()는 실제 보존 능력을 검사하고 조건이 맞지 않으면 로딩을 거부합니다.

CMake의 CMAKE_OSX_DEPLOYMENT_TARGET과 Swift 컴파일 대상에는 26.0이 보입니다. 이 값만 보고 제품이 26.0부터 동작한다고 결론 내리면 안 됩니다. 번들의 최소 OS 선언과 실행 중 기능 검사가 더 높은 조건을 요구합니다.

7-3. 소스 개발을 위한 조건

• 기본 도구: macOS 26.4 이상과 Apple Silicon, Xcode Command Line Tools, Homebrew, CMake, OpenJDK 21, Capstone, apktool. 근거는 BUILDING.md입니다.
• 플랫폼 리소스: AOSP 리소스를 준비할 때 aapt2가 필요합니다. 문서는 Android SDK build-tools 36.0.0을 사용한 API 36 절차를 제시합니다.
• 선택 기능: libpng·libvpx가 없으면 관련 기능을 빼거나 경고하며 진행하는 분기가 있습니다. 빌드에 성공해도 포함된 기능은 다를 수 있습니다.
• ANGLE 재빌드: 사전 빌드본을 쓰면 보통 불필요합니다. 직접 재빌드하는 경우에만 문서 기준 Xcode 26 전체와 Metal toolchain, 약 25 GB·30~60분의 준비 비용이 추가됩니다.
• 공유 런타임: 빌드된 파일과 설치 앱이 사용하는 공유 런타임은 별개입니다. BUILDING.md는 빌드만으로 공유 런타임이 갱신되지 않는다고 명시합니다.

코드를 읽는 데 필요한 환경과 APK를 실제로 실행하는 데 필요한 환경은 다르므로, 입문 학습은 읽기·상태도 작성만으로도 시작할 수 있습니다.

8직접 해볼 수 있는 실습 과제

다음 과제는 커밋 5a503e1의 파일을 읽고 표·그림·설계안을 만드는 방식입니다. 명령 예시는 저장소 루트 기준의 읽기 전용 탐색입니다. 빌드·설치·APK 실행은 요구하지 않습니다. 각 과제의 결과에는 근거 파일과 함수 이름을 함께 남기세요.

# 진입점과 Java 쪽 인계 지점 찾기
rg -n 'int main|Boot.run|CallStaticVoidMethod' runtime/src/main.cpp
rg -n 'public static void run' runtime/java/com/macapk/loader/Boot.java
rg -n 'classBytes|convertAll' runtime/java/com/macapk/dex/DexConverter.java

# 실행이 아니라 판단 근거가 있는 줄을 찾는 명령
rg -n 'CacheIsFresh|EffectiveAbiSelector|GetBuildIdentity' runtime/src/apk_unpacker.cpp
rg -n 'CONVERTER_ID|FRAMEWORK_ID|JAVA_ID|NATIVE_ID' runtime/scripts/build_ids.py
rg -n 'nativeIdMatches|findLibrary' runtime/java/com/macapk/loader/AppClassLoader.java

9관련 기술 심화 학습 로드맵

Java의 클래스·인터페이스·예외와 파일 읽기를 알고 있다면 다음 순서로 접근할 수 있습니다. 주당 3~5시간을 가정한 학습 제안이며, 저장소 전체를 여섯 주 만에 이해한다는 일정은 아닙니다. 매주 하나의 개념과 하나의 결과물만 가져가는 편이 좋습니다.

9-1. 3주차까지의 우선 목표: 호출을 왕복으로 설명하기

보통은 Java에서 네이티브로 들어가는 화살표만 그립니다. 그러나 UI는 “페이지 열기 요청 → 호스트 처리 → 페이지 완료 이벤트 → 앱 콜백”이라는 왕복입니다. MacApkWebViewBridge의 이벤트 코드와 Handler 전달까지 포함해야 비동기 API의 약속을 설명할 수 있습니다.

위 그림은 스레드 경계를 익히기 위한 개념도입니다. 실제 이벤트별 전달 규칙은 MacApkWebViewBridge.java에 따로 있습니다. JavaScript 인터페이스 호출은 전용 백그라운드 큐를 사용하므로 모든 콜백을 같은 UI 스레드라고 묶으면 안 됩니다.

9-2. 4~5주차의 우선 목표: 하나의 변환만 깊게 보기

처음에는 정수 덧셈·조건 분기·반환만 대상으로 삼으세요. 그다음 객체 생성과 예외를 더합니다. ARM 네이티브 쪽도 정수 계산과 함수 호출부터 시작하고, 신호·스레드·SIMD는 뒤로 미룹니다. 읽는 범위를 좁히면 변환 전후 상태를 끝까지 확인할 수 있습니다.

한 함수를 입력부터 출력까지 정확히 설명하는 경험이, 수십만 줄을 훑고 이름만 기억하는 것보다 다음 단계로 이어집니다.

9-3. 관심 분야에 따른 다음 갈림길

• 앱·UI 개발: Activity 수명주기, Handler·Looper, WebView·입력·리소스 선택을 더 읽습니다. 상태와 콜백 순서를 중심으로 봅니다.
• 컴파일러: 타입 격자, 스택 맵, 메서드 크기 제한, 예외 처리 구간, 다중 DEX 관계를 공부합니다.
• 시스템 개발: 동적 링커, 메모리 매핑 권한, TLS, ABI, 신호 처리와 게스트·호스트 주소 대응을 공부합니다.
• 제품·인프라: 공유 런타임 배포, 의존성 재연결, 코드 서명, 설치 복구, 재현 가능한 산출물 식별을 공부합니다.

10핵심 키워드 사전

키워드를 암기할 때는 정의 옆에 근거 파일 하나를 붙이세요. 예를 들어 “JNI → jvm_loader.cpp와 MacApkWebViewBridge.java”, “캐시 무효화 → CacheIsFresh()”처럼 연결하면 실제 문제를 만났을 때 찾아가기 쉽습니다.

11참고 링크

11-1. 프로젝트 공식 자료

• Mac.apk 공식 저장소 — 이슈·기여·프로젝트 개요의 출발점.
• README — 커밋 5a503e1 — 제품 주장, 최소 OS, 설치 공간, 실행 권한의 범위.
• 소스 빌드 안내 — 도구 조건, 리소스 준비, 공개 검사와 누락 데이터.
• 앱 호환성 목록 — 앱·버전별 동작과 세부 결함. 문서 갱신일은 2026-10-20.
• 공식 Wiki — 설치·입력·창·권한·고급 설정 문서. 본문 구현 해설의 기준 커밋과 별도로 갱신될 수 있음.
• v1.0.2303 릴리스 — 2026-10-21 공개된 분석일 기준 최신 릴리스.
• AGPL 라이선스 원문 · 공식 상용 라이선스 안내 · 제3자 소프트웨어 고지.

11-2. 본문에서 읽은 핵심 구현

• runtime/src/main.cpp · jvm_loader.cpp — 프로세스 진입, JVM 생성, Java 부팅으로의 인계.
• Boot.java · AppClassLoader.java — 앱 환경과 Java·네이티브 로딩.
• DexConverter.java · TypeInference.java · Translator.java — 4주차 컴파일러 학습의 중심.
• apk_unpacker.cpp · build_ids.py — 캐시 재사용 조건과 변환 산출물 정체성.
• MacApkWebViewBridge.java · webview_bridge.mm — Java와 호스트 UI의 왕복 연결.
• arm64_native.cpp · arm32rc_driver.h — ARM64 로딩과 ARM32 코드 생성의 차이.
• BundleGenerator.swift · AppStubMain.swift — 공유 런타임과 설치 중단 복구.
• MacApkSkia.java · AgslRenderingSmoke.java · LayerColorFilterTest.java — 그래픽 자원 관리와 픽셀 검사.
• 런타임 CMake 설정 · translator CMake 설정 · 공개 GitHub Actions 설정 — 실제 빌드 기준과 자동화 범위.
• ANGLE·MoltenVK 출처 · Skiko·Skia 출처 — 버전·커밋·패치·바이너리 이력.

11-3. 기반 기술의 공식 문서

• AOSP: Dalvik 바이트코드 — DEX의 레지스터 모델과 명령 의미.
• JVM 명세 21: 가상 머신 구조 — 로컬 변수, 피연산자 스택, 프레임과 실행 모델.
• Java Native Interface 명세 — Java와 네이티브 호출의 규칙을 더 공부할 때.
• ANGLE 공식 저장소 · MoltenVK 공식 저장소 — 그래픽 API 번역과 Metal 연결.
• Skiko 공식 저장소 — Skia 네이티브 런타임의 출처를 따라갈 때.
• Android Emulator · Waydroid — 가상 기기·컨테이너 방식과 구조를 비교할 때.
• dex2jvm — Mac.apk 문서가 별도 프로젝트로 소개하는 DEX 변환기. 버전 차이가 있을 수 있어 본문 근거는 Mac.apk 내부 코드로 한정.
• TrendShift — 저장소 관심도 흐름을 살펴보는 출발점.

현재 상태 (2026-10-23 확인)