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 principal: Trabalhando com o SCons

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.

O godot-cpp usa o SCons como seu sistema de compilação principal. Ele é modelado com base no sistema de compilação do Godot, e alguns comandos disponíveis lá também estão disponíveis em projetos godot-cpp.

Primeiros passos

Para compilar un projeto godot-cpp, geralmente é suficiente instalar o SCons e simplesmente executá-lo no diretório do projeto:

scons

Você pode querer conhecer as opções disponíveis:

scons --help

Para recompilar o seu projeto do zero (clean re-build), adicione --clean ao seu comando de compilação:

scons --clean

Você pode encontrar mais informações sobre argumentos comuns do SCons e padrões de compilação no Guia do Usuário do SCons. Comandos adicionais podem ser adicionados por projetos godot-cpp individuais, portanto, consulte a documentação específica deles para obter mais informações sobre isso.

Configurando uma IDE

A maioria das IDEs pode usar um arquivo compile_commands.json para entender um projeto C++. Você pode gerá-lo com o godot-cpp usando o seguinte comando:

# Generate compile_commands.json while compiling.
scons compiledb=yes

# Generate compile_commands.json without compiling.
scons compiledb=yes compile_commands.json

Para mais informações, consulte os guias de configuração de IDE. Embora tenham sido escritos para colaboradores do motor Godot, eles são amplamente aplicáveis também a projetos godot-cpp.

Carregando sua GDExtension no Godot

O Godot carrega GDExtensions encontrando arquivos .gdextension no diretório do projeto. Arquivos .gdextension são usados para selecionar e carregar um binário compatível com o computador / sistema operacional atual.

O godot-cpp-template, bem como a seção Primeiros Passos, fornecem arquivos .gdextension de exemplo para GDExtensions que são amplamente compatíveis com muitos sistemas diferentes.

Compilando para múltiplas plataformas

GDExtensions devem ser executadas em muitos sistemas diferentes, cada um com binários e configurações de compilação separados. Se você planeja publicar sua GDExtension, recomendamos que forneça binários para todas as configurações mencionadas no arquivo .gdextension do godot-cpp-template.

Existem duas maneiras populares de realizar builds multiplataforma:

Ferramentas de compilação multiplataforma
Integração Contínua (CI)

O godot-cpp-template contém uma configuração de exemplo para um fluxo de trabalho de CI baseado no GitHub.

Usando um arquivo de API personalizado

Cada ramificação (branch) do godot-cpp vem com um arquivo de API (extension_api.json) apropriado para a respectiva versão do Godot (por exemplo, a ramificação 4.3 vem com o arquivo de API compatível com o Godot versão 4.3 e posteriores).

No entanto, você pode querer usar un arquivo extension_api.json personalizado, por exemplo:

Se você quiser usar as APIs mais recentes do master do Godot.
Se você compilar o Godot por conta própria com opções diferentes das compilações oficiais (ex.: disable_3d=yes ou precision=double).
Se você quiser usar APIs expostas por módulos personalizados.

Para usar um arquivo de API personalizado, primeiro você deve gerá-lo a partir do executável apropriado do Godot:

godot --dump-extension-api

O arquivo extension_api.json resultante será criado no diretório do executável. Para utilizá-lo, você pode adicionar custom_api_file ao seu comando de compilação:

scons platform=<platform> custom_api_file=<PATH_TO_FILE>

Alternativamente, você pode adicioná-lo como o arquivo de API padrão ao seu projeto adicionando a seguinte linha ao seu arquivo SConstruct:

localEnv["custom_api_file"] = "extension_api.json"

Modifying generated files

If you have to modify the files generated by godot-cpp, its hook system is the right way of doing so. We provide the BindingGeneratorHooks class, located at godot-cpp/tools/binding_generator_hooks.py. Your custom hooks are a python class that extends BindingGeneratorHooks and overrides (some of) its methods. After defining your subclass, you should export an instance of it from your SConstruct with the key binding_hooks to godot-cpp's SConstruct. This way you let godot-cpp's SConstruct know about your class, see the example below for one way of doing this.

Exemplo

This example adds a string constant of every signal in a class to its class header. For example, in base_button.hpp we will add static constexpr char SIGNAL_PRESSED[] = "pressed"; for the pressed signal. We will use the SConstruct file from the godot-cpp template. We start by creating custom_generator.py at the root of our project. It only overrides alter_engine_class_header, as that is all we need.

custom_generator.py

import sys

sys.path.insert(0, "godot-cpp")
from tools.binding_generator_hooks import BindingGeneratorHooks

class CustomBindingGeneratorHooks(BindingGeneratorHooks):
    def alter_engine_class_header(self, class_api, lines):
        signals = []
        if "signals" in class_api:
            for signal_api in class_api["signals"]:
                name = signal_api["name"]
                signal_constant = "\tstatic constexpr char SIGNAL_" + name.upper() + '[] = "' + name + '";'
                signals.append(signal_constant)
            try:
                idx = lines.index("public:") + 1
                for signal_const in signals:
                    lines.insert(idx, signal_const)
                    idx += 1
            except ValueError:
                print("no public keyword found, not adding signals")
        return lines

Next, we import the class in our SConstruct file:

from custom_generator import CustomBindingGeneratorHooks

Additionally, we edit the line that exports variables to godot-cpp/SConstruct to include an instance of our class, like so:

env = SConscript("godot-cpp/SConstruct", {"env": env, "customs": customs, "binding_hooks": CustomBindingGeneratorHooks()})

This is everything you need, when you regenerate the files they should contain signal name constants for all signals in the API file.