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...

빌드 시스템 소개

Godot is a primarily C++ project and it uses the SCons build system. We love SCons for how maintainable and easy to set up it makes our buildsystem. 덕분에 소스에서 Godot를 컴파일하는 것은 다음을 실행하는 것만큼 간단할 수 있습니다:

scons

그러면 현재 플랫폼, 운영 체제 및 아키텍처에 대한 편집기 빌드가 생성됩니다. 대상, 플랫폼 및/또는 아키텍처를 지정하여 빌드되는 항목을 변경할 수 있습니다. 예를 들어 내보낸 게임을 실행하는 데 사용되는 내보내기 템플릿을 빌드하려면 다음을 실행할 수 있습니다.

scons target=template_release

엔진을 디버그하거나 개발하려는 경우 dev_build 옵션을 활성화하여 개발 전용 디버깅 코드를 활성화할 수 있습니다.

scons dev_build=yes

기사의 다음 섹션에서는 이러한 옵션과 기타 범용 옵션을 더 자세히 설명합니다. 하지만 Godot를 컴파일하기 전에 몇 가지 필수 구성 요소를 설치해야 합니다. 자세한 내용은 플랫폼 설명서를 참조하세요.

이 글은 특정 플랫폼에서 Godot를 컴파일하기 위해 환경을 설정하는 방법과 해당 플랫폼에 맞게 컴파일하는 방법을 매우 자세히 다루고 있습니다. 플랫폼별 구성 옵션과 범용 구성 옵션을 참조하려면 이 문서와 이 문서 사이를 자유롭게 오가십시오.

멀티스레드 사용하기

시스템 성능에 따라 빌드 프로세스에 시간이 걸릴 수 있습니다. 기본적으로 Godot의 SCons 설정은 하나를 제외한 모든 CPU 스레드를 사용하도록 구성됩니다(컴파일 중에 시스템 응답성을 유지하기 위해). 시스템에 4개 이하의 CPU 스레드가 있는 경우 기본적으로 모든 스레드를 사용합니다.

SCons가 사용할 CPU 스레드 수를 조정하려면 -j<threads> 매개변수를 사용하여 빌드에 사용할 스레드 수를 지정합니다.

예시:

scons -j12

플랫폼 선택

Godot의 빌드 시스템은 빌드할 수 있는 플랫폼을 감지하는 것으로 시작됩니다. 감지되지 않으면 해당 플랫폼은 사용 가능한 플랫폼 목록에 나타나지 않습니다. 각 플랫폼의 빌드 요구 사항은 이 튜토리얼 섹션의 나머지 부분에 설명되어 있습니다.

SCons는 ``scons``를 호출하여 호출됩니다. 플랫폼을 지정하지 않으면 SCons는 호스트 플랫폼을 기반으로 대상 플랫폼을 자동으로 감지합니다. 그러면 대상 플랫폼에 대한 구축이 즉시 시작됩니다.

사용 가능한 대상 플랫폼을 나열하려면 ``scons platform=list``를 사용하세요.

scons platform=list
scons: Reading SConscript files ...
The following platforms are available:

    android
    ios
    linuxbsd
    macos
    web
    windows

Please run SCons again and select a valid platform: platform=<string>

플랫폼(예: linuxbsd)용으로 빌드하려면 platform=``(또는 줄여서 ``p=) 인수를 사용하여 실행합니다.

scons platform=linuxbsd

결과 바이너리

결과 바이너리는 일반적으로 다음 명명 규칙에 따라 bin/ 하위 디렉터리에 배치됩니다.

godot.<platform>.<target>[.dev][.double].<arch>[.<extra_suffix>][.<ext>]

이전 빌드 시도의 결과는 다음과 같습니다:

ls bin
bin/godot.linuxbsd.editor.x86_64

이는 바이너리가 Linux 또는 *BSD(둘 다 아님)용이고, 최적화되지 않았으며, 전체 편집기가 컴파일되어 있고, 64비트용임을 의미합니다.

그리고 마침내, 씬을 실행시키면, 애니메이션은 이렇게 보여야 할 것입니다:

C:\godot> dir bin/
godot.windows.editor.64.exe

