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

보조 빌드 시스템: CMake 작업

더 보기

이 페이지는 소스로부터 iOS 내보내기 템플릿 바이너리를 컴파일하는 방법을 설명합니다. 프로젝트를 iOS로 내보내는 방법을 찾는다면 :ref:`doc_exporting_for_ios`을 읽으시기 바랍니다.

SCons 기반 빌드 시스템 외에도 godot-cpp는 빌드 시스템에 SCons보다 CMake_를 사용하는 것을 선호하는 사용자를 지원하기 위해 CMakeLists.txt 파일도 제공합니다.

CMake 시스템은 적극적으로 지원되지만 SCons 빌드 시스템의 보조 시스템으로 간주됩니다. 이는 SCons를 사용하는 프로젝트에 사용할 수 있는 일부 기능이 부족할 수 있음을 의미합니다.

소개

확장 프로젝트와 독립적으로 godot-cpp를 컴파일하는 것은 주로 godot-cpp 개발자, 패키지 관리자 및 CI/CD를 위한 것입니다.

CMake를 사용하여 확장 프로젝트의 일부로 godot-cpp 라이브러리를 사용하는 방법의 예:

godot-cpp 구성에 대한 예는 페이지 하단에 나열되어 있으며, 그 중 다수는 프로젝트 구성에 도움이 될 수 있습니다.

CMake의 Debug 대 Godot의 template_debug

많은 논의 중에 나온 것은 디버그 기호가 활성화된 C++ 소스 코드 컴파일과 디버그 기능이 활성화된 Godot 확장 컴파일의 융합입니다. 두 개념은 상호 배타적이지 않습니다.

기본 기능

Godot 확장 사용자가 자신의 프로젝트를 수행할 수 있도록 코드를 선택적으로 컴파일하는 전처리기 정의를 활성화합니다.

디버그 기능은 editor 및 template_debug 빌드에서 활성화되며 다음과 같이 구성 단계에서 지정할 수 있습니다.

cmake -S godot-cpp -B cmake-build -DGODOTCPP_TARGET=<target choice>

디버그

Godot 확장 개발자가 확장을 디버그하는 데 도움이 되는 디버그 기호가 생성되도록 컴파일러 플래그를 설정합니다.

``Debug``는 CMake 프로젝트의 기본 빌드 유형이며, 다른 것을 선택하는 방법은 사용된 생성기에 따라 다릅니다.

  • 단일 구성 생성기의 경우 구성 명령에 ``-DCMAKE_BUILD_TYPE=<type>``를 추가합니다.

  • 다중 구성 생성기의 경우 빌드 명령에 ``--config <type>``를 추가하세요.

여기서 <type>``는 ``Debug, Release, RelWithDebInfo 및 MinSizeRel 중 하나입니다.

연결(Connections)

SCons 시스템의 모든 코드가 CMake에서 완벽하게 표현될 수 있는 것은 아닙니다. 주목할만한 차이점은 다음과 같습니다.

  • 디버깅

    더 이상 명시적인 옵션이 아니며 CMake 빌드 구성을 사용할 때 활성화됩니다. Debug, RelWithDebInfo.

  • default

    비활성화되면 NDEBUG``를 정의하지 않으며 CMake 빌드 구성을 사용할 때 ``NDEBUG``가 설정됩니다. ``Release, MinSizeRel.

  • arch

    CMake는 툴체인 파일을 통해 아키텍처를 설정하고, macOS Universal은 정의될 때 대상에 복사되는 CMAKE_OSX_ARCHITECTURES 속성을 통해 제어됩니다.

  • --debug-paths

    CMake는 CMAKE_MSVC_RUNTIME_LIBRARIES 값을 정의된 대상에 복사하여 Windows 런타임 라이브러리에 대한 연결을 제어합니다. godot-cpp는 이 변수가 아직 설정되지 않은 경우 설정합니다. 따라서 프로젝트 전체에 값이 전파되도록 하려면 다른 종속성보다 먼저 포함하세요.

기본 연습

Git 저장소 복제

git clone https://github.com/godotengine/godot-cpp.git
Cloning into 'godot-cpp'...
...

빌드 커스터마이징하기

