Введение в систему сборки

Godot — это проект, написанный преимущественно на C++, и он использует систему сборки SCons. Мы любим SCons за то, насколько он удобен в обслуживании и прост в настройке. Благодаря этому компиляция Godot из исходного кода может быть такой же простой, как запуск:

scons

Это создаст сборку редактора для вашей текущей платформы, операционной системы и архитектуры. Вы можете изменить то, что будет собрано, указав целевую платформу, и/или архитектуру. Например, чтобы создать шаблон экспорта для запуска экспортированных игр, выполните команду:

scons target=template_release

Если вы планируете отлаживать или разрабатывать движок, то вам может потребоваться включить опцию dev_build, чтобы включить отладочный код, предназначенный только для разработки:

scons dev_build=yes

В следующих разделах статьи эти и другие универсальные опции будут подробно описаны. Но перед компиляцией Godot необходимо установить несколько необходимых компонентов. Подробнее см. в документации к платформе:

В этих статьях подробно описывается, как настроить среду для компиляции Godot на конкретной платформе, так и как компилировать для этой платформы. Вы можете свободно переходить от них к этой статье, чтобы ознакомиться с платформенно-специфичными и универсальными вариантами конфигурации.

Использование многопоточности

Процесс сборки может занять некоторое время в зависимости от мощности вашей системы. По умолчанию конфигурация Godot SCons настроена на использование всех потоков ЦП, кроме одного (чтобы система оставалась отзывчивой во время компиляции). Если в системе 4 потока ЦП или меньше, по умолчанию будут использоваться все потоки.

Если вы хотите настроить количество потоков ЦП, которые будет использовать SCons, используйте параметр -j<threads>, чтобы указать, сколько потоков будет использоваться для сборки.

Пример использования 12 потоков:

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-битной системы.

Бинарный файл для Windows с такой же конфигурацией будет выглядеть следующим образом:

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

Скопируйте этот исполняемый файл в любое удобное место, так как он содержит менеджер проектов, редактор и всё необходимое для запуска игры. Однако в нём отсутствуют данные для экспорта на различные платформы. Для этого необходимы шаблоны экспорта (которые можно скачать с сайта godotengine.org или создать самостоятельно).

Помимо этого, есть несколько стандартных параметров для установки во всех целях сборки, и которые будут описаны ниже.

Цель

Параметр target управляет компиляцией редактора и использованием флагов отладки. Уровни оптимизации (optimize) и наличие в каждой сборке отладочных символов (debug_symbols) контролируются отдельно от целевой версии. Каждый режим означает:

  • target=editor: сборка двоичного файла редактора (определяет TOOLS_ENABLED и DEBUG_ENABLED)

  • target=template_debug: Создание шаблона экспорта отладки (определяет DEBUG_ENABLED)

  • target=template_release: Создание шаблона экспорта релиза

Редактор включён по умолчанию на всех ПК (Linux, Windows, macOS) и отключён для всех остальных. Отключение редактора создаёт исполняемый файл, который может запускать проекты, но не включает в себя редактор и менеджер проектов.

Список доступных аргументов командной строки зависит от типа сборки.

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

Псевдонимы разработки и производства

При создании сборок для разработки (запуск инструментов отладки/profiling) у вас часто есть цели, отличающиеся от целей для производственных сборок (создание максимально быстрых и компактных двоичных файлов).

Для этой цели Godot предлагает два псевдонима:

  • dev_mode=yes — это псевдоним для verbose=yes warnings=extra werror=yes tests=yes. Это включает режим отображения предупреждений как ошибок (аналогично настройке непрерывной интеграции Godot), а также собирает unit-тесты, чтобы их можно было запускать локально.

  • production=yes — это псевдоним для use_static_cpp=yes debug_symbols=no lto=auto. Статическая линковка libstdc++ обеспечивает лучшую переносимость двоичного кода при компиляции для Linux. Этот псевдоним также обеспечивает оптимизацию времени компоновки при компиляции для Linux, Web и Windows с MinGW, но отключает LTO при компиляции для macOS, iOS или Windows с MSVC. Это связано с тем, что LTO на этих платформах компонуется очень медленно или имеет проблемы с генерируемым кодом.

Вы можете вручную переопределить параметры этих псевдонимов, указав их в той же командной строке с другими значениями. Например, можно использовать scons production=yes debug_symbols=yes для создания оптимизированных для производства двоичных файлов с включенными отладочными символами.

Dev-сборка

Примечание

dev_build не следует смешивать с dev_mode, который является псевдонимом для нескольких параметров, связанных с разработкой (см. выше).