프로젝트 관리자, 편집기 및 게임 실행을 위한 모든 수단이 포함되어 있으므로 해당 바이너리를 원하는 위치에 복사하세요. 그러나 이를 다른 플랫폼으로 내보낼 데이터가 부족합니다. 이를 위해서는 내보내기 템플릿이 필요합니다(`godotengine.org <https://godotengine.org/>`__에서 다운로드하거나 직접 구축할 수 있음).

Aside from that, there are a few standard options that can be set in all build targets, and which will be explained below.

대상

target 옵션은 편집기가 컴파일되고 디버그 플래그가 사용되는지 여부를 제어합니다. 최적화 수준(optimize) 및 각 빌드에 디버그 기호(debug_symbols)가 포함되어 있는지 여부는 대상과 별도로 제어됩니다. 각 모드의 의미는 다음과 같습니다.

  • target=editor: 편집기 바이너리 빌드(TOOLS_ENABLED 및 DEBUG_ENABLED 정의)

  • target=template_debug: 디버그 내보내기 템플릿 빌드(DEBUG_ENABLED 정의)

  • target=template_release: 릴리스 내보내기 템플릿 빌드

편집기는 모든 PC 대상(Linux, Windows, macOS)에서 기본적으로 활성화되어 있으며 다른 모든 대상에서는 비활성화되어 있습니다. 편집기를 비활성화하면 프로젝트를 실행할 수 있지만 편집기나 프로젝트 관리자는 포함되지 않는 바이너리가 생성됩니다.

사용 가능한 명령줄 인수 목록은 빌드 유형에 따라 다릅니다.

scons platform=<platform> target=editor|template_debug|template_release

개발

개발용 빌드를 생성할 때(debugging/profiling 도구 실행) 프로덕션 빌드와 비교하여 목표가 다른 경우가 많습니다(바이너리를 가능한 한 빠르고 작게 만들기).

Godot는 이 목적을 위해 두 가지 별칭을 제공합니다:

  • ``dev_mode=yes``는 ``verbose=yes warnings=extra werror=yes tests=yes``의 별칭입니다. 이는 오류로서의 경고 동작(Godot의 지속적인 통합 설정과 유사)을 활성화하고 :ref:`unit 테스트 <doc_unit_testing>`을 빌드하여 로컬에서 실행할 수 있도록 합니다.

  • ``production=yes``는 ``use_static_cpp=yes debug_symbols=no lto=auto``의 별칭입니다. libstdc++를 정적으로 연결하면 Linux용으로 컴파일할 때 바이너리 이식성이 향상됩니다. 또한 이 별칭은 MinGW를 사용하여 Linux, 웹 및 Windows용으로 컴파일할 때 링크 시간 최적화를 활성화하지만 MSVC를 사용하여 macOS, iOS 또는 Windows용으로 컴파일할 때는 LTO를 비활성화된 상태로 유지합니다. 이는 해당 플랫폼의 LTO가 연결 속도가 매우 느리거나 생성된 코드에 문제가 있기 때문입니다.

동일한 명령줄에서 다른 값으로 옵션을 지정하여 해당 별칭의 옵션을 수동으로 재정의할 수 있습니다. 예를 들어 ``scons production=yes debug_symbols=yes``를 사용하면 디버깅 기호가 포함된 프로덕션에 최적화된 바이너리를 생성할 수 있습니다.

개발 빌드

참고

``dev_build``는 여러 개발 관련 옵션의 별칭인 ``dev_mode``와 혼동해서는 안 됩니다.

