From 5f38b5b95742f5be2aaa896a39ff4faa05d37df3 Mon Sep 17 00:00:00 2001 From: Samuel Nicholas Date: Mon, 13 Oct 2025 14:14:57 +1030 Subject: [PATCH 1/2] cmake-updates - 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 --- .../scripting/cpp/build_system/cmake.rst | 290 +++++++++--------- 1 file changed, 141 insertions(+), 149 deletions(-) diff --git a/tutorials/scripting/cpp/build_system/cmake.rst b/tutorials/scripting/cpp/build_system/cmake.rst index 3ddbf4c7827..10abe956d04 100644 --- a/tutorials/scripting/cpp/build_system/cmake.rst +++ b/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 `__ based build system, godot-cpp also comes with a -`CMakeLists.txt `__ file, to support users that -prefer using `CMake `__ 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 `__ +* `godot_roguelite `__ +* `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 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=`` + .. code-block:: + + cmake -S godot-cpp -B cmake-build -DGODOTCPP_TARGET= - 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=`` + ``-DCMAKE_BUILD_TYPE=`` For multi-config generators add to the build command: - ``--config `` + ``--config `` - where ```` is one of ``Debug``, ``Release``, ``RelWithDebInfo``, ``MinSizeRel`` + where ```` 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 has 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 up + 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= \ -DCMAKE_ANDROID_ARCH_ABI= \ @@ -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//build/cmake/android.toolchain.cmake + 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: .. code-block:: - # Assuming our current directory is the godot-cpp source root. - cmake -S . -B cmake-build --toolchain $ANDROID_HOME/ndk//build/cmake/android.toolchain.cmake \ + 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 - - -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 `_ -* `LLVM `_ -* `LLVM-MinGW `_ - - * aarch64-w64-mingw32 - * armv7-w64-mingw32 - * i686-w64-mingw32 - * x86_64-w64-mingw32 - -* `AndroidSDK `_ -* `Emscripten `_ -* `MinGW-W64-builds `_ -* `Jetbrains-CLion `_ - - Jetbrains built-in compiler is just the MingW64 above. - -* `MSYS2 `_ - Necessary reading about MSYS2 `environments `_ - - * ucrt64 - * clang64 - * mingw32 - * mingw64 - * clangarm64 From b2d83fba72e1dd003969bb024342dbd54985033b Mon Sep 17 00:00:00 2001 From: Samuel Nicholas Date: Mon, 13 Oct 2025 21:06:01 +1030 Subject: [PATCH 2/2] Apply suggestions from code review Thanks. for the fixes. Co-authored-by: A Thousand Ships <96648715+AThousandShips@users.noreply.github.com> Co-authored-by: Lukas Tenbrink --- tutorials/scripting/cpp/build_system/cmake.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/tutorials/scripting/cpp/build_system/cmake.rst b/tutorials/scripting/cpp/build_system/cmake.rst index 10abe956d04..1b2bd813be6 100644 --- a/tutorials/scripting/cpp/build_system/cmake.rst +++ b/tutorials/scripting/cpp/build_system/cmake.rst @@ -37,7 +37,7 @@ of which may help with configuring your project. CMake's ``Debug`` vs Godot's ``template_debug`` ----------------------------------------------- -Something that has come come up during many discussions is the conflation of a +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. @@ -79,7 +79,7 @@ Not all code from the SCons system can be perfectly represented in CMake, here are the notable differences. - debug_symbols - Is no longer has an explicit option, and is enabled when using CMake build + Is no longer an explicit option, and is enabled when using CMake build configurations; ``Debug``, ``RelWithDebInfo``. - dev_build @@ -131,16 +131,16 @@ Basic walkthrough .. code-block:: - # current working directory is the godot-cpp source root + # Current working directory is the godot-cpp source root. cmake . -B build-dir - # current working directory is an empty godot-cpp/build-dir + # Current working directory is an empty godot-cpp/build-dir. cmake ../ - # current working directory is an existing build path + # Current working directory is an existing build path. cmake . - The build directory is specified so that generated files do not clutter up + 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