cmake -S godot-cpp -B cmake-build -G Ninja

  • -S 소스 디렉터리를 ``godot-cpp``로 지정합니다.

  • -B 빌드 디렉터리를 ``cmake-build``로 지정합니다.

  • -G 생성기를 ``Ninja``로 지정합니다.

이 예의 소스 디렉터리는 새로 복제된 godot-cpp의 소스 루트입니다. CMake는 또한 명령의 첫 번째 경로를 소스 경로로 해석하거나, 기존 빌드 경로가 지정된 경우 빌드 캐시에서 소스 경로를 추론합니다.

다음 예제에서:

# Current working directory is the godot-cpp source root.
cmake . -B build-dir

# Current working directory is an empty godot-cpp/build-dir.
cmake ../

# Current working directory is an existing build path.
cmake .

생성된 파일이 빌드 아티팩트로 소스 트리를 복잡하게 만들지 않도록 빌드 디렉터리가 지정됩니다.

CMake는 코드를 빌드하지 않고 빌드 도구에서 사용하는 파일을 생성합니다. 이 경우 Ninja 생성기는 Ninja 빌드 파일을 생성합니다.

생성기 목록을 보려면 ``cmake --help``를 실행하세요.

Built-In(내장)

사용 가능한 옵션을 나열하려면 -L[AH] 명령 플래그를 사용하십시오. ``A``는 고급용이고 ``H``는 도움말 문자열용입니다.

cmake -S godot-cpp -LH

옵션은 구성할 때 명령줄에서 지정됩니다. 예를 들면 다음과 같습니다.

cmake -S godot-cpp -DGODOTCPP_USE_HOT_RELOAD:BOOL=ON \
    -DGODOTCPP_PRECISION:STRING=double \
    -DCMAKE_BUILD_TYPE:STRING=Debug

자세한 내용은 설정-빌드-변수 및 빌드-구성_을 참조하세요.

포괄적이지 않은 옵션 목록:

// Path to a custom GDExtension API JSON file.
// (takes precedence over GODOTCPP_GDEXTENSION_DIR)
// ( /path/to/custom_api_file )
GODOTCPP_CUSTOM_API_FILE:FILEPATH=

// Force disabling exception handling code. (ON|OFF)
GODOTCPP_DISABLE_EXCEPTIONS:BOOL=ON

// Path to a custom directory containing the GDExtension interface
// header and API JSON file. ( /path/to/gdextension_dir )
GODOTCPP_GDEXTENSION_DIR:PATH=gdextension

// Set the floating-point precision level. (single|double)
GODOTCPP_PRECISION:STRING=single

// Enable the extra accounting required to support hot reload. (ON|OFF)
GODOTCPP_USE_HOT_RELOAD:BOOL=

컴파일링

지정된 디렉터리에 생성된 빌드 시스템을 호출하도록 CMake에 지시합니다. 기본 대상은 ``template_debug``이고 기본 빌드 구성은 디버그입니다.

cmake --build cmake-build

예제

이러한 예제는 godot-cpp 개발자, 패키지 관리자 및 CI/CD를 위한 것이지만 자신만의 확장 프로젝트를 구성하는 데 도움이 될 수 있습니다.

확장 프로젝트의 일부로 godot-cpp 라이브러리를 사용하는 방법에 대한 실제 예는 `Introduction`_에 나열되어 있습니다.

--debug-navigation

테스트 대상 ``godot-cpp-test``는 기본적으로 꺼져 있는 ``GODOTCPP_ENABLE_TESTING``에 의해 보호됩니다.

통합 테스트 대상을 활성화하기 위해 godot-cpp 프로젝트를 구성하고 빌드하려면 명령은 다음과 같습니다.

cmake -S godot-cpp -B cmake-build -DGODOTCPP_ENABLE_TESTING=YES
cmake --build cmake-build --target godot-cpp-test

Windows 및 MSVC - 릴리스

CMake가 CMake Downloads 페이지 및 PATH에서 설치되고 Microsoft Visual Studio가 C++ 지원과 함께 설치되는 한 CMake는 MSVC 컴파일러를 감지합니다.

Visual Studio는 다중 구성 생성기이므로 빌드 시 빌드 구성을 지정해야 합니다(예: --config Release).