엔진 개발을 수행할 때 dev_build 옵션을 target``와 함께 사용하여 개발별 코드를 활성화할 수 있습니다. ``dev_build defines DEV_ENABLED, disables optimization (-O0//0d), enables generating debug symbols, and does not define NDEBUG (so assert() works in thirdparty libraries).

scons platform=<platform> dev_build=yes

이 플래그는 생성된 바이너리 이름에 .dev 접미사(개발용)를 추가합니다.

더 보기

특정 엔진 문제를 더 효과적으로 디버그하기 위해 컴파일 타임에 활성화할 수 있는 도구인 *새니타이저*를 활성화하는 추가 SCons 옵션이 있습니다. 자세한 내용은 :ref:`doc_using_sanitizers`를 참조하세요.

디버깅

기본적으로 ``debug_symbols=no``가 사용됩니다. 이는 컴파일된 바이너리에 디버깅 기호가 포함되지 않음을 의미합니다. ``debug_symbols=yes``를 사용하여 컴파일된 바이너리 내에 디버그 기호를 포함하면 디버거와 프로파일러가 올바르게 작동할 수 있습니다. Godot의 크래시 스택 추적이 소스 코드 파일 및 라인에 대한 참조와 함께 표시되기 위해서는 디버깅 기호도 필요합니다.

단점은 디버깅 기호가 큰 파일이라는 것입니다(바이너리 자체보다 훨씬 더 큼). 결과적으로 공식 바이너리에는 현재 디버깅 기호가 포함되어 있지 않습니다. 이는 디버깅 기호에 접근하려면 Godot를 직접 컴파일해야 함을 의미합니다.

debug_symbols=yes``를 사용하는 경우 ``separate_debug_symbols=yes``를 사용하여 ``.debug 접미사가 있는 별도의 파일에 디버그 정보를 넣을 수도 있습니다. 이렇게 하면 두 파일을 독립적으로 배포할 수 있습니다. Windows에서 MSVC로 컴파일할 때 디버깅 정보는 separate_debug_symbols``에 관계없이 *항상* 별도의 ``.pdb 파일에 기록됩니다.

팁

이미 컴파일한 바이너리에서 디버깅 기호를 제거하려면 strip <path/to/binary> 명령을 사용하십시오.

최적화(Optimization)

다음 중에서 여러 컴파일러 최적화 수준을 선택할 수 있습니다.

  • optimize=speed_trace (웹이 아닌 플랫폼을 대상으로 하는 경우 기본값): 더 큰 바이너리 크기를 사용하여 실행 속도를 선호합니다. 최적화는 때때로 디버거 사용에 부정적인 영향을 미칠 수 있습니다(스택 추적은 덜 정확할 수 있습니다. 이런 일이 발생하면 대신 ``optimize=debug``를 사용하십시오.

  • optimize=speed: ``optimize=speed_trace``에 비해 바이너리 크기가 더 커지는 대신 실행 속도가 더 빨라집니다. ``optimize=debug``에 비해 디버깅에 덜 친숙합니다. 이는 사용 가능한 가장 공격적인 최적화를 사용하기 때문입니다.

  • optimize=size (웹 플랫폼을 대상으로 하는 경우 기본값): 실행 속도가 느린 대신 작은 바이너리를 선호합니다.

  • optimize=size_extra: ``optimize=size``에 비해 실행 속도가 훨씬 느리지만 더 작은 바이너리를 선호합니다.

  • optimize=debug: 어떤 방식으로든 디버깅에 영향을 주지 않는 최적화만 활성화합니다. 이로 인해 ``optimize=none``보다 빠른 바이너리가 생성되지만 ``optimize=speed_trace``보다 느린 바이너리가 생성됩니다.

  • optimize=none: 최적화를 수행하지 않습니다. 이는 가장 빠른 빌드 시간을 제공하지만 실행 시간은 가장 느립니다.

  • optimize=custom (고급 사용자 전용): C/C++ 컴파일러에 최적화 인수를 전달하지 않습니다. cflags, ccflags 및 cxxflags SCons 옵션을 사용하여 인수를 수동으로 전달해야 합니다.

텍스처

arch 옵션은 바이너리를 실행하기 위한 CPU 또는 OS 버전을 제어하기 위한 것입니다. 주로 데스크톱 플랫폼에 초점을 맞추고 다른 곳에서는 무시됩니다.

arch 옵션에 지원되는 값은 auto, x86_32, x86_64, arm32, arm64, rv64, ppc32, ppc64 및 **wasm32**입니다.

scons platform=<platform> arch={auto|x86_32|x86_64|arm32|arm64|rv64|ppc32|ppc64|wasm32}

이 플래그는 관련된 경우 결과 바이너리에 arch 값을 추가합니다. 기본값 ``arch=auto``는 호스트 플랫폼과 일치하는 아키텍처를 감지합니다.

커스텀 모듈

내장 모듈과 함께 Godot의 디렉토리 트리 외부에 있는 모듈을 컴파일하는 것이 가능합니다.

컴파일하기 전에 custom_modules 빌드 옵션을 명령줄에 전달할 수 있습니다. 이 옵션은 내장된 modules/ 디렉터리와 마찬가지로 C++ 패키지로 볼 수 있는 독립적인 C++ 모듈 컬렉션을 포함하는 쉼표로 구분된 디렉터리 경로 목록을 나타냅니다.

예를 들어, 해당 모듈을 포함하는 상대, 절대 및 사용자 디렉터리 경로를 모두 제공할 수 있습니다.

scons custom_modules="../modules,/abs/path/to/modules,~/src/godot_modules"

참고

내장 모듈로서 정확한 디렉터리 이름을 가진 사용자 정의 모듈이 있는 경우 엔진은 해당 사용자 정의 모듈만 컴파일합니다. 이 논리는 내장 모듈 구현을 재정의하는 데 사용될 수 있습니다.

더 보기

맞춤형 후처리

생성된 파일 정리하기

때로는 생성된 파일이 존재하기 때문에 오류가 발생할 수 있습니다. ``scons --clean <options>``를 사용하여 제거할 수 있습니다. 여기서 ``<options>``는 이전에 Godot를 빌드하는 데 사용한 빌드 옵션 목록입니다.

또는 모든 플랫폼 및 구성에 대한 빌드 아티팩트를 정리하는 ``git clean -fixd``를 사용할 수 있습니다. 이렇게 하면 저장소에서 추적되지 않고 무시된 파일이 모두 제거되므로 주의하세요. 커밋되지 않은 작업이 있는 경우 이 명령을 실행하지 마세요!

기타 빌드 옵션

Godot를 빌드하는 방법(컴파일러, 디버그 옵션 등)과 포함/비활성화할 기능을 구성하는 데 사용할 수 있는 몇 가지 다른 빌드 옵션이 있습니다.

컴파일하려는 버전의 각 옵션에 대한 자세한 내용은 ``scons --help``의 출력을 확인하세요.

가상 함수 다시 정의하기(Override)

타일맵 사용하기

기본 custom.py 파일은 Godot 엔진 소스의 루트에 생성되어 명령줄을 통해 전달된 SCons 빌드 옵션을 초기화할 수 있습니다:

custom.py
optimize = "size"
module_mono_enabled = "yes"
use_llvm = "yes"
extra_suffix = "game_title"

컴파일하기 전에 일부 내장 모듈을 비활성화하여 엔진을 빌드하는 데 걸리는 약간의 시간을 절약할 수도 있습니다. 자세한 사항은 크기에 따른 빌드 최적화 페이지를 참조하세요.

더 보기

온라인 Godot 빌드 옵션 생성기 <https://godot-build-options-generator.github.io/>`__를 사용하여 SCons 옵션이 포함된 ``custom.py` 파일을 생성할 수 있습니다. 그런 다음 이 파일을 저장하고 Godot 소스 디렉터리의 루트에 배치할 수 있습니다.

profile 명령줄 옵션을 사용하여 다른 사용자 정의 파일을 명시적으로 지정할 수 있으며, 둘 다 기본 빌드 구성을 재정의합니다.

scons profile=path/to/custom.py

참고

파일에서 설정된 빌드 옵션은 명령줄 옵션으로 오버라이드될 수 있습니다.

조건에 따라 옵션을 재정의할 수도 있습니다.

custom.py
import version

# Override options specific for Godot 3.x and 4.x versions.
if version.major == 3:
    pass
elif version.major == 4:
    pass

SCONSFLAGS 사용

``SCONSFLAGS``는 명령줄을 통해 옵션을 제공하지 않고도 자동으로 옵션을 설정하기 위해 SCons에서 사용하는 환경 변수입니다.

예를 들어, 향후 모든 빌드에 대해 앞서 언급한 -j 옵션을 사용하여 다수의 CPU 스레드를 강제로 적용할 수 있습니다.

export SCONSFLAGS="-j4"

SCU(단일 컴파일 단위) 빌드

일반 빌드는 각 컴파일 번역 단위에 많은 수의 헤더를 포함하여 병목 현상이 발생하는 경향이 있습니다. 주로 개발 속도를 높이기 위해(프로덕션 빌드보다는) Godot는 "단일 컴파일 유닛" 빌드(일명 "Unity / Jumbo" 빌드)를 제공합니다.

이 옵션으로 가속화된 폴더의 경우 여러 .cpp 파일이 각 번역 단위에서 컴파일되므로 여러 파일 간에 헤더를 공유할 수 있으므로 빌드 시간이 크게 단축될 수 있습니다.

SCU 빌드를 수행하려면 scu_build=yes SCons 옵션을 사용하세요.

참고

SCU 빌드를 사용하여 Pull Request를 개발하는 경우 PR을 제출하기 전에 일반 빌드를 만들어야 합니다. 이는 SCU 빌드가 본질적으로 번역 단위에 이전 .cpp 파일의 헤더를 포함하므로 일반 빌드에 필요한 모든 포함을 포착하지 못하기 때문입니다. CI는 이러한 오류를 포착하지만 일반적으로 컴퓨터의 로컬 빌드에서 오류를 포착하는 것이 더 빠릅니다.

템플릿 내보내기

공식 내보내기 템플릿은 Godot Engine 사이트(godotengine.org)에서 다운로드됩니다. 그러나 직접 빌드하고 싶을 수도 있습니다(최신 모듈을 원하거나 사용자 정의 모듈을 사용하거나 단순히 자신의 섀도우를 신뢰하지 않는 경우).

공식 내보내기 템플릿 패키지를 다운로드하고 압축을 풀면 대부분의 파일이 각 플랫폼에 최적화된 바이너리 또는 패키지라는 것을 알 수 있습니다.

android_debug.apk
android_release.apk
android_source.zip
ios.zip
linux_debug.arm32
linux_debug.arm64
linux_debug.x86_32
linux_debug.x86_64
linux_release.arm32
linux_release.arm64
linux_release.x86_32
linux_release.x86_64
macos.zip
version.txt
web_debug.zip
web_dlink_debug.zip
web_dlink_nothreads_debug.zip
web_dlink_nothreads_release.zip
web_dlink_release.zip
web_nothreads_debug.zip
web_nothreads_release.zip
web_release.zip
windows_debug_x86_32_console.exe
windows_debug_x86_32.exe
windows_debug_x86_64_console.exe
windows_debug_x86_64.exe
windows_debug_arm64_console.exe
windows_debug_arm64.exe
windows_release_x86_32_console.exe
windows_release_x86_32.exe
windows_release_x86_64_console.exe
windows_release_x86_64.exe
windows_release_arm64_console.exe
windows_release_arm64.exe

직접 만들려면 동일한 튜토리얼 섹션에서 각 플랫폼에 대해 자세히 설명된 지침을 따르세요. 각 플랫폼은 자체 템플릿을 만드는 방법을 설명합니다.

version.txt 파일에는 해당 Godot 버전 식별자가 포함되어 있어야 합니다. 이 파일은 충돌을 피하기 위해 버전별 디렉터리에 내보내기 템플릿을 설치하는 데 사용됩니다. 예를 들어, Godot 4.4.1용 내보내기 템플릿을 구축하는 경우 version.txt``는 첫 번째 줄에 ``4.4.1.stable``를 포함해야 합니다(다른 것은 포함하지 않음). 이 버전 식별자는 `Godot Git 저장소의 version.py 파일 <https://github.com/godotengine/godot/blob/master/version.py>`__의 ``major, minor, patch``(있는 경우) 및 ``status 행을 기반으로 합니다.

여러 플랫폼용으로 개발하는 경우 macOS는 확실히 크로스 컴파일을 위한 가장 편리한 호스트 플랫폼입니다. 모든 대상에 대해 크로스 컴파일이 가능하기 때문입니다. Linux와 Windows가 2위를 차지하지만 Linux는 이를 설정하기 더 쉬운 플랫폼이라는 장점이 있습니다.