Document the Unification of tools/target build type configuration (#6316

)

Document the Unification of tools/target build type configuration

Introduced in godotengine/godot#66242 the
`tools=yes/no` option was removed and merged into the `target` preset.

Includes miscellaneous fixes identified during code review as well

Co-authored-by: Raul Santos <[email protected]>
Co-authored-by: Marius Hanl <[email protected]>
Co-authored-by: Clay John <[email protected]>

development/compiling/compiling_for_android.rst

@@ -94,8 +94,8 @@ root directory with the following arguments:
 
 ::
 
-    scons platform=android target=release android_arch=armv7
-    scons platform=android target=release android_arch=arm64v8
+    scons platform=android target=template_release arch=armv7
+    scons platform=android target=template_release arch=arm64v8
     cd platform/android/java
     # On Windows
     .\gradlew generateGodotTemplates
@@ -109,8 +109,8 @@ The resulting APK will be located at ``bin/android_release.apk``.
 
 ::
 
-    scons platform=android target=release_debug android_arch=armv7
-    scons platform=android target=release_debug android_arch=arm64v8
+    scons platform=android target=template_debug arch=armv7
+    scons platform=android target=template_debug arch=arm64v8
     cd platform/android/java
     # On Windows
     .\gradlew generateGodotTemplates
@@ -130,16 +130,16 @@ Adding support for x86 devices
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 If you also want to include support for x86 and x86-64 devices, run the SCons
-command a third and fourth time with the ``android_arch=x86``, and
-``android_arch=x86_64`` arguments before building the APK with Gradle. For
+command a third and fourth time with the ``arch=x86_32``, and
+``arch=x86_64`` arguments before building the APK with Gradle. For
 example, for the release template:
 
 ::
 
-    scons platform=android target=release android_arch=armv7
-    scons platform=android target=release android_arch=arm64v8
-    scons platform=android target=release android_arch=x86
-    scons platform=android target=release android_arch=x86_64
+    scons platform=android target=template_release arch=armv7
+    scons platform=android target=template_release arch=arm64v8
+    scons platform=android target=template_release arch=x86
+    scons platform=android target=template_release arch=x86_64
     cd platform/android/java
     # On Windows
     .\gradlew generateGodotTemplates
@@ -214,10 +214,10 @@ root directory with the following arguments:
 
 ::
 
-   scons platform=android android_arch=armv7 production=yes tools=yes target=release_debug
-   scons platform=android android_arch=arm64v8 production=yes tools=yes target=release_debug
-   scons platform=android android_arch=x86 production=yes tools=yes target=release_debug
-   scons platform=android android_arch=x86_64 production=yes tools=yes target=release_debug
+   scons platform=android arch=armv7 production=yes target=editor
+   scons platform=android arch=arm64v8 production=yes target=editor
+   scons platform=android arch=x86 production=yes target=editor
+   scons platform=android arch=x86_64 production=yes target=editor
    cd platform/android/java
    # On Windows
    .\gradlew generateGodotEditor
@@ -289,8 +289,8 @@ one of the following reasons:
 
 -  Make sure to use export templates that match your editor version; if
    you use a new Godot version, you *have* to update the templates too.
--  ``libgodot_android.so`` is not in ``libs/<android_arch>/``
-   where ``<android_arch>`` is the device's architecture.
+-  ``libgodot_android.so`` is not in ``libs/<arch>/``
+   where ``<arch>`` is the device's architecture.
 -  The device's architecture does not match the exported one(s).
    Make sure your templates were built for that device's architecture,
    and that the export settings included support for that architecture.

development/compiling/compiling_for_linuxbsd.rst

@@ -149,7 +149,7 @@ manager.
 
 .. note:: If you are compiling Godot for production use, then you can
           make the final executable smaller and faster by adding the
-          SCons option ``target=release_debug``.
+          SCons options ``target=template_release production=yes``.
 
           If you are compiling Godot with GCC, you can make the binary
           even smaller and faster by adding the SCons option ``use_lto=yes``.
@@ -161,23 +161,27 @@ manager.
           :ref:`doc_data_paths_self_contained_mode` by creating a file called
           ``._sc_`` or ``_sc_`` in the ``bin/`` folder.
 
-Compiling a headless/server build
----------------------------------
+Running a headless/server build
+-------------------------------
 
-To compile a *headless* build which provides editor functionality to export
-projects in an automated manner, use::
+To run in *headless* mode which provides editor functionality to export
+projects in an automated manner, use the normal build::
 
