Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

Android로 컴파일하기

더 보기

이 페이지는 소스로부터 Android 내보내기 템플릿 바이너리를 컴파일하는 방법을 설명합니다. 프로젝트를 Android로 내보내고자 한다면, 대신 Android로 내보내기를 읽으세요.

참고

대부분의 경우 내장된 배포자 및 내보내기 템플릿을 사용하면 충분합니다. Android APK를 수동으로 컴파일하는 것은 배포자를 위한 맞춤 빌드 또는 맞춤 패키지에 주로 유용합니다.

또한 사용자 정의 내보내기 템플릿을 구축하기 전에 Android로 내보내기 튜토리얼에 언급된 단계를 따라야 합니다.

요구 사항

Windows, Linux 또는 macOS에서 컴파일하려면 다음이 필요합니다:

  • Python 3.9+.

  • SCons 4.4+ build system.

  • Android

    • To install the Android SDK, follow the steps here.

    • Linux에서는 배포판의 저장소에서 제공되는 Android SDK는 때때로 오래되었을 것이므로 사용하지 마세요.

    • macOS에서는 홈브류가 제공하는 Android SDK는 통합된 위치에 설치되지 않을 것이므로 사용하지 마세요.

  • Gradle (누락된 경우 자동으로 다운로드 및 설치됩니다).

  • JDK 17 (OpenJDK 또는 Oracle JDK 중 하나).

    • Adoptium에서 빌드를 다운로드할 수 있습니다.

더 보기

컴파일을 위한 Godot 소스 코드를 얻으려면 :ref:`doc_getting_source`를 참조하세요.

Godot의 SCons 사용법에 대한 일반적인 개요는 :ref:`doc_introduction_to_the_buildsystem`를 참조하세요.

빌드시스템 설정하기

  • Android SDK를 가리키도록 환경 변수 ``ANDROID_HOME``를 설정합니다. Android 명령줄 도구를 다운로드한 경우 이 폴더는 ZIP 아카이브의 콘텐츠를 추출한 폴더입니다.

    • Windows: :kbd:`Windows + R`을 누르고 "제어 시스템"을 입력한 다음 왼쪽 창에서 **고급 시스템 설정**을 클릭하고 나타나는 창에서 **환경 변수**를 클릭합니다.

    • Linux 또는 macOS: .bashrc 또는 .zshrc``에 ``export ANDROID_HOME="/path/to/android-sdk" 텍스트를 추가합니다. 여기서 ``/path/to/android-sdk``는 SDK 디렉터리의 루트를 가리킵니다.

  • SDK 및 환경 변수를 설정한 후 변경 사항을 적용하려면 **터미널을 다시 시작**해야 합니다. 통합 터미널이 있는 IDE를 사용하는 경우 IDE를 다시 시작해야 합니다.

  • ``scons platform=android``를 실행합니다. 실패하면 돌아가서 단계를 확인하세요. 설정을 올바르게 완료했다면 NDK 다운로드가 시작됩니다. GDExtension을 컴파일하려는 경우 먼저 엔진을 컴파일하여 NDK를 다운로드한 다음 GDExtension을 컴파일할 수 있습니다.

내보내기 템플릿 구축

Godot에는 최적화된 "릴리스" 템플릿(android_release.apk), 디버그 템플릿(android_debug.apk), Gradle 빌드 템플릿(android_source.zip) 등 세 가지 Android용 내보내기 템플릿이 필요합니다. Google에서는 2019년 8월부터 모든 APK에 ARMv8(64비트) 라이브러리를 포함하도록 요구하므로 아래 명령은 ARMv7 및 ARMv8 라이브러리를 모두 포함하는 템플릿을 빌드합니다.

표준 내보내기 템플릿 컴파일은 다음 인수를 사용하여 Godot 루트 디렉터리에서 SCons를 호출하여 수행됩니다:

  • 릴리스 템플릿(**디버깅 활성화**를 선택하지 않은 상태로 내보낼 때 사용됨)

scons platform=android target=template_release arch=arm32
scons platform=android target=template_release arch=arm64 generate_android_binaries=yes

  • 디버그 템플릿(**디버깅 활성화**를 선택한 상태로 내보낼 때 사용됨)

