Merge pull request #11222 from Calinou/add-engine-compilation-configuration-editor

Add documentation on using the Engine compilation configuration editor

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 <class_@GlobalScope_method_print_rich>`.
 
+- The editor can
+  :ref:`detect features used in a project and create a compilation profile <doc_engine_compilation_configuration_editor>`,
+  which can be used to create smaller export template binaries
+  with unneeded features disabled.
 - Support for :ref:`C++ modules <doc_custom_modules_in_cpp>` 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 <doc_introduction_to_the_buildsystem>` using GCC,

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

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

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 <doc_compiling_index>`
+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 <doc_evaluating_expressions>`.
+- Features that are used in :ref:`GDExtensions <doc_gdextension>`, unless the language binding
+  allows for defining used classes and the extension makes use of the functionality.
+  See `GH-104129 <https://github.com/godotengine/godot/pull/104129>`__ for details.
+- Features that are used in :ref:`external PCKs loaded at runtime <doc_exporting_pcks>`.
+- Certain edge cases may exist. If unsure, please
+  `open an issue on GitHub <https://github.com/godotengine/godot/issues>`__
+  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.