-    scons -j8 platform=server tools=yes target=release_debug
+    scons -j8 platform=linuxbsd target=editor
+
+And then use the ``--headless`` command line argument::
+
+    ./bin/godot.linuxbsd.editor.x86_64 --headless
 
 To compile a debug *server* build which can be used with
 :ref:`remote debugging tools <doc_command_line_tutorial>`, use::
 
-    scons -j8 platform=server tools=no target=release_debug
+    scons -j8 platform=linuxbsd target=template_debug
 
 To compile a *server* build which is optimized to run dedicated game servers,
 use::
 
-    scons -j8 platform=server tools=no target=release
+    scons -j8 platform=linuxbsd target=template_release production=yes
 
 Building export templates
 -------------------------
@@ -197,15 +201,15 @@ following parameters:
 
 ::
 
-    scons platform=linuxbsd tools=no target=release bits=32
-    scons platform=linuxbsd tools=no target=release_debug bits=32
+    scons platform=linuxbsd target=template_release arch=x86_32
+    scons platform=linuxbsd target=template_debug arch=x86_32
 
 -  (64 bits)
 
 ::
 
-    scons platform=linuxbsd tools=no target=release bits=64
-    scons platform=linuxbsd tools=no target=release_debug bits=64
+    scons platform=linuxbsd target=template_release arch=x86_64
+    scons platform=linuxbsd target=template_debug arch=x86_64
 
 Note that cross-compiling for the opposite bits (64/32) as your host
 platform is not always straight-forward and might need a chroot environment.

development/compiling/compiling_for_macos.rst

@@ -94,44 +94,48 @@ editor binary built with ``target=release_debug``::
         mkdir -p Godot.app/Contents/Frameworks
         cp <Vulkan SDK path>/macOS/lib/libMoltenVK.dylib Godot.app/Contents/Frameworks/libMoltenVK.dylib
 
-Compiling a headless/server build
----------------------------------
+Running a headless/server build
+-------------------------------
 
-To compile a *headless* build which provides editor functionality to export
-projects in an automated manner, use::
+To run in *headless* mode which provides editor functionality to export
+projects in an automated manner, use the normal build::
 
-    scons platform=server tools=yes target=release_debug --jobs=$(sysctl -n hw.logicalcpu)
+    scons platform=macos target=editor --jobs=$(sysctl -n hw.logicalcpu)
+
+And then use the ``--headless`` command line argument::
+
+    ./bin/godot.macos.editor.x86_64 --headless
 
 To compile a debug *server* build which can be used with
 :ref:`remote debugging tools <doc_command_line_tutorial>`, use::
 
-    scons platform=server tools=no target=release_debug --jobs=$(sysctl -n hw.logicalcpu)
+    scons platform=macos target=template_debug --jobs=$(sysctl -n hw.logicalcpu)
 
 To compile a release *server* build which is optimized to run dedicated game servers,
 use::
 
-    scons platform=server tools=no target=release --jobs=$(sysctl -n hw.logicalcpu)
+    scons platform=macos target=template_release production=yes --jobs=$(sysctl -n hw.logicalcpu)
 
 Building export templates
 -------------------------
 
-To build macOS export templates, you have to compile with ``tools=no`` (no
-editor) and respectively for ``target=release`` (release template) and
-``target=release_debug``.
+To build macOS export templates, you have to compile using the targets without
+the editor: ``target=template_release`` (release template) and
+``target=template_debug``.
 
 Official templates are universal binaries which support both Intel x86_64 and
 ARM64 architectures. You can also create export templates that support only one
 of those two architectures by leaving out the ``lipo`` step below.
 
 - For Intel x86_64::
 
-    scons platform=macos tools=no target=release arch=x86_64 --jobs=$(sysctl -n hw.logicalcpu)
-    scons platform=macos tools=no target=release_debug arch=x86_64 --jobs=$(sysctl -n hw.logicalcpu)
+    scons platform=macos target=template_release arch=x86_64 --jobs=$(sysctl -n hw.logicalcpu)
+    scons platform=macos target=template_debug arch=x86_64 --jobs=$(sysctl -n hw.logicalcpu)
 
 - For ARM64 (Apple M1)::
 
-    scons platform=macos tools=no target=release arch=arm64 --jobs=$(sysctl -n hw.logicalcpu)
-    scons platform=macos tools=no target=release_debug arch=arm64 --jobs=$(sysctl -n hw.logicalcpu)
+    scons platform=macos target=template_release arch=arm64 --jobs=$(sysctl -n hw.logicalcpu)
+    scons platform=macos target=template_debug arch=arm64 --jobs=$(sysctl -n hw.logicalcpu)
 
 To support both architectures in a single "Universal 2" binary, run the above
 two commands blocks and then use ``lipo`` to bundle them together::

