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

Основная система сборки: работа с SCons

См. также

На этой странице описано, как компилировать godot-cpp. Если вы хотите скомпилировать Godot, см. Введение в систему сборки.

godot-cpp использует SCons в качестве основной системы сборки. Она создана по образцу системы сборки Godot, и некоторые команды, доступные там, также доступны в проектах godot-cpp.

Начало работы

Для сборки проекта godot-cpp обычно достаточно установить SCons и просто запустить его в каталоге проекта:

scons

Возможно, вы захотите узнать о доступных опциях:

scons --help

Чтобы выполнить чистую пересборку проекта, добавьте --clean в команду сборки:

scons --clean

Дополнительную информацию об общих аргументах SCons и шаблонах сборки можно найти в Руководстве пользователя SCons. Отдельные проекты godot-cpp могут добавлять дополнительные команды, поэтому обратитесь к их конкретной документации для получения дополнительной информации.

Настройка IDE

Большинство IDE могут использовать файл compile_commands.json для понимания проекта на C++. Вы можете сгенерировать его с помощью godot-cpp, используя следующую команду:

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

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

Для получения дополнительной информации ознакомьтесь с руководствами по настройке IDE. Хотя они написаны для участников разработки Godot, они в значительной степени применимы и к проектам godot-cpp.

Загрузка вашего GDExtension в Godot

Godot загружает GDExtensions, находя файлы .gdextension в каталоге проекта. Файлы .gdextension используются для выбора и загрузки бинарного файла, совместимого с текущим компьютером/операционной системой.

godot-cpp-template, а также раздел Начало работы содержат примеры файлов .gdextension для GDExtensions, широко совместимых с различными системами.

Сборка для нескольких платформ

Ожидается, что GDExtensions будут работать на множестве различных систем, каждая из которых имеет свои бинарные файлы и конфигурации сборки. Если вы планируете публиковать свой GDExtension, мы рекомендуем предоставлять бинарные файлы для всех конфигураций, упомянутых в .gdextension файле godot-cpp-template.

Существует два популярных способа достижения кроссплатформенной сборки:

  • Кроссплатформенные инструменты сборки

  • Непрерывная интеграция (CI)

godot-cpp-template содержит пример настройки для CI-процесса на основе GitHub.

Использование пользовательского файла API

Каждая ветка godot-cpp поставляется с файлом API (extension_api.json), подходящим для соответствующей версии Godot (например, ветка 4.3 поставляется с файлом API, совместимым с Godot версии 4.3 и новее).

Однако вы можете использовать пользовательский extension_api.json, например:

  • Если вы хотите использовать последние API из Godot master.

  • Если вы собираете Godot сами с другими опциями, чем официальные сборки (например, disable_3d=yes или precision=double).

  • Если вы хотите использовать API, предоставляемые пользовательскими модулями.

Чтобы использовать пользовательский файл API, сначала необходимо сгенерировать его из соответствующего исполняемого файла Godot:

godot --dump-extension-api

Результирующий файл extension_api.json будет создан в каталоге исполняемого файла. Чтобы использовать его, вы можете добавить custom_api_file в команду сборки:

scons platform=<platform> custom_api_file=<PATH_TO_FILE>

Кроме того, вы можете добавить его как файл API по умолчанию в свой проект, добавив следующую строку в файл 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.

Пример

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.