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

Знайомство з системою побудови

Godot — це переважно проєкт на C++, який uses the SCons build system. Ми любимо SCons за те, наскільки зручною в обслуговуванні та налаштуванні робить нашу систему збірки. І завдяки цьому компіляція Godot з вихідного коду може бути такою ж простою, як запуск:

scons

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

scons target=template_release

Якщо ви плануєте налагоджувати або розробляти рушій, можливо, вам варто ввімкнути опцію dev_build, щоб увімкнути код налагодження лише для розробників:

scons dev_build=yes

У наступних розділах статті докладніше пояснюється ці та інші універсальні варіанти. Але перш ніж ви зможете скомпілювати Godot, вам потрібно встановити кілька попередніх умов. Щоб дізнатися більше, зверніться до документації платформи:

У цих статтях детально описано як налаштувати ваше середовище для компіляції Godot на певній платформі, так і як компілювати для цієї платформи. Будь ласка, не соромтеся переходити між ними та цією статтею, щоб посилатися на специфічні для платформи та універсальні параметри конфігурації.

Використання багатопоточності

Процес збірки може тривати деякий час, залежно від потужності вашої системи. За замовчуванням, налаштування SCons у Godot налаштоване на використання всіх потоків процесора, крім одного (щоб система реагувала швидко під час компіляції). Якщо система має 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>

Щоб створити для платформи (наприклад, linux bsd), запустіть аргумент 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), вимкнено для всіх інших. Вимкнення редактора створює двійковий файл, який може запускати проекти, але не включає редактор або менеджер проекту.

Список доступних аргументів командного рядка command line arguments залежить від типу збірки.

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

Псевдоніми розробки та виробництва

Створюючи збірки для розробки (виконуючи інструменти debugging/profiling), ви часто маєте інші цілі порівняно з робочими збірками (створення двійкових файлів якомога швидших і менших).

Godot пропонує два псевдоніми для цієї мети:

  • dev_mode=yes — це псевдонім для verbose=yes warnings=extra werror=yes tests=yes. Це вмикає поведінку попереджень як помилок (подібно до налаштування безперервної інтеграції Godot), а також створює unit tests, щоб ви могли запускати їх локально.

  • 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_build не слід плутати з dev_mode, який є псевдонімом для кількох параметрів, пов’язаних з розробкою (див. вище).

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

scons platform=<platform> dev_build=yes

Цей прапорець додає суфікс .dev (для розробки) до згенерованого двійкового імені.

Дивись також

Існують додаткові параметри SCons для ввімкнення дезінфікуючих засобів, які є інструментами, які можна ввімкнути під час компіляції для кращого усунення певних проблем двигуна. Перегляньте Використання дезінфікуючих засобів для отримання додаткової інформації.

Налагоджувальні символи

За замовчуванням використовується 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 (за умовчанням, якщо націлено на не-веб-платформи): надає перевагу швидкості виконання за рахунок більшого двійкового розміру. Оптимізація іноді може негативно вплинути на використання налагоджувача (трасування стека може бути менш точним. Якщо це станеться з вами, використовуйте натомість 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++. Вам доведеться передавати аргументи вручну за допомогою параметрів cflags, ccflags і cxxflags SCons.

Архітектура

Параметр arch призначений для керування версією ЦП або ОС, призначеною для запуску двійкових файлів. Він зосереджений переважно на настільних платформах і ігнорується скрізь.

Підтримувані значення для опції 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, який очистить артефакти збірки для всіх платформ і конфігурацій. Будьте обережні, оскільки це видалить усі невідстежувані та проігноровані файли зі сховища. Не запускайте цю команду, якщо у вас є незакріплена робота!

Інші параметри збирання

Існує кілька інших параметрів збірки, які ви можете використовувати, щоб налаштувати спосіб збирання 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, використовуйте параметр SCons scu_build=yes.

Примітка

Розробляючи Pull Request за допомогою збірок SCU, обов’язково зробіть регулярну збірку перед подачею PR. Це пояснюється тим, що збірки SCU за своєю природою включають заголовки з попередніх файлів .cpp в одиниці перекладу, тому не вловлюють усі включення, які вам знадобляться у звичайній збірці. КІ виловить ці помилки, але зазвичай це буде швидше виявити їх у локальній збірці на вашій машині.

Шаблони експорту

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

Щоб створити їх самостійно, дотримуйтесь інструкцій, докладних для кожної платформи в тому самому розділі підручника. Кожна платформа пояснює, як створити власний шаблон.

Файл version.txt повинен містити відповідний ідентифікатор версії Godot. Цей файл використовується для встановлення шаблонів експорту в каталог, що відповідає версії, щоб уникнути конфліктів. Наприклад, якщо ви створюєте шаблони експорту для Godot 4.4.1, version.txt повинен містити 4.4.1.stable у першому рядку (і нічого більше). Цей ідентифікатор версії базується на рядках major, minor, patch (якщо є) та status файлу version.py у репозиторії Godot Git.

Якщо ви розробляєте для кількох платформ, macOS, безперечно, є найзручнішою хост-платформою для крос-компіляції, оскільки ви можете крос-компілювати для кожної цілі. Linux і Windows займають друге місце, але Linux має перевагу в тому, що є простішою платформою для налаштування.