development/compiling/compiling_for_uwp.rst

@@ -66,8 +66,8 @@ be able to export.
 Open the command prompt for one architecture and run SCons twice (once for
 each target)::
 
-    C:\godot>scons platform=uwp target=release_debug
-    C:\godot>scons platform=uwp target=release
+    C:\godot>scons platform=uwp target=template_debug
+    C:\godot>scons platform=uwp target=template_release
 
 Repeat for the other architectures.
 

development/compiling/compiling_for_web.rst

@@ -34,18 +34,18 @@ and ``source ./emsdk_env.sh``/``emsdk_env.bat``.
 
 Open a terminal and navigate to the root directory of the engine source code.
 Then instruct SCons to build the Web platform. Specify ``target`` as
-either ``release`` for a release build or ``release_debug`` for a debug build::
+either ``template_release`` for a release build or ``template_debug`` for a debug build::
 
-    scons platform=web tools=no target=release
-    scons platform=web tools=no target=release_debug
+    scons platform=web target=template_release
+    scons platform=web target=template_debug
 
 By default, the :ref:`JavaScript singleton <doc_javascript_eval>` will be built
 into the engine. Official export templates also have the JavaScript singleton
 enabled. Since ``eval()`` calls can be a security concern, the
 ``javascript_eval`` option can be used to build without the singleton::
 
-    scons platform=web tools=no target=release javascript_eval=no
-    scons platform=web tools=no target=release_debug javascript_eval=no
+    scons platform=web target=template_release javascript_eval=no
+    scons platform=web target=template_debug javascript_eval=no
 
 The engine will now be compiled to WebAssembly by Emscripten. Once finished,
 the resulting file will be placed in the ``bin`` subdirectory. Its name is
@@ -71,8 +71,8 @@ performance and compatibility reasons. See the
 You can build the export templates using the option ``dlink_enabled=yes``
 to enable GDExtension support::
 
-    scons platform=web tools=no dlink_enabled=yes target=release
-    scons platform=web tools=no dlink_enabled=yes target=release_debug
+    scons platform=web dlink_enabled=yes target=template_release
+    scons platform=web dlink_enabled=yes target=template_debug
 
 Once finished, the resulting file will be placed in the ``bin`` subdirectory.
 Its name will have ``_dlink`` added.
@@ -90,7 +90,7 @@ It is also possible to build a version of the Godot editor that can run in the
 browser. The editor version is not recommended
 over the native build. You can build the editor with::
 
-    scons platform=web tools=yes target=release_debug
+    scons platform=web target=editor
 
 Once finished, the resulting file will be placed in the ``bin`` subdirectory.
 Its name will be ``godot.web.opt.tools.wasm32.zip``. You can upload the

development/compiling/compiling_for_windows.rst

@@ -149,15 +149,15 @@ option to any SCons command you see below.
 If all goes well, the resulting binary executable will be placed in
 ``C:\godot\bin\`` with the name ``godot.windows.tools.32.exe`` or
 ``godot.windows.tools.64.exe``. By default, SCons will build a binary matching
-your CPU architecture, but this can be overridden using ``bits=64`` or
-``bits=32``.
+your CPU architecture, but this can be overridden using ``arch=x86_64`` or
+``arch=x86_32``.
 
 This executable file contains the whole engine and runs without any
 dependencies. Running it will bring up the Project Manager.
 
 .. note:: If you are compiling Godot for production use, then you can
           make the final executable smaller and faster by adding the
-          SCons option ``target=release_debug``.
+          SCons option ``target=template_release``.
 
           If you are compiling Godot with MinGW, you can make the binary
           even smaller and faster by adding the SCons option ``use_lto=yes``.
@@ -269,10 +269,10 @@ Creating Windows export templates
 Windows export templates are created by compiling Godot without the editor,
 with the following flags::
 
-    C:\godot> scons platform=windows tools=no target=release_debug bits=32
-    C:\godot> scons platform=windows tools=no target=release bits=32
-    C:\godot> scons platform=windows tools=no target=release_debug bits=64
-    C:\godot> scons platform=windows tools=no target=release bits=64
+    C:\godot> scons platform=windows target=template_debug arch=x86_32
+    C:\godot> scons platform=windows target=template_release arch=x86_32
+    C:\godot> scons platform=windows target=template_debug arch=x86_64
+    C:\godot> scons platform=windows target=template_release arch=x86_64
 
 If you plan on replacing the standard export templates, copy these to the
 following location, replacing ``<version>`` with the version identifier