From d424f4dde3cd67ed7c1b59f005fcf5d99f059263 Mon Sep 17 00:00:00 2001 From: Samuel Nicholas Date: Thu, 16 Oct 2025 00:42:31 +1030 Subject: [PATCH 1/2] cmake-updates Documentation Guideline Conformance - added sphinx reference name, matching the scons name - fix admonition formatting - use proper headings rather than topic:: - reflow due to change of indent. - add code block language to fix highlighting - fix bad formatting for bullet points - a couple of full stops, colons, and capitilsation - added a link to the android documentation in the admonition Co-authored-by: A Thousand Ships <96648715+AThousandShips@users.noreply.github.com> --- .../scripting/cpp/build_system/cmake.rst | 290 +++++++++--------- 1 file changed, 149 insertions(+), 141 deletions(-) diff --git a/tutorials/scripting/cpp/build_system/cmake.rst b/tutorials/scripting/cpp/build_system/cmake.rst index 1b2bd813be6..5e4f653ee14 100644 --- a/tutorials/scripting/cpp/build_system/cmake.rst +++ b/tutorials/scripting/cpp/build_system/cmake.rst @@ -1,9 +1,12 @@ +.. _doc_godot_cpp_build_system_cmake: + Secondary build system: Working with CMake ========================================== -.. seealso:: This page documents how to compile godot-cpp. If you're looking to - compile Godot instead, see - :ref:`doc_introduction_to_the_buildsystem`. +.. 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 SCons_ based build system, godot-cpp also provides a CMakeLists.txt_ file to support users that prefer using CMake_ over SCons for their build @@ -33,7 +36,6 @@ extension project: Examples for configuring godot-cpp are listed at the bottom of the page, many of which may help with configuring your project. - CMake's ``Debug`` vs Godot's ``template_debug`` ----------------------------------------------- @@ -42,170 +44,171 @@ 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: - - .. code-block:: +Debug Features +~~~~~~~~~~~~~~ - cmake -S godot-cpp -B cmake-build -DGODOTCPP_TARGET= +Enables a pre-processor definition to selectively compile code to help users of +a Godot extension with their own project. -- Debug - Sets compiler flags so that debug symbols are generated to help godot - extension developers debug their extension. +Debug features are enabled in ``editor`` and ``template_debug`` builds, which +can be specified during the configure phase like so: - ``Debug`` is the default build type for CMake projects, to select another - it depends on the generator used +.. code-block:: shell - For single configuration generators, add to the configure command: + cmake -S godot-cpp -B cmake-build -DGODOTCPP_TARGET= - ``-DCMAKE_BUILD_TYPE=`` +Debug +~~~~~ - For multi-config generators add to the build command: +Sets compiler flags so that debug symbols are generated to help godot extension +developers debug their extension. - ``--config `` +``Debug`` is the default build type for CMake projects, to select another it +depends on the generator used: - where ```` is one of ``Debug``, ``Release``, ``RelWithDebInfo``, - ``MinSizeRel`` +* For single configuration generators, add ``-DCMAKE_BUILD_TYPE=`` to the + configure command. +* For multi-config generators add ``--config `` to the build command. +Where ```` is one of ``Debug``, ``Release``, ``RelWithDebInfo``, and +``MinSizeRel``. SCons Deviations ---------------- Not all code from the SCons system can be perfectly represented in CMake, here -are the notable differences. +are the notable differences: + +- ``debug_symbols`` -- debug_symbols Is no longer an explicit option, and is enabled when using CMake build configurations; ``Debug``, ``RelWithDebInfo``. -- dev_build +- ``dev_build`` + 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`` - 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. - - -Basic walkthrough ------------------ +- ``arch`` -.. topic:: Clone the git repository - - .. code-block:: + 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. - git clone https://github.com/godotengine/godot-cpp.git - Cloning into 'godot-cpp'... - ... +- ``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. -.. topic:: Configure the build +Basic Walk-Through +------------------ - .. code-block:: +Clone the git repository +~~~~~~~~~~~~~~~~~~~~~~~~ - cmake -S godot-cpp -B cmake-build -G Ninja +.. code-block:: shell - ``-S`` Specifies the source directory as ``godot-cpp`` + git clone https://github.com/godotengine/godot-cpp.git + Cloning into 'godot-cpp'... + ... - ``-B`` Specifies the build directory as ``cmake-build`` +Configure the build +~~~~~~~~~~~~~~~~~~~ - ``-G`` Specifies the Generator as ``Ninja`` +.. code-block:: shell - 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. + cmake -S godot-cpp -B cmake-build -G Ninja - The following three commands are equivalent. +- ``-S`` Specifies the source directory as ``godot-cpp`` +- ``-B`` Specifies the build directory as ``cmake-build`` +- ``-G`` Specifies the Generator as ``Ninja`` - .. code-block:: +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. - # Current working directory is the godot-cpp source root. - cmake . -B build-dir +The following three commands are equivalent: - # Current working directory is an empty godot-cpp/build-dir. - cmake ../ +.. code-block:: shell - # Current working directory is an existing build path. - cmake . + # Current working directory is the godot-cpp source root. + cmake . -B build-dir - The build directory is specified so that generated files do not clutter - the source tree with build artifacts. + # Current working directory is an empty godot-cpp/build-dir. + cmake ../ - 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. + # Current working directory is an existing build path. + cmake . - To see the list of generators run ``cmake --help``. +The build directory is specified so that generated files do not clutter the +source tree with build artifacts. - .. _Ninja: https://ninja-build.org/ +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. -.. topic:: Build Options +To see the list of generators run ``cmake --help``. - To list the available options use the ``-L[AH]`` command flags. +.. _Ninja: https://ninja-build.org/ - ``A`` is for advanced, and ``H`` is for help strings: +Build Options +~~~~~~~~~~~~~ - .. code-block:: +To list the available options use the ``-L[AH]`` command flags. ``A`` is for +advanced, and ``H`` is for help strings: - cmake -S godot-cpp -LH +.. code-block:: shell - Options are specified on the command line when configuring, for example: + cmake -S godot-cpp -LH - .. code-block:: +Options are specified on the command line when configuring, for example: - cmake -S godot-cpp -DGODOTCPP_USE_HOT_RELOAD:BOOL=ON \ - -DGODOTCPP_PRECISION:STRING=double \ - -DCMAKE_BUILD_TYPE:STRING=Debug +.. code-block:: shell - Review setting-build-variables_ and build-configurations_ for more - information. + cmake -S godot-cpp -DGODOTCPP_USE_HOT_RELOAD:BOOL=ON \ + -DGODOTCPP_PRECISION:STRING=double \ + -DCMAKE_BUILD_TYPE:STRING=Debug - .. _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 +See setting-build-variables_ and build-configurations_ for more information. - A non-exhaustive list of options: +.. _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 - .. code-block:: +A non-exhaustive list of options: +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - // Path to a custom GDExtension API JSON file. - // (takes precedence over `GODOTCPP_GDEXTENSION_DIR`) - // ( /path/to/custom_api_file ) - GODOTCPP_CUSTOM_API_FILE:FILEPATH= +.. code-block:: text - // Force disabling exception handling code. (ON|OFF) - GODOTCPP_DISABLE_EXCEPTIONS:BOOL=ON + // Path to a custom GDExtension API JSON file. + // (takes precedence over GODOTCPP_GDEXTENSION_DIR) + // ( /path/to/custom_api_file ) + GODOTCPP_CUSTOM_API_FILE:FILEPATH= - // Path to a custom directory containing the GDExtension interface - // header and API JSON file. ( /path/to/gdextension_dir ) - GODOTCPP_GDEXTENSION_DIR:PATH=gdextension + // Force disabling exception handling code. (ON|OFF) + GODOTCPP_DISABLE_EXCEPTIONS:BOOL=ON - // Set the floating-point precision level. (single|double) - GODOTCPP_PRECISION:STRING=single + // Path to a custom directory containing the GDExtension interface + // header and API JSON file. ( /path/to/gdextension_dir ) + GODOTCPP_GDEXTENSION_DIR:PATH=gdextension - // Enable the extra accounting required to support hot reload. (ON|OFF) - GODOTCPP_USE_HOT_RELOAD:BOOL= + // Set the floating-point precision level. (single|double) + GODOTCPP_PRECISION:STRING=single + // Enable the extra accounting required to support hot reload. (ON|OFF) + GODOTCPP_USE_HOT_RELOAD:BOOL= -.. topic:: Compiling +Compiling +~~~~~~~~~ - 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. +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. - .. code-block:: +.. code-block:: shell - cmake --build cmake-build + cmake --build cmake-build Examples -------- @@ -214,7 +217,7 @@ These examples, while intended for godot-cpp developers, package maintainers, and CI/CD may help you configure your own extension project. Practical examples for how to consume the godot-cpp library as part of an -extension project are listed in the `Introduction`_ +extension project are listed in the `Introduction`_. Enabling Integration Testing ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -225,7 +228,7 @@ which is off by default. To configure and build the godot-cpp project to enable the integration testing targets the command will look something like: -.. code-block:: +.. code-block:: shell cmake -S godot-cpp -B cmake-build -DGODOTCPP_ENABLE_TESTING=YES cmake --build cmake-build --target godot-cpp-test @@ -242,23 +245,22 @@ needs to be specified at build time, for example, ``--config Release``. .. _CMake downloads: https://cmake.org/download/ -.. code-block:: +.. code-block:: shell cmake -S godot-cpp -B cmake-build -DGODOTCPP_ENABLE_TESTING=YES cmake --build cmake-build -t godot-cpp-test --config Release - MSys2/clang64, "Ninja" - Debug ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Assumes the ``ming-w64-clang-x86_64``-toolchain is installed. -Note that Ninja is a Single-Config Generator so the build type -needs to be specified at configuration time. +Note that Ninja is a Single-Config Generator so the build type needs to be +specified at configuration time. Using the ``msys2/clang64`` shell: -.. code-block:: +.. code-block:: shell cmake -S godot-cpp -B cmake-build -G"Ninja" \ -DGODOTCPP_ENABLE_TESTING=YES -DCMAKE_BUILD_TYPE=Release @@ -274,7 +276,7 @@ type is specified at build time. Using the ``msys2/clang64`` shell: -.. code-block:: +.. code-block:: shell cmake -S godot-cpp -B cmake-build -G"Ninja Multi-Config" \ -DGODOTCPP_ENABLE_TESTING=YES -DGODOTCPP_DEV_BUILD:BOOL=ON @@ -292,7 +294,7 @@ This has only been tested on Windows so far. You can use this example workflow: command. It can also be added manually; the location is listed inside the ``emcmake.bat`` file -.. code-block:: +.. code-block:: powershell C:\emsdk\emsdk.ps1 activate latest emcmake.bat cmake -S godot-cpp -B cmake-build-web -DCMAKE_BUILD_TYPE=Release @@ -315,44 +317,50 @@ is for the Android sdk platform, (tested with ``android-29``). .. warning:: - The Android SDK website explicitly states that they do not support using + The Android SDK website_ explicitly states that they do not support using the CMake built-in method, and recommends you stick with their toolchain files. -.. topic:: Using your own toolchain file as described in the CMake documentation + .. _website: https://developer.android.com/ndk/guides/cmake + +Using your own toolchain file +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +As described in the CMake documentation: - .. code-block:: +.. code-block:: shell - cmake -S godot-cpp -B cmake-build --toolchain my_toolchain.cmake - cmake --build cmake-build -t template_release + 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: +Doing the equivalent just using the command line: - .. code-block:: +.. code-block:: shell - cmake -S godot-cpp -B cmake-build \ - -DCMAKE_SYSTEM_NAME=Android \ - -DCMAKE_SYSTEM_VERSION= \ - -DCMAKE_ANDROID_ARCH_ABI= \ - -DCMAKE_ANDROID_NDK=/path/to/android-ndk - cmake --build cmake-build + cmake -S godot-cpp -B cmake-build \ + -DCMAKE_SYSTEM_NAME=Android \ + -DCMAKE_SYSTEM_VERSION= \ + -DCMAKE_ANDROID_ARCH_ABI= \ + -DCMAKE_ANDROID_NDK=/path/to/android-ndk + cmake --build cmake-build -.. topic:: Using the toolchain file from the Android SDK +Using the Android SDK toolchain file +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - This defaults to the minimum supported version and armv7-a: +This defaults to the minimum supported version and armv7-a: - .. code-block:: +.. code-block:: shell - cmake -S godot-cpp -B cmake-build \ - --toolchain $ANDROID_HOME/ndk//build/cmake/android.toolchain.cmake - cmake --build cmake-build + cmake -S godot-cpp -B cmake-build \ + --toolchain $ANDROID_HOME/ndk//build/cmake/android.toolchain.cmake + cmake --build cmake-build - Specifying the Android platform and ABI: +Specifying the Android platform and ABI: - .. code-block:: +.. code-block:: shell - cmake -S godot-cpp -B cmake-build \ - --toolchain $ANDROID_HOME/ndk//build/cmake/android.toolchain.cmake \ - -DANDROID_PLATFORM:STRING=android-29 \ - -DANDROID_ABI:STRING=armeabi-v7a - cmake --build cmake-build + cmake -S godot-cpp -B cmake-build \ + --toolchain $ANDROID_HOME/ndk//build/cmake/android.toolchain.cmake \ + -DANDROID_PLATFORM:STRING=android-29 \ + -DANDROID_ABI:STRING=armeabi-v7a + cmake --build cmake-build From 9e9c96aadae7e003274f3ba474fc8f1898a23532 Mon Sep 17 00:00:00 2001 From: Samuel Nicholas Date: Thu, 23 Oct 2025 19:35:42 +1030 Subject: [PATCH 2/2] Apply suggestions from code review Co-authored-by: A Thousand Ships <96648715+AThousandShips@users.noreply.github.com> --- tutorials/scripting/cpp/build_system/cmake.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tutorials/scripting/cpp/build_system/cmake.rst b/tutorials/scripting/cpp/build_system/cmake.rst index 5e4f653ee14..3a49946d4cb 100644 --- a/tutorials/scripting/cpp/build_system/cmake.rst +++ b/tutorials/scripting/cpp/build_system/cmake.rst @@ -63,12 +63,12 @@ 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 +``Debug`` is the default build type for CMake projects, the way to select another depends on the generator used: * For single configuration generators, add ``-DCMAKE_BUILD_TYPE=`` to the configure command. -* For multi-config generators add ``--config `` to the build command. +* For multi-config generators, add ``--config `` to the build command. Where ```` is one of ``Debug``, ``Release``, ``RelWithDebInfo``, and ``MinSizeRel``.