diff --git a/tutorials/scripting/cpp/build_system/cmake.rst b/tutorials/scripting/cpp/build_system/cmake.rst new file mode 100644 index 00000000000..3ddbf4c7827 --- /dev/null +++ b/tutorials/scripting/cpp/build_system/cmake.rst @@ -0,0 +1,366 @@ +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`. + +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. + +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. + +.. 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 + +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. + +Configuration examples are listed at the bottom of the page. + +.. _godot-cpp-template: https://github.com/godotengine/godot-cpp-template + +Debug vs 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. + +- 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: + + ``cmake -S . -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 + + For single configuration generators, add to the configure command: + + ``-DCMAKE_BUILD_TYPE=`` + + For multi-config generators add to the build command: + + ``--config `` + + 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. + +- debug_symbols + No longer has an explicit option, and is enabled via Debug-like CMake + build configurations; ``Debug``, ``RelWithDebInfo``. + +- dev_build + Does not define ``NDEBUG`` when disabled, ``NDEBUG`` is set via Release-like + 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. + +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 +----------------- + +.. topic:: Clone the git repository + + .. code-block:: + + 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: + + .. code-block:: + + cmake .. -LH + + Options are specified on the command line when configuring, for example: + + .. code-block:: + + cmake .. -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. + + .. _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 + + A non-exhaustive list of options: + + .. code-block:: + + // 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 ) + GODOTCPP_GDEXTENSION_DIR:PATH=gdextension + + // 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:: 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. + + .. code-block:: + + cmake --build cmake-build + +Examples +-------- + +Windows and MSVC - Release +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +So long as CMake is installed from the `CMake Downloads`_ page and in the PATH, +and Microsoft Visual Studio is installed with C++ support, CMake will detect +the MSVC compiler. + +Note that Visual Studio is a Multi-Config Generator so the build configuration +needs to be specified at build time, for example, ``--config Release``. + +.. _CMake downloads: https://cmake.org/download/ + +.. 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 -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. + +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 --build cmake-build -t godot-cpp-test + +MSys2/clang64, "Ninja Multi-Config" - dev_build, Debug Symbols +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Assumes the ``ming-w64-clang-x86_64``-toolchain is installed. + +This time we are choosing the 'Ninja Multi-Config' generator, so the build +type is specified at build time. + +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 --build cmake-build -t godot-cpp-test --config Debug + +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; + 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 + cmake --build cmake-build-web + +Android Cross Compile from Windows +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +There are two separate paths you can choose when configuring for android. + +Use the ``CMAKE_ANDROID_*`` variables specified on the command line or in your +own toolchain file as listed in the cmake-toolchains_ documentation. + +.. _cmake-toolchains: https://cmake.org/cmake/help/latest/manual/cmake-toolchains.7.html#cross-compiling-for-android-with-the-ndk + +Or use the toolchain and scripts provided by the Android SDK and make changes +using the ``ANDROID_*`` variables listed there. Where ```` is whatever +NDK version you have installed (tested with `28.1.13356709`) and ```` +is for the Android sdk platform, (tested with ``android-29``). + +.. warning:: + + 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 + + .. code-block:: + + # Assuming our current directory is the godot-cpp source root. + cmake -S . -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 \ + -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 + + This defaults to the minimum supported version and armv7-a: + + .. 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 --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 \ + -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 diff --git a/tutorials/scripting/cpp/build_system/index.rst b/tutorials/scripting/cpp/build_system/index.rst new file mode 100644 index 00000000000..7fde0ce9614 --- /dev/null +++ b/tutorials/scripting/cpp/build_system/index.rst @@ -0,0 +1,9 @@ +Build system +============ + +.. toctree:: + :maxdepth: 1 + :name: toc-godot-cpp-build-system + + scons + cmake diff --git a/tutorials/scripting/cpp/build_system/scons.rst b/tutorials/scripting/cpp/build_system/scons.rst new file mode 100644 index 00000000000..b1e3d0d739d --- /dev/null +++ b/tutorials/scripting/cpp/build_system/scons.rst @@ -0,0 +1,75 @@ +.. _doc_godot_cpp_build_system: + +Main build system: Working with SCons +===================================== + +.. seealso:: This page documents how to compile godot-cpp. If you're looking to compile Godot instead, see + :ref:`doc_introduction_to_the_buildsystem`. + +`godot-cpp `__ uses `SCons `__ as its main build system. +It is modeled after :ref:`Godot's build system `, and some commands available there are also +available in godot-cpp projects. + +Getting started +--------------- + +To build a godot-cpp project, it is generally sufficient to install `SCons `__, and simply run it +in the project directory: + + scons + +You may want to learn about available options: + + scons --help + +To cleanly re-build your project, add ``--clean`` to your build command: + + scons --clean + +You can find more information about common SCons arguments and build patterns in the +`SCons User Guide `__. Additional commands may be added by +individual godot-cpp projects, so consult their specific documentation for more information on those. + +Configuring an IDE +------------------ + +Most IDEs can use a ``compile_commands.json`` file to understand a C++ project. You can generate it with godot-cpp using +the following command: + +.. code-block:: shell + + # Generate compile_commands.json while compiling. + scons compiledb=yes + + # Generate compile_commands.json without compiling. + scons compiledb=yes compile_commands.json + +For more information, please check out the :ref:`IDE configuration guides `. +Although written for Godot engine contributors, they are largely applicable to godot-cpp projects as well. + +Loading your GDExtension in Godot +--------------------------------- + +Godot loads GDExtensions by finding :ref:`.gdextension ` files in the project directory. +``.gdextension`` files are used to select and load a binary compatible with the current computer / operating system. + +The `godot-cpp-template `__, as well as the +:ref:`Getting Started section `, provide example ``.gdextension`` files for GDExtensions +that are widely compatible to many different systems. + +Building for multiple platforms +------------------------------- + +GDExtensions are expected to run on many different systems, each with separate binaries and build configurations. +If you are planning to publish your GDExtension, we recommend you provide binaries for all configurations that are +mentioned in the `godot-cpp-template `__ +`.gdextension file `__. + +There are two popular ways by which cross platform builds can be achieved: + +- Cross-platform build tools +- Continuous Integration (CI) + +`godot-cpp-template `__ contains an +`example setup `__ +for a GitHub based CI workflow. diff --git a/tutorials/scripting/cpp/index.rst b/tutorials/scripting/cpp/index.rst index 437267d4620..ed3bfc401c8 100644 --- a/tutorials/scripting/cpp/index.rst +++ b/tutorials/scripting/cpp/index.rst @@ -14,4 +14,5 @@ the official C++ GDExtension bindings maintained as part of the Godot project. about_godot_cpp gdextension_cpp_example + build_system/index gdextension_docs_system