scons platform=android target=template_debug arch=arm32
scons platform=android target=template_debug arch=arm64 generate_android_binaries=yes

결과 템플릿은 bin 디렉터리에 위치합니다.

  • 릴리스 템플릿의 경우 bin/android_release.apk

  • 디버그 템플릿의 경우 bin/android_debug.apk

  • Gradle 빌드 템플릿의 경우 bin/android_source.zip

참고

  • 빌드 중인 아키텍처 목록을 변경하는 경우 빌드 중인 마지막 아키텍처에 ``generate_android_binaries=yes``를 추가하여 빌드 후에 템플릿 파일이 생성되도록 해야 합니다.

  • To enable dev build (for use when troubleshooting) in the generated templates, add the dev_build=yes parameters to the SCons command.

  • 생성된 템플릿에 디버그 기호를 포함하려면 SCons 명령에 debug_symbols=yes 매개변수를 추가합니다.

    • separate_debug_symbols=yes``를 포함하여 별도의 ``*-native-debug-symbols.zip 파일에 디버그 기호를 생성할 수 있습니다.

더 보기

Vulkan 검증 레이어를 활성화하려면 :ref:`Android의 Vulkan 검증 레이어 <doc_vulkan_validation_layers_android>`를 참조하세요.

x86 기기에 대한 지원 추가하기

x86 및 x86_64 기기에 대한 지원도 포함하려면 Gradle로 APK를 빌드하기 전에 arch=x86_32 및 arch=x86_64 인수를 사용하여 SCons 명령을 세 번째 및 네 번째로 실행하세요. 예를 들어 릴리스 템플릿의 경우:

scons platform=android target=template_release arch=arm32
scons platform=android target=template_release arch=arm64
scons platform=android target=template_release arch=x86_32
scons platform=android target=template_release arch=x86_64 generate_android_binaries=yes

그러면 모든 플랫폼에서 작동하는 템플릿 바이너리가 생성됩니다. 내보낸 프로젝트의 최종 바이너리 크기는 내보낼 때 지원하도록 선택한 플랫폼에 따라 달라집니다. 즉, 사용하지 않는 플랫폼은 바이너리에서 제거됩니다.

생성된 내보내기 템플릿 정리하기

다음 명령을 사용하여 생성된 내보내기 템플릿을 제거할 수 있습니다.

cd platform/android/java
# On Windows
.\gradlew clean
# On Linux and macOS
./gradlew clean

내보내기 템플릿 사용하기

Godot는 편집기와 동일한 버전/커밋에 대해 컴파일된 릴리스 및 디버그 바이너리가 필요합니다. 편집기용 공식 바이너리를 사용하는 경우 일치하는 내보내기 템플릿을 설치하거나 동일한 버전에서 직접 빌드하세요.

게임을 내보낼 때 Godot는 템플릿을 기본으로 사용하고 필요에 따라 콘텐츠를 업데이트합니다.

템플릿 설치하기

새로 컴파일된 템플릿(android_debug.apk, android_release.apk, android_source.zip)은 각각의 이름과 함께 Godot의 템플릿 폴더에 복사되어야 합니다. 템플릿 폴더는 다음 위치에 있습니다.

  • Windows: %APPDATA%\Godot\export_templates\<버전>\

  • Linux: $HOME/.local/share/godot/export_templates/<버전>/

  • macOS: $HOME/Library/Application Support/Godot/export_templates/<버전>/

<version>``는 Godot 소스 저장소(예: ``4.1.3.stable 또는 4.2.dev)에 있는 version.py``의 값을 사용하여 ``major.minor[.patch].status 형식입니다. 또한 내보내기 템플릿 옆에 있는 version.txt 파일에 동일한 버전 문자열을 작성해야 합니다.

그러나 사용자 정의 모듈이나 사용자 정의 C++ 코드를 작성하는 경우 대신 프로젝트 내보내기 메뉴에서 템플릿 바이너리를 사용자 정의 내보내기 템플릿으로 구성할 수 있습니다. 이를 설정하려면 **고급 옵션**을 활성화해야 합니다.