При разработке движка параметр dev_build можно использовать вместе с target для включения специфичного для dev кода. dev_build определяет DEV_ENABLED, отключает оптимизацию (-O0//0d), включает генерацию отладочных символов и не определяет NDEBUG (поэтому assert() работает в сторонних библиотеках).

scons platform=<platform> dev_build=yes

Этот флаг добавляет суффикс .dev (для разработки) к сгенерированному имени двоичного файла.

См. также

Существуют дополнительные параметры SCons для включения sanitizers — инструментов, которые можно включить во время компиляции для более эффективной отладки определённых проблем движка. Подробнее см. в документе Использование дезинфицирующих средств (sanitizers).

Отладочные символы

По умолчанию используется debug_symbols=no, что означает, что в скомпилированные двоичные файлы не будут включены никакие отладочные символы. Используйте debug_symbols=yes, чтобы включить отладочные символы в скомпилированные двоичные файлы, что обеспечивает корректную работу отладчиков и профилировщиков. Отладочные символы также необходимы для отображения трассировок стека сбоев Godot со ссылками на файлы и строки исходного кода.

Недостатком является то, что отладочные символы представляют собой большие файлы (значительно больше, чем сами исполняемые файлы). В результате официальные исполняемые файлы в настоящее время не содержат отладочных символов. Это означает, что для доступа к отладочным символам вам придётся самостоятельно скомпилировать Godot.

При использовании debug_symbols=yes вы также можете использовать separate_debug_symbols=yes для помещения отладочной информации в отдельный файл с суффиксом .debug. Это позволяет распространять оба файла независимо. Обратите внимание, что в Windows при компиляции с помощью MSVC отладочная информация всегда записывается в отдельный файл .pdb независимо от separate_debug_symbols.

Совет

Используйте команду strip <path/to/binary> для удаления отладочных символов из уже скомпилированного вами двоичного файла.

Уровень оптимизации

Можно выбрать несколько уровней оптимизации компилятора:

  • optimize=speed_trace (по умолчанию при использовании не-Web-платформ): увеличивает скорость выполнения за счёт увеличения размера двоичного файла. Оптимизация иногда может негативно влиять на использование отладчика (трассировка стека может быть менее точной). В этом случае используйте 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++. Вам придётся передавать аргументы вручную с помощью параметров SCons cflags, ccflags и cxxflags.

Архитектура

Параметр arch предназначен для управления версией CPU или ОС, на которой будут запускаться исполняемые файлы. Он ориентирован в основном на настольные платформы и игнорируется во всех остальных случаях.

Поддерживаемые значения для параметра 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 можно передать в командную строку перед компиляцией. Этот параметр представляет собой список путей к каталогам, разделённых запятыми, содержащим набор независимых модулей C++, которые можно рассматривать как пакеты C++, подобно встроенному каталогу modules/.

Например, можно указать как относительные, так и абсолютные пути, а также пути к пользовательским каталогам, содержащим такие модули:

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

Примечание

Если существует встроенный пользовательский модуль с таким же именем каталога, как и у встроенного модуля, движок скомпилирует только его. Эту логику можно использовать для переопределения реализаций встроенных модулей.

См. также

Собственные модули на C++

Очистка сгенерированных файлов

Иногда может возникнуть ошибка из-за наличия сгенерированных файлов. Вы можете удалить их с помощью команды scons --clean <options>, где <options> — это список параметров сборки, которые вы использовали ранее при сборке Godot.

В качестве альтернативы вы можете использовать git clean -fixd, которая очистит артефакты сборки для всех платформ и конфигураций. Будьте осторожны: это удалит все неотслеживаемые и игнорируемые файлы в репозитории. Не запускайте эту команду, если у вас есть незакоммиченные (uncommitted) изменения!

Другие параметры сборки

Существуют несколько других параметров сборки которые вы можете использовать для настройки способа сборки Godot (компилятор, опции отладки, итд.) также как и возможности для включения/выключения.

Посмотрите вывод scons --help для подробностей по этим командам для версии которую вы хотите скомпилировать.

Переопределение параметров сборки

Использование файла

Файл custom.py по умолчанию можно создать в корневом каталоге исходного кода Godot Engine для инициализации любых параметров сборки SCons, переданных через командную строку:

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

Вы также можете отключить некоторые встроенные модули перед компиляцией, что сэкономит время на сборку движка. Подробнее см. на странице Оптимизация размера билда.

См. также

Вы можете использовать онлайн-генератор параметров сборки Godot <https://godot-build-options-generator.github.io/>`__ для создания файла custom.py, содержащего параметры SCons. Затем сохраните этот файл и поместите его в корень исходного каталога 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 для всех будущих сборок:

export SCONSFLAGS="-j4"

Сборка SCU (единая единица компиляции)

Обычные сборки, как правило, являются узким местом из-за включения большого количества заголовочных файлов в каждый блок трансляции компиляции. Godot предлагает сборку "единым блоком компиляции" (также известную как "Unity/Jumbo"), в первую очередь для ускорения разработки (а не для производственных сборок).

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

Для выполнения сборки SCU используйте опцию scu_build=yes SCons.

Примечание

При разработке запроса на включение изменений с использованием сборок SCU обязательно создайте обычную сборку перед отправкой запроса на включение изменений. Это связано с тем, что сборки SCU по своей природе включают заголовки из более ранних файлов .cpp в единицу трансляции, поэтому не смогут перехватить все необходимые включения в обычной сборке. Непрерывная интеграция (CI) выявит эти ошибки, но обычно быстрее будет отловить их в локальной сборке на вашем компьютере.

Экспорт шаблонов

Официальные шаблоны экспорта загружаются с официального сайта Godot: 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

Чтобы создать их самостоятельно, следуйте инструкциям для каждой платформы в этом же разделе руководства. Для каждой платформы объясняется, как создать свой собственный шаблон.

The version.txt file should contain the corresponding Godot version identifier. This file is used to install export templates in a version-specific directory to avoid conflicts. For instance, if you are building export templates for Godot 4.4.1, version.txt should contain 4.4.1.stable on the first line (and nothing else). This version identifier is based on the major, minor, patch (if present) and status lines of the version.py file in the Godot Git repository.

Если вы разрабатываете для нескольких платформ, macOS, безусловно, самая удобная платформа для кросс-компиляции, поскольку позволяет выполнять кросс-компиляцию для любой целевой платформы. Linux и Windows идут на втором месте, но у Linux есть преимущество: это более простая платформа для настройки.