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

Sistema de compilação secundário: Trabalhando com o CMake

Ver também

Esta página documenta como compilar o godot-cpp. Se você deseja compilar o Godot, consulte Introdução ao sistema de compilação.

Além do sistema de compilação baseado no SCons, o godot-cpp também fornece um arquivo CMakeLists.txt para dar suporte aos usuários que preferem usar o CMake em vez do SCons como seu sistema de compilação.

Embora seja ativamente suportado, o sistema CMake é considerado secundário em relação ao sistema de compilação SCons. Isso significa que ele pode carecer de alguns recursos que estão disponíveis para projetos que utilizam o SCons.

Introdução

A compilação do godot-cpp de forma independente de um projeto de extensão é voltada principalmente para desenvolvedores do godot-cpp, mantenedores de pacotes e CI/CD.

Exemplos de como usar o CMake para consumir a biblioteca godot-cpp como parte de um projeto de extensão:

• godot-cpp-template

• godot_roguelite

• godot-orchestrator

Exemplos para configurar o godot-cpp estão listados no final da página, muitos dos quais podem ajudar na configuração do seu projeto.

Debug do CMake vs template_debug do Godot

Algo que surgiu durante muitas discussões é a confusão entre a compilação de código-fonte C++ com símbolos de depuração (debug symbols) ativados e a compilação de uma extensão do Godot com recursos de depuração ativados. Os dois conceitos não são mutuamente exclusivos.

Recursos de depuração

Ativa uma definição de pré-processador para compilar código seletivamente para ajudar os usuários de uma extensão do Godot em seus próprios projetos.

Os recursos de depuração são ativados em compilações de editor e template_debug, que podem ser especificadas durante a fase de configuração desta forma:

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

Depuração

Define flags do compilador para que símbolos de depuração sejam gerados para ajudar os desenvolvedores de extensões do Godot a depurarem suas extensões.

Debug é o tipo de compilação padrão para projetos CMake, a maneira de selecionar outra depende do gerador utilizado:

• Para geradores de configuração única (single configuration), adicione -DCMAKE_BUILD_TYPE=<tipo> ao comando de configuração.

• Para geradores multi-configuração (multi-config), adicione --config <tipo> ao comando de compilação.

Onde <tipo> é um dentre Debug, Release, RelWithDebInfo e MinSizeRel.

Desvios do SCons

Nem todo código do sistema SCons pode ser perfeitamente representado no CMake; aqui estão as diferenças notáveis:

• debug_symbols

  Não é mais uma opção explícita e é ativado ao usar as configurações de compilação do CMake; Debug, RelWithDebInfo.

• dev_build

  Não define NDEBUG quando desativado; NDEBUG é definido ao usar as configurações de compilação do CMake; Release, MinSizeRel.

• arch

  O CMake define a arquitetura por meio dos arquivos de toolchain; o universal do macOS é controlado por meio da propriedade CMAKE_OSX_ARCHITECTURES, que é copiada para os alvos (targets) quando eles são definidos.

• debug_crt

  O CMake controla a vinculação às bibliotecas de tempo de execução do Windows copiando o valor de CMAKE_MSVC_RUNTIME_LIBRARIES para os alvos conforme eles são definidos. O godot-cpp definirá essa variável se ela ainda não estiver definida. Portanto, inclua-a antes de outras dependências para fazer com que o valor se propague pelos projetos.

Additionally, the hook system works a bit differently with CMake:

• Your subclass has to be named CustomBindingGeneratorHooks.

• Pass the filepath of the python file containing your subclass with the GODOTCPP_BINDING_HOOK_FILE option to CMake.

Passo a Passo Básico

Clonar o repositório git

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

Configure a compilação

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

• -S Especifica o diretório de origem como godot-cpp

• -B Especifica o diretório de compilação como cmake-build

• -G Especifica o Gerador como Ninja

O diretório de origem neste exemplo é a raiz do código-fonte do godot-cpp recém-clonado. O CMake também interpretará o primeiro caminho no comando como o caminho de origem, ou se um caminho de compilação existente for especificado, ele deduzirá o caminho de origem a partir do cache de compilação.

Os três comandos a seguir são equivalentes:

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