../../../_images/andtemplates.webp

복사할 필요도 없으며 Godot 소스 폴더의 bin\ 디렉터리에 있는 결과 파일을 참조하면 다음 번 빌드 시 자동으로 사용자 정의 템플릿이 참조됩니다.

Godot 편집기 빌드하기

편집기 컴파일은 다음 인수를 사용하여 Godot 루트 디렉터리에서 SCons를 호출하여 수행됩니다:

scons platform=android arch=arm32 production=yes target=editor
scons platform=android arch=arm64 production=yes target=editor
scons platform=android arch=x86_32 production=yes target=editor
scons platform=android arch=x86_64 production=yes target=editor generate_android_binaries=yes

  • dev_build=yes 매개변수를 추가하여 Godot 편집기의 개발 빌드를 생성할 수 있습니다.

  • debug_symbols=yes 매개변수를 추가하여 생성된 빌드에 디버그 기호를 포함할 수 있습니다.

    • 빌드 중인 마지막 아키텍처에 separate_debug_symbols=yes``를 포함하여 별도의 ``*-native-debug-symbols.zip 파일에 디버그 기호를 생성할 수 있습니다.

  • 컴파일 속도를 높이기 위해 대상 장치에 따라 특정 아키텍처를 건너뛸 수 있습니다.

빌드하는 마지막 아키텍처에 ``generate_android_binaries=yes``를 추가하여 빌드 후에 바이너리가 생성되도록 하는 것을 잊지 마세요.

결과 바이너리는 bin/android_editor_builds/ 아래에 위치합니다.

템플릿 위치시키기

외부 편집기를 설정하는 방법은 아래 구획들을 확인하세요:

 cd platform/android/java
 # On Windows
.\gradlew clean
# On Linux and macOS
./gradlew clean

편집기 실행하기

개발자 옵션이 활성화된 Android 기기를 사용하여 USB/USB-C 포트에 연결된 충전 케이블을 통해 Android 기기를 컴퓨터에 연결하세요. 터미널/명령 프롬프트를 열고 다음 인수를 사용하여 루트 디렉터리에서 다음 명령을 실행합니다.

adb install ./bin/android_editor_builds/android_editor-android-debug.apk

문제 해결

플랫폼이 SCons에 표시되지 않습니다.

ANDROID_HOME 환경 변수를 설정했는지 다시 확인하세요. 플랫폼이 SCons의 감지된 플랫폼 목록에 표시되려면 이 작업이 필요합니다. 자세한 내용은 :ref:`빌드 시스템 설정 <doc_android_setting_up_the_buildsystem>`을 참조하세요.

애플리케이션이 설치되지 않았습니다.

Android에서는 애플리케이션이 올바르게 설치되지 않았다고 불평할 수 있습니다. 그렇다면:

  • Check that the debug keystore is properly generated.

  • jarsigner 실행 파일이 JDK 8에서 생성되었는지 확인하세요.

그래도 실패하면 명령줄을 열고 `logcat <https://developer.android.com/studio/command-line/logcat>`_을 실행하세요.

adb logcat

그런 다음 애플리케이션이 설치되는 동안 출력을 확인하십시오. 거기에 오류 메시지가 표시되어야 합니다. 알아낼 수 없다면 도움을 요청하세요.

애플리케이션이 즉시 종료됩니다.

애플리케이션이 실행되지만 즉시 종료되는 경우 이는 다음 이유 중 하나 때문일 수 있습니다.

  • 편집기 버전과 일치하는 내보내기 템플릿을 사용해야 합니다. 새로운 Godot 버전을 사용한다면, 템플릿도 업데이트해야 해야 합니다.

  • ``libgodot_android.so``는 ``<arch>``가 장치 아키텍처인 ``libs/<arch>/``에 없습니다.

  • 장치의 아키텍처가 내보낸 아키텍처와 일치하지 않습니다. 템플릿이 해당 장치의 아키텍처에 맞게 구축되었는지, 내보내기 설정에 해당 아키텍처에 대한 지원이 포함되었는지 확인하세요.

어떤 경우든 ``adb logcat``는 오류의 원인도 표시해야 합니다.