diff --git a/about/list_of_features.rst b/about/list_of_features.rst index b3fcee1572c..f0f69792e0b 100644 --- a/about/list_of_features.rst +++ b/about/list_of_features.rst @@ -669,7 +669,7 @@ XR support (AR and VR) - Currently only exporting an application for use on a flat plane within the headset is supported. Immersive experiences are not supported. - + - Other devices supported through an XR plugin structure. - Various advanced toolkits are available that implement common features required by XR applications. @@ -776,8 +776,16 @@ Miscellaneous - Print colored text to standard output on all platforms using :ref:`print_rich `. +- The editor can + :ref:`detect features used in a project and create a compilation profile `, + which can be used to create smaller export template binaries + with unneeded features disabled. - Support for :ref:`C++ modules ` statically linked into the engine binary. + + - Most built-in modules can be disabled at compile-time to reduce binary size + in custom builds. See :ref:`doc_optimizing_for_size` for details. + - Engine and editor written in C++17. - Can be :ref:`compiled ` using GCC, diff --git a/engine_details/development/compiling/optimizing_for_size.rst b/engine_details/development/compiling/optimizing_for_size.rst index bb0ac935c77..768ebc370ef 100644 --- a/engine_details/development/compiling/optimizing_for_size.rst +++ b/engine_details/development/compiling/optimizing_for_size.rst @@ -93,6 +93,29 @@ Godot 4.5 introduced the ``size_extra`` option, which can further reduce size. scons target=template_release optimize=size_extra +Detecting used features from the current project and disabling unused features +------------------------------------------------------------------------------ + +- **Space savings:** Moderate to high depending on project +- **Difficulty:** Easy to medium depending on project +- **Performed in official builds:** No + +Godot features an :ref:`doc_engine_compilation_configuration_editor` tool that can detect +the features used in the current project and create a build profile. Once saved, +this build profile can then be passed to SCons when compiling custom export templates: + +:: + + scons target=template_release build_profile=/path/to/profile.gdbuild + +Note that for certain projects, the feature detection may be too aggressive and disable +features that are actually needed at runtime. This can occur if certain features are used +in a way that their usage cannot be detected statically (such as a script being procedurally +created and run at runtime). + +More specific features can be disabled by following the sections below, but remember +that many of them are automatically detected by the engine compilation configuration detector. + Disabling advanced text server ------------------------------ diff --git a/tutorials/editor/img/engine_compilation_configuration_editor_detect.webp b/tutorials/editor/img/engine_compilation_configuration_editor_detect.webp new file mode 100644 index 00000000000..6ced779da87 Binary files /dev/null and b/tutorials/editor/img/engine_compilation_configuration_editor_detect.webp differ diff --git a/tutorials/editor/img/engine_compilation_configuration_editor_detected.webp b/tutorials/editor/img/engine_compilation_configuration_editor_detected.webp new file mode 100644 index 00000000000..72427bf1680 Binary files /dev/null and b/tutorials/editor/img/engine_compilation_configuration_editor_detected.webp differ diff --git a/tutorials/editor/index.rst b/tutorials/editor/index.rst index 572eb6aa80d..66b364173bc 100644 --- a/tutorials/editor/index.rst +++ b/tutorials/editor/index.rst @@ -81,6 +81,7 @@ like Visual Studio Code or Emacs. command_line_tutorial external_editor + using_engine_compilation_configuration_editor Managing editor features ------------------------ diff --git a/tutorials/editor/using_engine_compilation_configuration_editor.rst b/tutorials/editor/using_engine_compilation_configuration_editor.rst new file mode 100644 index 00000000000..aea286140e9 --- /dev/null +++ b/tutorials/editor/using_engine_compilation_configuration_editor.rst @@ -0,0 +1,107 @@ +.. _doc_engine_compilation_configuration_editor: + +Using the engine compilation configuration editor +================================================= + +Godot comes with a large set of built-in features. While this is convenient, +this also means its binary size is larger than it could be, especially +for projects that only use a small portion of its feature set. + +To help reduce binary size, it is possible to compile custom export templates +with certain features disabled. This is described in detail in :ref:`doc_optimizing_for_size`. +However, determining which features need to be disabled can be a tedious task. +The engine compilation configuration editor aims to address this +by providing an interface to view and manage these features easily, +while also being able to detect the features currently being used in the project. + +The :menu:`Project > Tools > Engine Compilation Configuration Editor` +allows you to create and manage build profiles for your Godot project. + +From now on, you have two possibilities: + +- View the list and manually uncheck features that you don't need. +- Use the :button:`Detect from Project` button to automatically detect features + currently used in the project and disable unused features. Note that this will + override the existing list of features, so if you have manually unchecked some + items, their state will be reset based on whether the project actually + uses the feature. + +.. figure:: img/engine_compilation_configuration_editor_detect.webp + :align: center + :alt: Opening the Engine Compilation Configuration Editor + + Opening the Engine Compilation Configuration Editor + +Once you click :button:`Detect from Project`, the project detection step will run. +This can take from a few seconds up to several minutes depending on the project size. +Once detection is complete, you'll see an updated list of features with some features disabled: + +.. figure:: img/engine_compilation_configuration_editor_detected.webp + :align: center + :alt: Updated features list after using feature detection (example from the 3D platformer demo) + + Updated features list after using feature detection (example from the 3D platformer demo) + +.. warning:: + + Unchecking features in this dialog will not reduce binary size directly on export. + Since it is only possible to actually remove features from the binary at compile-time, + you still need to compile custom export templates with the build profile specified + to actually benefit from the engine compilation configuration editor. + +You can now save the build profile by clicking **Save As** at the top. +The build profile can be saved in any location, but it's a good idea to +save it somewhere in your project folder and add it to version control to be able +to go back to it later when needed. This also allows using version control +to track changes to the build profile. + +The build profile is a JSON file (and ``.gdbuild`` extension) that looks like this +after detection in the above example: + +:: + + { + "disabled_build_options": { + "disable_navigation_3d": true, + "disable_xr": true, + "module_godot_physics_3d_enabled": false, + "module_msdfgen_enabled": false, + "module_openxr_enabled": false + }, + "disabled_classes": [ + "AESContext", + ... + "ZIPReader" + ], + "type": "build_profile" + } + +This file can be passed as a SCons option when :ref:`compiling ` +export templates: + +:: + + scons target=template_release build_profile=/path/to/profile.gdbuild + +The buildsystem will use this to disable unused classes and reduce binary size as a result. + +Limitations +----------- + +The :button:`Detect from Project` functionality relies on reading the project's scenes and scripts. +It will not be able to detect used features in the following scenarios: + +- Features that are used in GDScripts that are procedurally created then run at runtime. +- Features that are used in :ref:`expressions `. +- Features that are used in :ref:`GDExtensions `, unless the language binding + allows for defining used classes and the extension makes use of the functionality. + See `GH-104129 `__ for details. +- Features that are used in :ref:`external PCKs loaded at runtime `. +- Certain edge cases may exist. If unsure, please + `open an issue on GitHub `__ + with a minimal reproduction project attached. + +.. seealso:: + + You can achieve further size reductions by passing other options that reduce binary size. + See :ref:`doc_optimizing_for_size` for more information.