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

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

Процес збирання може зайняти деякий час, залежно від потужності вашої системи. За замовчуванням налаштування Godot SCons налаштовано на використання всіх потоків процесора, крім одного (щоб підтримувати реакцію системи під час компіляції). Якщо ви хочете налаштувати, скільки потоків ЦП використовуватиме SCons, використовуйте параметр -j <threads>, щоб вказати, скільки потоків використовуватиметься для збірки.

Приклад використання 4-х ниток:

scons -j4

Вибір платформи

Система збірки 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 контролює, якщо міститься редактор і використовуються позначки налагодження. Усі збірки оптимізовані. Кожен режим означає:

  • target=editor: збірка за допомогою редактора, оптимізована, з кодом налагодження (визначає: TOOLS_ENABLED, DEBUG_ENABLED, -O2//O2)

  • target=template_debug: збірка за допомогою символів налагодження C++ (визначає: DEBUG_ENABLED, -O2//O2)

  • target=template_release: збірка без символів (визначає: -O3//O2)

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

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

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

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

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

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

  • 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, щоб мати доступ до символів налагодження.

Використовуючи 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=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"

You can also disable some of the built-in modules before compiling, saving some time it takes to build the engine. See Оптимізація збірки за розміром page for more details.

Дивись також

Ви можете використати онлайн-генератор параметрів збірки 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.

Примітка

When developing a Pull Request using SCU builds, be sure to make a regular build prior to submitting the PR. This is because SCU builds by nature include headers from earlier .cpp files in the translation unit, therefore won't catch all the includes you will need in a regular build. The CI will catch these errors, but it will usually be faster to catch them on a local build on your machine.

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

Офіційні шаблони експорту завантажуються з сайту 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 3.1.1, version.txt має містити 3.1.1.stable у першому рядку (і нічого більше). Цей ідентифікатор версії базується на рядках major, minor, patch (якщо є) і status файлу version.py у сховищі Godot Git.

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