Python 기반 모바일 애플리케이션을 Windows 환경에서 직접 APK로 패키징하는 것은 공식적으로 지원되지 않습니다. 이를 해결하기 위해 Windows Subsystem for Linux(WSL)를 활용하면 리눅스 기반 빌드 도구체인을 그대로 사용할 수 있습니다. 본 문서는 Ubuntu 기반 WSL 환경에서 Kivy와 Buildozer를 통해 Python 코드를 Android 앱(APK)으로 변환하는 절차를 설명합니다.

WSL 환경 설정

먼저 WSL 기능을 활성화해야 합니다. Windows 설정 → 앱 → 프로그램 및 기능 → Windows 기능 켜기/끄기에서 Linux용 Windows 하위 시스템을 선택하고 시스템을 재시작합니다.

다음으로 Microsoft Store에서 원하는 배포판을 설치합니다. 본 가이드에서는 Ubuntu를 기준으로 진행합니다. 설치 후 처음 실행 시 사용자 이름과 비밀번호를 설정하세요.

Kivy 설치 및 검증

터미널을 열고 다음 명령어로 Kivy를 설치합니다:

pip install kivy

설치 중 다음과 같은 오류가 발생할 수 있습니다:

kivy/include/gl_redirect.h:72:13: fatal error: GL/gl.h: No such file or directory

이 경우 OpenGL 관련 헤더 파일이 누락된 것이므로, 다음 명령어로 개발 패키지를 추가 설치합니다:

sudo apt update
sudo apt install mesa-common-dev libgl1-mesa-dev libglu1-mesa-dev

다시 pip install kivy를 실행하면 정상적으로 설치됩니다.

설치 확인을 위해 간단한 테스트 앱을 작성합니다:

from kivy.app import App
from kivy.uix.button import Button

class MyApp(App):
    def build(self):
        return Button(text='Hello, Kivy!')

MyApp().run()

실행 시 OpenGL 버전이 낮아 오류가 발생할 수 있으나, 이는 개발 단계에서는 무시해도 무방하며 최종 APK 빌드에는 영향을 주지 않습니다.

Buildozer 설치 및 초기화

APK 생성을 위해 Buildozer를 설치합니다:

pip install buildozer

프로젝트 디렉터리로 이동하여 설정 파일을 생성합니다:

cd /mnt/c/Users/YourName/your_project
buildozer init

정상적으로 완료되면 buildozer.spec 파일이 생성됩니다. 이 파일은 앱 메타데이터와 빌드 옵션을 정의합니다.

buildozer.spec 설정 수정

주요 수정 항목은 다음과 같습니다:

• title: 앱 이름 (예: MyKivyApp)
• package.name: 패키지 식별자 (영문 소문자만 가능, 예: mykivyapp)
• version: 앱 버전 (예: 0.1)
• requirements: 종속성 목록 (예: kivy,numpy)
• presplash.filename: 스플래시 이미지 경로 (PNG 또는 JPG)
• icon.filename: 앱 아이콘 경로 (512x512 PNG 권장)
• orientation: 화면 방향 (all, portrait, landscape)
• fullscreen: 전체 화면 여부 (1 또는 0)
• android.api, android.minapi, android.sdk, android.ndk: Android 플랫폼 설정
• log_level: 로그 수준 (2 추천, 디버깅 용이)

빌드 전 필수 의존성 설치

Buildozer가 원활히 동작하려면 추가 시스템 패키지가 필요합니다:

sudo apt install -y build-essential ccache git libncurses5:i386 libstdc++6:i386
sudo apt install -y openjdk-8-jdk

Java 컴파일러(javac)가 없다는 오류가 발생하면 JDK 설치가 누락된 것입니다. 위 명령어로 해결 가능합니다.

APK 빌드 실행

모든 준비가 완료되면 다음 명령어로 빌드를 시작합니다:

buildozer -v android debug

이 과정에서 자동으로 Android SDK, NDK, 그리고 기타 빌드 도구들이 다운로드되고 설정됩니다. 첫 빌드 시 네트워크 상태에 따라 수십 분 이상 소요될 수 있으며, 전체 저장 공간은 약 5GB 이상 필요할 수 있습니다.

빌드 문제 해결 팁

• 네트워크 차단: 중국 지역처럼 특정 자원 접근이 제한되는 경우, 프록시 또는 미러를 활용하세요.
• 라이브러리 링킹 오류: "xyz.so not found" 오류 발생 시 시스템 내 존재하는 라이브러리를 심볼릭 링크로 연결합니다:

  locate xyz.so
  sudo ln -s /path/to/existing/xyz.so /usr/lib/xyz.so
  

• 사용자 권한 경고: WSL에서 root로 실행 시 표시되는 경고는 일반적으로 무시해도 무방하지만, 별도의 사용자를 생성해 실행하는 것이 안정적입니다.

결과물 확인

성공적으로 빌드가 완료되면 프로젝트 폴더 내 bin/ 디렉터리에 *-debug.apk 파일이 생성됩니다. 해당 파일을 Android 기기에 설치하여 실행 가능합니다.