O diretório de compilação é especificado para que os arquivos gerados não baguncem a árvore de código-fonte com artefatos de compilação.

O CMake não compila o código, ele gera os arquivos que uma ferramenta de compilação utiliza; neste caso, o gerador Ninja cria arquivos de compilação do Ninja.

Para ver a lista de geradores, execute cmake --help.

Opções de compilação

Para listar as opções disponíveis, use as flags de comando -L[AH]. A é para avançado e H é para strings de ajuda:

cmake -S godot-cpp -LH

As opções são especificadas na linha de comando ao configurar, por exemplo:

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

Veja setting-build-variables e build-configurations para mais informações.

Uma lista não exaustiva de opções:

// 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=

// Use the binding generator's hook system to modify generated files.
// ( /path/to/custom_generator_file.py)
GODOTCPP_BINDING_HOOK_FILE:FILEPATH=

Compilando

Informa ao CMake para invocar o sistema de compilação que ele gerou no diretório especificado. O alvo padrão é template_debug e a configuração de compilação padrão é Debug.

cmake --build cmake-build

Exemplos

Estes exemplos, embora destinados a desenvolvedores do godot-cpp, mantenedores de pacotes e CI/CD, podem ajudá-lo a configurar o seu próprio projeto de extensão.

Exemplos práticos de como consumir a biblioteca godot-cpp como parte de um projeto de extensão estão listados na Introdução.

Habilitando testes de integração

O alvo de teste godot-cpp-test é protegido por GODOTCPP_ENABLE_TESTING, que fica desativado por padrão.

Para configurar e compilar o projeto godot-cpp de modo a ativar os alvos de teste de integração, o comando será parecido com:

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

Windows e MSVC - Release

Desde que o CMake esteja instalado a partir da página Downloads do CMake e no PATH, e o Microsoft Visual Studio esteja instalado com suporte a C++, o CMake detectará o compilador MSVC.

Observe que o Visual Studio é um Gerador Multi-Configuração, portanto a configuração de compilação precisa ser especificada no momento da compilação, por exemplo, --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" - Debug

Assume que o toolchain ming-w64-clang-x86_64 está instalado.

Observe que o Ninja é um Gerador de Configuração Única, portanto o tipo de compilação precisa ser especificado no momento da configuração.

Usando o terminal 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 Multi-Config" - dev_build, Símbolos de Depuração

Assume que o toolchain ming-w64-clang-x86_64 está instalado.

Desta vez estamos escolhendo o gerador 'Ninja Multi-Config', de modo que o tipo de compilação é especificado no momento da compilação.

Usando o terminal 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

Emscripten para plataforma web

Isso só foi testado no Windows até agora. Você pode usar este exemplo de fluxo de trabalho:

• Clone e instale as ferramentas mais recentes do Emscripten em c:\emsdk.

• Use C:\emsdk\emsdk.ps1 activate latest para ativar o ambiente a partir do PowerShell no terminal atual.

• O utilitário emcmake.bat adiciona o toolchain do emscripten ao comando do CMake. Ele também pode ser adicionado manualmente; a localização está listada dentro do arquivo 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

Compilação cruzada de Android a partir do Windows

Existem dois caminhos separados que você pode escolher ao configurar para o Android.

Use as variáveis CMAKE_ANDROID_* especificadas na linha de comando ou em seu próprio arquivo de toolchain, conforme listado na documentação do cmake-toolchains.

Ou use o toolchain e os scripts fornecidos pelo Android SDK e faça alterações usando as variáveis ANDROID_* listadas lá. Onde <version> é a versão do NDK que você tem instalada (testado com 28.1.13356709) e <platform> é para a plataforma do SDK do Android (testado com android-29).

Aviso

O site do Android SDK afirma explicitamente que eles não oferecem suporte ao uso do método integrado do CMake e recomendam que você continue usando os arquivos de toolchain deles.

Usando seu próprio arquivo de toolchain

Conforme descrito na documentação do CMake:

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

Fazendo o equivalente apenas usando a linha de comando:

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

Usando o arquivo de toolchain do SDK do Android

Isso define como padrão a versão mínima suportada e armv7-a:

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

Especificando a plataforma e a ABI do Android:

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