Update Working with CMake GDExtension documentation (#11370)

- Respect the 80 column rule.
- Be more explicit in code blocks.
- Re-arrange for faster grokking.
- Remove half-made tested toolchain section.
- Fix /s/mutially inclusive/mutially exclusive.
- Remove old warning.
- Update examples.

Co-authored-by: A Thousand Ships <[email protected]>
Co-authored-by: Lukas Tenbrink <[email protected]>

tutorials/scripting/cpp/build_system/cmake.rst

@@ -1,106 +1,102 @@
 Secondary build system: Working with CMake
 ==========================================
 
-.. seealso:: This page documents how to compile godot-cpp. If you're looking to compile Godot instead, see
+.. seealso:: This page documents how to compile godot-cpp. If you're looking to
+             compile Godot instead, see
              :ref:`doc_introduction_to_the_buildsystem`.
 
-Beside the primary `SCons <https://scons.org>`__ based build system, godot-cpp also comes with a
-`CMakeLists.txt <https://github.com/godotengine/godot-cpp/blob/master/CMakeLists.txt>`__ file, to support users that
-prefer using `CMake <https://cmake.org>`__ over SCons for their build system.
+Beside the SCons_ based build system, godot-cpp also provides a CMakeLists.txt_
+file to support users that prefer using CMake_ over SCons for their build
+system.
 
-While actively supported, it is considered secondary to the SCons build system. This means it may lack some features
-that are available to projects using SCons.
+While actively supported, the CMake system is considered secondary to the
+SCons build system. This means it may lack some features that are available to
+projects using SCons.
 
-.. warning::
-
-    The CMake scripts do not have feature parity with the SCons ones at this
-    stage and are still a work in progress. There are a number of people who
-    have been working on alternative CMake solutions that are frequently
-    referenced in the Discord chats: Ivan's cmake-rewrite_ branch and
-    Vorlac's godot-roguelite_ project.
-
-.. _cmake-rewrite: https://github.com/IvanInventor/godot-cpp/tree/cmake-rewrite
-.. _godot-roguelite: https://github.com/vorlac/godot-roguelite
+.. _CMakeLists.txt: https://github.com/godotengine/godot-cpp/blob/master/CMakeLists.txt
+.. _CMake: http://scons.org
+.. _Scons: http://cmake.org
 
 Introduction
 ------------
 
 Compiling godot-cpp independently of an extension project is mainly for
-godot-cpp developers, package maintainers, and CI/CD. Look to the
-godot-cpp-template_ for a practical example on how to consume the godot-cpp
-library as part of a Godot extension.
+godot-cpp developers, package maintainers, and CI/CD.
+
+Examples of how to use CMake to consume the godot-cpp library as part of an
+extension project:
+
+* `godot-cpp-template <https://github.com/godotengine/godot-cpp-template/>`__
+* `godot_roguelite <https://github.com/vorlac/godot-roguelite/>`__
+* `godot-orchestrator <https://github.com/CraterCrash/godot-orchestrator/>`__
 
-Configuration examples are listed at the bottom of the page.
+Examples for configuring godot-cpp are listed at the bottom of the page, many
+of which may help with configuring your project.
 
-.. _godot-cpp-template: https://github.com/godotengine/godot-cpp-template
 
-Debug vs template_debug
------------------------
+CMake's ``Debug`` vs Godot's ``template_debug``
+-----------------------------------------------
 
-Something that has come come up many times is the conflation of a compilation of C++
-source code with debug symbols enabled, and compiling a Godot extension with
-debug features enabled. The two concepts are not mutually inclusive.
+Something that has come up during many discussions is the conflation of a
+compilation of C++ source code with debug symbols enabled, and compiling a
+Godot extension with debug features enabled. The two concepts are not mutually
+exclusive.
 
 - debug_features
     Enables a pre-processor definition to selectively compile code to help
     users of a Godot extension with their own project.
 
-    debug features are enabled in editor and template_debug builds, which can be specified during the configure phase like so:
+    debug features are enabled in ``editor`` and ``template_debug`` builds,
+    which can be specified during the configure phase like so:
 
-	``cmake -S . -B cmake-build -DGODOTCPP_TARGET=<target choice>``
+    .. code-block::
+
+        cmake -S godot-cpp -B cmake-build -DGODOTCPP_TARGET=<target choice>
 
 - Debug
     Sets compiler flags so that debug symbols are generated to help godot
     extension developers debug their extension.
 
-    ``Debug`` is the default build type for CMake projects, to select another it depends on the generator used
+    ``Debug`` is the default build type for CMake projects, to select another
+    it depends on the generator used
 
     For single configuration generators, add to the configure command:
 
-	``-DCMAKE_BUILD_TYPE=<type>``
+    ``-DCMAKE_BUILD_TYPE=<type>``
 
     For multi-config generators add to the build command:
 
-	``--config <type>``
+    ``--config <type>``
 
-    where ``<type>`` is one of ``Debug``, ``Release``, ``RelWithDebInfo``, ``MinSizeRel``
+    where ``<type>`` is one of ``Debug``, ``Release``, ``RelWithDebInfo``,
+    ``MinSizeRel``
 
 
 SCons Deviations
 ----------------
 
-Not everything from SCons can be perfectly represented in CMake, here are
-the notable differences.
+Not all code from the SCons system can be perfectly represented in CMake, here
+are the notable differences.
 
 - debug_symbols
-    No longer has an explicit option, and is enabled via Debug-like CMake
-    build configurations; ``Debug``, ``RelWithDebInfo``.
+    Is no longer an explicit option, and is enabled when using CMake build
+    configurations; ``Debug``, ``RelWithDebInfo``.
 
 - dev_build
-    Does not define ``NDEBUG`` when disabled, ``NDEBUG`` is set via Release-like
+    Does not define ``NDEBUG`` when disabled, ``NDEBUG`` is set when using
     CMake build configurations; ``Release``, ``MinSizeRel``.
 
 - arch
-    CMake sets the architecture via the toolchain files, macOS universal is controlled via the ``CMAKE_OSX_ARCHITECTURES``
+    CMake sets the architecture via the toolchain files, macOS universal is
+    controlled via the ``CMAKE_OSX_ARCHITECTURES``
     property which is copied to targets when they are defined.
 
 - debug_crt
-    CMake controls linking to Windows runtime libraries by copying the value of ``CMAKE_MSVC_RUNTIME_LIBRARIES`` to targets as they are defined.
-    godot-cpp will set this variable if it isn't already set. So, include it before other dependencies to have the value propagate across the projects.
-
-Testing Integration
--------------------
-
-The testing target ``godot-cpp-test`` is guarded by ``GODOTCPP_ENABLE_TESTING`` which is off by default.
+    CMake controls linking to Windows runtime libraries by copying the value of
+    ``CMAKE_MSVC_RUNTIME_LIBRARIES`` to targets as they are defined.
+    godot-cpp will set this variable if it isn't already set. So, include it
+    before other dependencies to have the value propagate across the projects.
 
-To configure and build the godot-cpp project to enable the integration
-testing targets the command will look something like:
-
-.. code-block::
-
-    # Assuming our current directory is the godot-cpp source root.
-    cmake -S . -B cmake-build -DGODOTCPP_ENABLE_TESTING=YES
-    cmake --build cmake-build --target godot-cpp-test
 
 Basic walkthrough
 -----------------
@@ -112,26 +108,68 @@ Basic walkthrough
         git clone https://github.com/godotengine/godot-cpp.git
         Cloning into 'godot-cpp'...
         ...
-        cd godot-cpp
 
-.. topic:: Options
 
-    To list the available options CMake use the ``-L[AH]`` option. ``A`` is for
-    advanced, and ``H`` is for help strings:
+.. topic:: Configure the build
+
+    .. code-block::
+
+        cmake -S godot-cpp -B cmake-build -G Ninja
+
+    ``-S`` Specifies the source directory as ``godot-cpp``
+
+    ``-B`` Specifies the build directory as ``cmake-build``
+
+    ``-G`` Specifies the Generator as ``Ninja``
+
+    The source directory in this example is the source root for the freshly
+    cloned godot-cpp. CMake will also interpret the first path in the command
+    as the source path, or if an existing build path is specified it will
+    deduce the source path from the build cache.
+
+    The following three commands are equivalent.
 
     .. code-block::
 
-        cmake .. -LH
+        # Current working directory is the godot-cpp source root.
+        cmake . -B build-dir
+
+        # Current working directory is an empty godot-cpp/build-dir.
+        cmake ../
+
+        # Current working directory is an existing build path.
+        cmake .
+
+    The build directory is specified so that generated files do not clutter
+    the source tree with build artifacts.
+
+    CMake doesn't build the code, it generates the files that a build tool
+    uses, in this case the ``Ninja`` generator creates Ninja_ build files.
+
+    To see the list of generators run ``cmake --help``.
+
+    .. _Ninja: https://ninja-build.org/
+
+.. topic:: Build Options
+
+    To list the available options use the ``-L[AH]`` command flags.
+
+    ``A`` is for advanced, and ``H`` is for help strings:
+
+    .. code-block::
+
+        cmake -S godot-cpp -LH
 
     Options are specified on the command line when configuring, for example:
 
     .. code-block::
 
-        cmake .. -DGODOTCPP_USE_HOT_RELOAD:BOOL=ON \
+        cmake -S godot-cpp -DGODOTCPP_USE_HOT_RELOAD:BOOL=ON \
             -DGODOTCPP_PRECISION:STRING=double \
             -DCMAKE_BUILD_TYPE:STRING=Debug
 
-    Review setting-build-variables_ and build-configurations_ for more information.
+    Review setting-build-variables_ and build-configurations_ for more
+    information.
 
     .. _setting-build-variables: https://cmake.org/cmake/help/latest/guide/user-interaction/index.html#setting-build-variables
     .. _build-configurations: https://cmake.org/cmake/help/latest/manual/cmake-buildsystem.7.html#build-configurations
@@ -140,13 +178,16 @@ Basic walkthrough
 
     .. code-block::
 
-        // Path to a custom GDExtension API JSON file. (takes precedence over `GODOTCPP_GDEXTENSION_DIR`) ( /path/to/custom_api_file )
+        // Path to a custom GDExtension API JSON file.
+        // (takes precedence over `GODOTCPP_GDEXTENSION_DIR`)
+        // ( /path/to/custom_api_file )
         GODOTCPP_CUSTOM_API_FILE:FILEPATH=
 
         // Force disabling exception handling code. (ON|OFF)
         GODOTCPP_DISABLE_EXCEPTIONS:BOOL=ON
 
-        // Path to a custom directory containing the GDExtension interface header and API JSON file. ( /path/to/gdextension_dir )
+        // Path to a custom directory containing the GDExtension interface
+        // header and API JSON file. ( /path/to/gdextension_dir )
         GODOTCPP_GDEXTENSION_DIR:PATH=gdextension
 
         // Set the floating-point precision level. (single|double)
@@ -155,35 +196,39 @@ Basic walkthrough
         // Enable the extra accounting required to support hot reload. (ON|OFF)
         GODOTCPP_USE_HOT_RELOAD:BOOL=
 
-.. topic:: Configure the build
 
-    .. code-block::
+.. topic:: Compiling
 
-        cmake -S . -B cmake-build -G Ninja
+    Tell CMake to invoke the build system it generated in the specified
+    directory. The default target is ``template_debug`` and the default build
+    configuration is Debug.
 
-    ``-S .`` Specifies the source directory
+    .. code-block::
 
-    ``-B cmake-build`` Specifies the build directory
+        cmake --build cmake-build
 
-    ``-G Ninja`` Specifies the Generator
+Examples
+--------
 
-    The source directory in this example is the source code for godot-cpp.
-    The build directory is so that generated files do not clutter up the source tree.
-    CMake doesn't build the code, it generates the files that another tool uses
-    to build the code, in this case Ninja.
-    To see the list of generators run ``cmake --help``.
+These examples, while intended for godot-cpp developers, package maintainers,
+and CI/CD may help you configure your own extension project.
 
-.. topic:: Compiling
+Practical examples for how to consume the godot-cpp library as part of an
+extension project are listed in the `Introduction`_
 
-    Tell CMake to invoke the build system it generated in the specified directory.
-    The default target is ``template_debug`` and the default build configuration is Debug.
+Enabling Integration Testing
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-    .. code-block::
+The testing target ``godot-cpp-test`` is guarded by ``GODOTCPP_ENABLE_TESTING``
+which is off by default.
 
-        cmake --build cmake-build
+To configure and build the godot-cpp project to enable the integration
+testing targets the command will look something like:
 
-Examples
---------
+.. code-block::
+
+    cmake -S godot-cpp -B cmake-build -DGODOTCPP_ENABLE_TESTING=YES
+    cmake --build cmake-build --target godot-cpp-test
 
 Windows and MSVC - Release
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -199,8 +244,7 @@ needs to be specified at build time, for example, ``--config Release``.
 
 .. code-block::
 
-    # Assuming our current directory is the godot-cpp source root.
-    cmake -S . -B cmake-build -DGODOTCPP_ENABLE_TESTING=YES
+    cmake -S godot-cpp -B cmake-build -DGODOTCPP_ENABLE_TESTING=YES
     cmake --build cmake-build -t godot-cpp-test --config Release
 
 
@@ -216,8 +260,8 @@ Using the ``msys2/clang64`` shell:
 
 .. code-block::
 
-    # Assuming our current directory is the godot-cpp source root.
-    cmake -S . -B cmake-build -G"Ninja" -DGODOTCPP_ENABLE_TESTING=YES -DCMAKE_BUILD_TYPE=Release
+    cmake -S godot-cpp -B cmake-build -G"Ninja" \
+        -DGODOTCPP_ENABLE_TESTING=YES -DCMAKE_BUILD_TYPE=Release
     cmake --build cmake-build -t godot-cpp-test
 
 MSys2/clang64, "Ninja Multi-Config" - dev_build, Debug Symbols
@@ -232,8 +276,8 @@ Using the ``msys2/clang64`` shell:
 
 .. code-block::
 
-    # Assuming our current directory is the godot-cpp source root.
-    cmake -S . -B cmake-build -G"Ninja Multi-Config" -DGODOTCPP_ENABLE_TESTING=YES -DGODOTCPP_DEV_BUILD:BOOL=ON
+    cmake -S godot-cpp -B cmake-build -G"Ninja Multi-Config" \
+        -DGODOTCPP_ENABLE_TESTING=YES -DGODOTCPP_DEV_BUILD:BOOL=ON
     cmake --build cmake-build -t godot-cpp-test --config Debug
 
 Emscripten for web platform
@@ -242,15 +286,16 @@ Emscripten for web platform
 This has only been tested on Windows so far. You can use this example workflow:
 
 - Clone and install the latest Emscripten tools to ``c:\emsdk``.
-- Use ``C:\emsdk\emsdk.ps1 activate latest`` to enable the environment from powershell in the current shell.
-- The ``emcmake.bat`` utility adds the emscripten toolchain to the CMake command. It can also be added manually;
+- Use ``C:\emsdk\emsdk.ps1 activate latest`` to enable the environment from
+  powershell in the current shell.
+- The ``emcmake.bat`` utility adds the emscripten toolchain to the CMake
+  command. It can also be added manually;
   the location is listed inside the ``emcmake.bat`` file
 
 .. code-block::
 
-    # Assuming our current directory is the godot-cpp source root.
     C:\emsdk\emsdk.ps1 activate latest
-    emcmake.bat cmake -S . -B cmake-build-web -DCMAKE_BUILD_TYPE=Release
+    emcmake.bat cmake -S godot-cpp -B cmake-build-web -DCMAKE_BUILD_TYPE=Release
     cmake --build cmake-build-web
 
 Android Cross Compile from Windows
@@ -278,16 +323,14 @@ is for the Android sdk platform, (tested with ``android-29``).
 
     .. code-block::
 
-        # Assuming our current directory is the godot-cpp source root.
-        cmake -S . -B cmake-build --toolchain my_toolchain.cmake
+        cmake -S godot-cpp -B cmake-build --toolchain my_toolchain.cmake
         cmake --build cmake-build -t template_release
 
     Doing the equivalent on just using the command line:
 
     .. code-block::
 
-        # Assuming our current directory is the godot-cpp source root.
-        cmake -S . -B cmake-build \
+        cmake -S godot-cpp -B cmake-build \
             -DCMAKE_SYSTEM_NAME=Android \
             -DCMAKE_SYSTEM_VERSION=<platform> \
             -DCMAKE_ANDROID_ARCH_ABI=<arch> \
@@ -300,67 +343,16 @@ is for the Android sdk platform, (tested with ``android-29``).
 
     .. code-block::
 
-        # Assuming our current directory is the godot-cpp source root.
-        cmake -S . -B cmake-build --toolchain $ANDROID_HOME/ndk/<version>/build/cmake/android.toolchain.cmake
+        cmake -S godot-cpp -B cmake-build \
+            --toolchain $ANDROID_HOME/ndk/<version>/build/cmake/android.toolchain.cmake
         cmake --build cmake-build
 
     Specifying the Android platform and ABI:
 
     .. code-block::
 
-        # Assuming our current directory is the godot-cpp source root.
-        cmake -S . -B cmake-build --toolchain $ANDROID_HOME/ndk/<version>/build/cmake/android.toolchain.cmake \
+        cmake -S godot-cpp -B cmake-build \
+            --toolchain $ANDROID_HOME/ndk/<version>/build/cmake/android.toolchain.cmake \
             -DANDROID_PLATFORM:STRING=android-29 \
             -DANDROID_ABI:STRING=armeabi-v7a
         cmake --build cmake-build
-
-
-Toolchains
-----------
-
-This section attempts to list the host and target combinations that have been
-tested.
-
-Linux Host
-~~~~~~~~~~
-
-macOS Host
-~~~~~~~~~~
-
-:System: Mac Mini
-:OS Name: Sequoia 15.0.1
-:Processor: Apple M2
-
-* AppleClang
-
-Windows Host
-~~~~~~~~~~~~
-
-:OS Name: Windows 11
-:Processor: AMD Ryzen 7 6800HS Creator Edition
-
-
-* `Microsoft Visual Studio 17 2022 <https://visualstudio.microsoft.com/vs/>`_
-* `LLVM <https://llvm.org/>`_
-* `LLVM-MinGW <https://github.com/mstorsjo/llvm-mingw/releases>`_
-
-    * aarch64-w64-mingw32
-    * armv7-w64-mingw32
-    * i686-w64-mingw32
-    * x86_64-w64-mingw32
-
-* `AndroidSDK <https://developer.android.com/studio/#command-tools>`_
-* `Emscripten <https://emscripten.org/>`_
-* `MinGW-W64-builds <https://github.com/niXman/mingw-builds-binaries/releases>`_
-* `Jetbrains-CLion <https://www.jetbrains.com/clion/>`_
-
-    Jetbrains built-in compiler is just the MingW64 above.
-
-* `MSYS2 <https://www.msys2.org/>`_
-    Necessary reading about MSYS2 `environments <https://www.msys2.org/docs/environments/>`_
-
-    * ucrt64
-    * clang64
-    * mingw32
-    * mingw64
-    * clangarm64