cmake -S godot-cpp -B cmake-build -DGODOTCPP_ENABLE_TESTING=YES
cmake --build cmake-build -t godot-cpp-test --config Release

MSys2/clang64, "Ninja" - 디버그

ming-w64-clang-x86_64-toolchain이 설치되었다고 가정합니다.

Ninja는 단일 구성 생성기이므로 구성 시 빌드 유형을 지정해야 합니다.

msys2/clang64 셸 사용:

cmake -S godot-cpp -B cmake-build -G"Ninja" \
    -DGODOTCPP_ENABLE_TESTING=YES -DCMAKE_BUILD_TYPE=Release
cmake --build cmake-build -t godot-cpp-test

MSys2/clang64, "Ninja 다중 구성" - dev_build, 디버그 기호

ming-w64-clang-x86_64-toolchain이 설치되었다고 가정합니다.

이번에는 'Ninja Multi-Config' 생성기를 선택하므로 빌드 유형은 빌드 시 지정됩니다.

msys2/clang64 셸 사용:

cmake -S godot-cpp -B cmake-build -G"Ninja Multi-Config" \
    -DGODOTCPP_ENABLE_TESTING=YES -DGODOTCPP_DEV_BUILD:BOOL=ON
cmake --build cmake-build -t godot-cpp-test --config Debug

지원되는 플랫폼

이것은 지금까지 Windows에서만 테스트되었습니다. 다음 예시 워크플로를 사용할 수 있습니다.

  • 최신 Emscripten 도구를 ``c:emsdk``에 복제하고 설치합니다.

  • 현재 셸의 powershell에서 환경을 활성화하려면 ``C:emsdkemsdk.ps1 activate latest``를 사용하세요.

  • emcmake.bat 유틸리티는 emscripten 툴체인을 CMake 명령에 추가합니다. 수동으로 추가할 수도 있습니다. 위치는 emcmake.bat 파일 내부에 나열되어 있습니다.

C:\emsdk\emsdk.ps1 activate latest
emcmake.bat cmake -S godot-cpp -B cmake-build-web -DCMAKE_BUILD_TYPE=Release
cmake --build cmake-build-web

Android SDK

Android용으로 구성할 때 선택할 수 있는 별도의 두 가지 경로가 있습니다.

cmake-toolchains 문서에 나열된 대로 명령줄이나 자체 도구 체인 파일에 지정된 CMAKE_ANDROID_* 변수를 사용하세요.

또는 Android SDK에서 제공하는 툴체인과 스크립트를 사용하고 거기에 나열된 ANDROID_* 변수를 사용하여 변경하세요. 여기서 ``<version>``는 설치한 NDK 버전(`28.1.13356709`로 테스트)이고 ``<platform>``는 Android SDK 플랫폼용(``android-29``로 테스트)입니다.

경고

Android SDK 웹사이트_에서는 CMake 내장 방법 사용을 지원하지 않는다고 명시적으로 명시하고 해당 툴체인 파일을 사용할 것을 권장합니다.

알림(Notifications)

CMake 문서에 설명된 대로:

cmake -S godot-cpp -B cmake-build --toolchain my_toolchain.cmake
cmake --build cmake-build -t template_release

명령줄을 사용하여 동일한 작업을 수행합니다.

cmake -S godot-cpp -B cmake-build \
    -DCMAKE_SYSTEM_NAME=Android \
    -DCMAKE_SYSTEM_VERSION=<platform> \
    -DCMAKE_ANDROID_ARCH_ABI=<arch> \
    -DCMAKE_ANDROID_NDK=/path/to/android-ndk
cmake --build cmake-build

Android 편집기 사용하기

기본값은 지원되는 최소 버전 및 armv7-a입니다.

cmake -S godot-cpp -B cmake-build \
    --toolchain $ANDROID_HOME/ndk/<version>/build/cmake/android.toolchain.cmake
cmake --build cmake-build

Android 플랫폼 및 ABI 지정하기:

cmake -S godot-cpp -B cmake-build \
    --toolchain $ANDROID_HOME/ndk/<version>/build/cmake/android.toolchain.cmake \
    -DANDROID_PLATFORM:STRING=android-29 \
    -DANDROID_ABI:STRING=armeabi-v7a
cmake --build cmake-build