Configuring the build¶
Note
This page assumes that you’ve read Building from source.
Extension¶
The root SConstruct allows you to compile the engine with the extension by
running the same scons command, and the behavior can be configured.
By default, running scons from within Goost source root will clone the Godot
repository within the current working directory. If you’d like to prevent this
behavior, you can define GODOT_SOURCE_PATH environment variable pointing to
Godot source within your filesystem before compiling:
export GODOT_SOURCE_PATH="/path/to/godot"
set GODOT_SOURCE_PATH=C:\src\godot
$env:GODOT_SOURCE_PATH="C:/src/godot"
If the path is invalid, the script shall try to find Godot at the parent
directory. If this fails too, then the Godot repository is cloned from the
remote URL defined by GODOT_REPO_URL environment variable, which can be
configured similarly as above.
Command-line options¶
| SCons build option | Description | Default value |
godot_version |
Godot version to build. Accepts the branch names, tags, git commit hashes. Can be overridden with GODOT_VERSION env var. |
Run scons --help |
godot_sync |
Synchronize Godot version from remote GODOT_REPO_URL before building. |
no |
godot_modules_enabled |
Build all Godot builtin modules. If no, disables modules which are not essential to build to test out Goost. |
yes |
use_godot_patches |
Apply custom fixes and small enhancements to Godot source before building from the godot_patches directory. |
no |
godot_patches |
A directory path containing custom Godot patches. Patches at the default directory won’t be applied if using a custom path. | "misc/patches" |
Usage examples¶
Compile the stable version of the engine with Goost:
scons godot_version=3.3-stable
Compile the beta or development versions of the engine, synchronizing any changes from remote URL automatically:
scons godot_version=3.3 godot_sync=yes
Disable non-essential Godot modules for testing and development purposes (speeds up compilation, optimizes for size):
scons godot_modules_enabled=no
Components¶
By default, all extension components are built, but it’s also possible to
disable them. Disabling a single component involves compiling the engine with
one of the goost_*_enabled build options:
scons goost_math_enabled=no
It’s also possible to disable a entire branch of components:
# For instance, this disables both ``image`` and ``math`` components.
scons goost_core_enabled=no
See each component build options in the Components section.
Modules¶
The extension provides as set of optional modules (regular C++ modules just like
this extension) which are compiled alongside this extension by default if you
build the engine from within Goost root with the scons command.
If you compile the Goost extension externally, those modules can be compiled by
appending to the list of paths specified by custom_modules option:
scons custom_modules="/path/to/dir/containing/goost,/path/to/goost/modules"
It’s possible to compile the modules independently of whether Goost is enabled:
scons module_goost_enabled="no" custom_modules="/path/to/goost/modules"
Configuring modules¶
Goost distinguishes between built-in and community modules. Built-in modules are
officially maintained by the Goost authors and are versioned as part of the
extension. Community modules represent git submodules which are maintained
by third-party developers.
The disable_builtin.py and disable_community.py configuration scripts
located at modules/ directory aim to list all modules in such a way that
they can be disabled by users, as modules are enabled by default once detected
by the build system, unless they are explicitly disabled via
config.py::is_enabled method per each module.
If you’d like to opt-out from compiling certain modules, you’ll have to disable each of the unused modules explicitly:
scons custom_modules="/path/to/dir/containing/goost,/path/to/goost/modules" \
module_a_enabled="no" module_b_enabled="no" module_c_enabled="no" ...
All of the above options can be conveniently defined by creating custom.py at
the root of Godot source, or pointing to an existing configuration file such as
above:
scons profile="modules/goost/disable_community.py"
Community modules can be fetched with:
git submodule update --init --recursive
Or if you haven’t yet cloned Goost:
git clone https://github.com/goostengine/goost.git --recurse-submodules
Patching¶
The Godot core cannot be modified without tinkering with the engine source, but in some cases, it’s necessary to do so.
The engine can be optionally modified by applying custom git diff patches
which match *.patch or *.diff filenames automatically. This is disabled
by default, and can be enabled with the use_godot_patches build option:
scons use_godot_patches=yes
By default, patches are searched within the built-in misc/patches directory
in Goost. All patches in the directory are collected and applied automatically
before building Godot with Goost.
Note
Patching only works if you have Godot cloned under the Goost directory.
The godot_patches build option can be overridden to point to a custom
directory path. If you do specify a custom directory, the built-in patches will
not be applied. It’s recommended that you copy built-in patches to your own
directory instead:
scons use_godot_patches=yes godot_patches=/path/to/custom/patches
The built-in misc/patches directory exists for the purpose of collecting
various patches which may benefit other developers, and may not always apply
to the current version of Godot.
Creating patches¶
The following commands can be run to generate patches from within Godot Engine repository:
# From committed changes:
git format-patch HEAD~1 -o ../misc/patches/custom.patch
# From non-committed changes (working tree):
git diff > ../misc/patches/custom.patch
# From a pull request/remotely:
curl https://github.com/godotengine/godot/pull/42653.patch > custom.patch
# From committed changes:
git format-patch HEAD~1 --stdout | Out-File -Encoding utf8 ../misc/patches/custom.patch
# From non-committed changes (working tree):
git diff | Out-File -Encoding utf8 ../misc/patches/custom.patch
# From a pull request/remotely:
Invoke-RestMethod "https://github.com/godotengine/godot/pull/42653.patch" | Select-Object -Expand Content | Out-File -Encoding utf8 "custom.patch"
On some systems, the resulting patch encoding and line endings may not be
compatible with git, so they may fail to apply. Patches must use utf8
encoding and have LF line endings.