Merge pull request #3554 from Xrayez/override-build-opts

Describe a way to override build options via a file and SCONSFLAGS

development/compiling/introduction_to_the_buildsystem.rst

@@ -192,6 +192,75 @@ features to include/disable.
 Check the output of ``scons --help`` for details about each option for
 the version you are willing to compile.
 
+.. _doc_overriding_build_options:
+
+Overriding the build options
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Using a file
+^^^^^^^^^^^^
+
+The default ``custom.py`` file can be created at the root of the Godot Engine
+source to initialize any SCons build options passed via the command line:
+
+.. code-block:: python
+
+    # custom.py
+    
+    optimize = "size"
+    module_mono_enabled = "yes"
+    use_llvm = "yes"
+    extra_suffix = "game_title"
+
+You can also disable some of the builtin modules before compiling, saving some
+time it takes to build the engine, see :ref:`doc_optimizing_for_size` page for more details.
+
+Another custom file can be specified explicitly with the ``profile`` command
+line option, both overriding the default build configuration:
+
+.. code-block:: shell
+
+    scons profile=path/to/custom.py
+
+.. note:: Build options set from the file can be overridden by the command line
+          options.
+
+It's also possible to override the options conditionally:
+
+.. code-block:: python
+
+    # 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
+
+Using the SCONSFLAGS
+^^^^^^^^^^^^^^^^^^^^
+
+``SCONSFLAGS`` is an environment variable which is used by the SCons to set the
+options automatically without having to supply them via the command line.
+
+For instance, you may want to build Godot in parallel with the aforementioned
+``-j`` option for all the future builds:
+
+.. tabs::
+ .. code-tab:: bash Linux/macOS
+
+     export SCONSFLAGS="-j4"
+
+ .. code-tab:: bat Windows (cmd)
+
+     set SCONSFLAGS=-j4
+
+ .. code-tab:: powershell Windows (powershell)
+
+     $env:SCONSFLAGS="-j4"
+
 Export templates
 ----------------
 

development/compiling/optimizing_for_size.rst

@@ -63,6 +63,52 @@ modules and see which ones you actually still need for your game (e.g. you
 might want to keep networking-related modules, regex support, or theora/webm
 to play videos).
 
+Alternatively, you can supply a list of disabled modules by creating
+``custom.py`` at the root of the source, with the contents similar to the
+following:
+
+.. code-block:: python
+
+    # custom.py
+    
+    module_arkit_enabled = "no"
+    module_assimp_enabled = "no"
+    module_bmp_enabled = "no"
+    module_bullet_enabled = "no"
+    module_camera_enabled = "no"
+    module_csg_enabled = "no"
+    module_dds_enabled = "no"
+    module_enet_enabled = "no"
+    module_etc_enabled = "no"
+    module_gdnative_enabled = "no"
+    module_gridmap_enabled = "no"
+    module_hdr_enabled = "no"
+    module_jsonrpc_enabled = "no"
+    module_mbedtls_enabled = "no"
+    module_mobile_vr_enabled = "no"
+    module_opensimplex_enabled = "no"
+    module_opus_enabled = "no"
+    module_pvr_enabled = "no"
+    module_recast_enabled = "no"
+    module_regex_enabled = "no"
+    module_squish_enabled = "no"
+    module_svg_enabled = "no"
+    module_tga_enabled = "no"
+    module_theora_enabled = "no"
+    module_tinyexr_enabled = "no"
+    module_upnp_enabled = "no"
+    module_vhacd_enabled = "no"
+    module_vorbis_enabled = "no"
+    module_webm_enabled = "no"
+    module_webp_enabled = "no"
+    module_webrtc_enabled = "no"
+    module_websocket_enabled = "no"
+    module_xatlas_unwrap_enabled = "no"
+    
+.. seealso::
+
+    :ref:`doc_overriding_build_options`.
+
 Optimizing for size instead of speed
 ------------------------------------