godotengine/godot-docs
1
0
Fork 0
mirror of https://github.com/godotengine/godot-docs.git synced 2025-12-31 17:49:03 +03:00
Code Issues Packages Projects Releases Wiki Activity

Update Working with CMake GDExtension documentation (#11370)

Browse Source 
- 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 <96648715+AThousandShips@users.noreply.github.com>
Co-authored-by: Lukas Tenbrink <lukas.tenbrink@gmail.com>
This commit is contained in:
Samuel Nicholas
2025-10-15 01:21:55 +10:30
committed by GitHub
parent 055023d3b6
commit b61cd5d935
1 changed files with 142 additions and 150 deletions
Download Patch File Download Diff File Expand all files Collapse all files

292
tutorials/scripting/cpp/build_system/cmake.rst
View File

@@ -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.
Configuration examples are listed at the bottom of the page.
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-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/>`__
Debug vs template_debug
-----------------------
Examples for configuring godot-cpp are listed at the bottom of the page, many
of which may help with configuring your project.
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.
CMake's ``Debug`` vs Godot's ``template_debug``
-----------------------------------------------
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.
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.
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 .. -LH
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::
# 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,28 +196,12 @@ Basic walkthrough
// Enable the extra accounting required to support hot reload. (ON|OFF)
GODOTCPP_USE_HOT_RELOAD:BOOL=
.. topic:: Configure the build
.. code-block::
cmake -S . -B cmake-build -G Ninja
``-S .`` Specifies the source directory
``-B cmake-build`` Specifies the build directory
``-G Ninja`` Specifies the Generator
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``.
.. topic:: 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::
@@ -185,6 +210,26 @@ Basic walkthrough
Examples
--------
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`_
Enabling Integration Testing
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The testing target ``godot-cpp-test`` is guarded by ``GODOTCPP_ENABLE_TESTING``
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::
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