From 6e3d5d26bf2647d06d815d6536ed8ec614c98b60 Mon Sep 17 00:00:00 2001 From: Samuel Nicholas Date: Tue, 22 Oct 2024 19:15:14 +1030 Subject: [PATCH] Updating documentation --- cmake/godotcpp.cmake | 2 +- doc/cmake.md | 216 +++++++++++++++++++++++++++++++++++-------- 2 files changed, 181 insertions(+), 37 deletions(-) diff --git a/cmake/godotcpp.cmake b/cmake/godotcpp.cmake index 047da926b2..3e2356b873 100644 --- a/cmake/godotcpp.cmake +++ b/cmake/godotcpp.cmake @@ -7,7 +7,7 @@ function( godotcpp_options ) set(GODOT_GDEXTENSION_DIR "gdextension" CACHE PATH "Path to a custom directory containing GDExtension interface header and API JSON file ( /path/to/gdextension_dir )" ) set(GODOT_CUSTOM_API_FILE "" CACHE FILEPATH - "Path to a custom GDExtension API JSON file (takes precedence over `gdextension_dir`) ( /path/to/custom_api_file )") + "Path to a custom GDExtension API JSON file (takes precedence over `GODOT_GDEXTENSION_DIR`) ( /path/to/custom_api_file )") #TODO generate_bindings diff --git a/doc/cmake.md b/doc/cmake.md index 3dd77f58f6..a41cca638b 100644 --- a/doc/cmake.md +++ b/doc/cmake.md @@ -1,57 +1,201 @@ -## CMake +# CMake -### cmake arguments +> **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 working on alternative cmake solutions that are frequently referenced in the discord chats: [Ivan's cmake-rewrite branch](https://github.com/IvanInventor/godot-cpp/tree/cmake-rewrite) | [Vorlac's godot-roguelite Project](https://github.com/vorlac/godot-roguelite) -`CMAKE_BUILD_TYPE`: Compilation target (Debug or Release defaults to Debug) +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](https://github.com/godotengine/godot-cpp-template) for how to consume the godot-cpp library as part of your godot extension -### godot-cpp cmake arguments -- `GODOT_GDEXTENSION_DIR`: Path to the directory containing GDExtension interface header and API JSON file -- `GODOT_SYSTEM_HEADERS`: Mark the header files as SYSTEM. This may be useful to suppress warnings in projects including this one. -- `GODOT_WARNING_AS_ERROR`: Treat any warnings as errors -- `GODOT_USE_HOT_RELOAD`: Build with hot reload support. Defaults to YES for Debug-builds and NO for Release-builds. -- `GODOT_CUSTOM_API_FILE`: Path to a custom GDExtension API JSON file (takes precedence over `gdextension_dir`) -- `GODOT_PRECISION`: Floating-point precision level ("single", "double") +[Configuration examples](#Examples) are listed at the bottom of the page. -### Android cmake arguments -- `CMAKE_TOOLCHAIN_FILE`: The path to the android cmake toolchain ($ANDROID_NDK/build/cmake/android.toolchain.cmake) -- `ANDROID_NDK`: The path to the android ndk root folder -- `ANDROID_TOOLCHAIN_NAME`: The android toolchain (arm-linux-androideabi-4.9 or aarch64-linux-android-4.9 or x86-4.9 or x86_64-4.9) -- `ANDROID_PLATFORM`: The android platform version (android-23) +## Tested Toolchains +I'm still trying to make sense of cross compiling infrastructure, so I apologise for confusion, I am doing my best. Targets are structured like: ` - ---` +### Linux +### MacOS +### Windows +* [Microsoft Visual Studio 2022](https://visualstudio.microsoft.com/vs/) + * x86_64-w64-ucrt +* [MinGW-w64](https://www.mingw-w64.org/) + * [MSYS2](https://www.msys2.org/) + * ucrt64 + * gcc - x86_64-msys2-w64-ucrt + * clang64 + * llvm - x86_64-msys2-w64-ucrt + * [LLVM-MinGW](https://github.com/mstorsjo/llvm-mingw/releases) + * [MinGW-W64-builds](https://github.com/niXman/mingw-builds-binaries/releases) + * [Jetbrains-CLion](https://www.jetbrains.com/clion/) + * gcc - x86_64-clion-w64-msvcrt +* [LLVM](https://llvm.org/) + * llvm - x86_64-llvm-w64-ucrt +* [AndroidSDK](https://developer.android.com/studio/#command-tools) + * armv7-none-linux-androideabi16 -- More info [here](https://godot.readthedocs.io/en/latest/development/compiling/compiling_for_android.html) +## Clone the git repository + +```shell +> git clone https://github.com/godotengine/godot-cpp.git +Cloning into 'godot-cpp'... +... +> cd godot-cpp +``` + +## Out-of-tree build directory +Create a build directory for cmake to put caches and build artifacts in and change directory to it. This is typically as a sub-directory of the project root but can be outside the source tree. This is so that generated files do not clutter up the source tree. +```shell +> mkdir cmake-build-Debug +> cd cmake-build-Debug +``` + +## Configure the build +Cmake isn't a build tool, it's a build tool generator, which means it generates the build scripts/files that will end up compiling your code. +To see the list of generators simply run `cmake --help` + +Current working directory is the build directory from the previous step. + +Configure and generate Ninja build files. When using single configuration generators like Ninja, Make, the build type needs to be specified at configure time using `CMAKE_BUILD_TYPE` + +```shell +> cmake ../ -DCMAKE_BUILD_TYPE=Debug -G "Ninja" +``` + +To list the available options cmake use the `-L[AH]` option. `A` is for advanced, and `H` is for help strings. +```shell +> cmake ../ -LH +``` + +Review the cmake documentation for [setting-build-variables](https://cmake.org/cmake/help/latest/guide/user-interaction/index.html#setting-build-variables) + +Specify options on the command line + +```shell +> cmake ../ -DGODOT_USE_HOT_RELOAD:BOOL=ON -DGODOT_PRECISION:STRING=double +``` + +### A non-exhaustive list of options +``` +// Path to a custom GDExtension API JSON file (takes precedence over `GODOT_GDEXTENSION_DIR`) ( /path/to/custom_api_file ) +`GODOT_CUSTOM_API_FILE:FILEPATH=` + +// Force disabling exception handling code (ON|OFF) +GODOT_DISABLE_EXCEPTIONS:BOOL=ON + +// Path to a custom directory containing GDExtension interface header and API JSON file ( /path/to/gdextension_dir ) +GODOT_GDEXTENSION_DIR:PATH=gdextension + +// Generate a template version of the Node class's get_node. (ON|OFF) +GODOT_GENERATE_TEMPLATE_GET_NODE:BOOL=ON + +// Set the floating-point precision level (single|double) +GODOT_PRECISION:STRING=single + +// Symbols visibility on GNU platforms. Use 'auto' to apply the default value. (auto|visible|hidden) +GODOT_SYMBOL_VISIBILITY:STRING=hidden + +// Expose headers as SYSTEM. +GODOT_SYSTEM_HEADERS:BOOL=ON + +// Enable the extra accounting required to support hot reload. (ON|OFF) +GODOT_USE_HOT_RELOAD:BOOL= + +// Treat warnings as errors +GODOT_WARNING_AS_ERROR:BOOL=OFF +``` + +## Building + +Building the default `all` target +```shell +> cmake --build . +``` + +Listing build a targets +```shell +> cmake --build . -t help +``` + +Building a specific target +```shell +> cmake --build . -t godot-cpp +``` + +When using multi-config generators like `Ninja Multi-Config`, `Visual Studio *` or `Xcode` the build type (Debug;Release;etc) needs to be specified at build time. + +```shell +> cmake --build . -t godot-cpp --config Release +``` ## Examples + +#### Building `Release` config of godot-cpp-test using Microsoft Visual Studio +So long as cmake is installed from the cmake [downloads page](https://cmake.org/download/) and in the PATH, and Microsoft Visual Studio is installed with c++ support, cmake will detect the msvc compiler. + ```shell -Builds a debug version: -cmake . -cmake --build . +> mkdir build-msvc +> cd build-msvc +> cmake ../ +> cmake --build . -t godot-cpp-test --config Release ``` -Builds a release version with clang +#### Building a `Debug` config of godot-cpp-test using msys2/clang64 and "Ninja Multi-Config" generator +Assumes the ming-w64-clang-x86_64-toolchain is installed + +Using the msys2/clang64 shell ```shell -CC=/usr/bin/clang CXX=/usr/bin/clang++ cmake -DCMAKE_BUILD_TYPE=Release -G "Unix Makefiles" . -cmake --build . +> mkdir build-clang +> cd build-clang +> cmake ../ -G"Ninja Multi-Config" +> cmake --build . -t godot-cpp-test --config Debug ``` -Builds an android armeabi-v7a debug version: -``` shell -cmake -DCMAKE_TOOLCHAIN_FILE=$ANDROID_NDK/build/cmake/android.toolchain.cmake -DANDROID_NDK=$ANDROID_NDK \ - -DANDROID_TOOLCHAIN_NAME=arm-linux-androideabi-4.9 -DANDROID_PLATFORM=android-23 -DCMAKE_BUILD_TYPE=Debug . -cmake --build . +### Android Cross Compile from Windows +From what I can tell, there are two directions you can go + +Use the `CMAKE_ANDROID_*` variables specified on the commandline or in your own toolchain file as listed in the [cmake-toolchains](https://cmake.org/cmake/help/latest/manual/cmake-toolchains.7.html#cross-compiling-for-android-with-the-ndk) documentation. + +Or use the `$ANDROID_HOME/ndk//build/cmake/android.toolchain.cmake` toolchain and make changes using the `ANDROID_*` variables listed there. Where `` is whatever ndk version you have installed ( tested with `23.2.8568313`) and `` is for android sdk platform, (tested with `android-29`) + + +Using your own toolchain file as described in the cmake documentation + +```shell +> mkdir build-android +> cd build-android +> cmake ../ --toolchain my_toolchain.cmake +> cmake --build . ``` -## Protip -Generate the buildfiles in a sub directory to not clutter the root directory with build files: +Doing the equivalent on just using the command line ```shell -mkdir build && cd build && cmake -G "Unix Makefiles" .. && cmake --build . +> mkdir build-android +> cd build-android +> cmake ../ \ + -DCMAKE_SYSTEM_NAME=Android \ + -DCMAKE_SYSTEM_VERSION= \ + -DCMAKE_ANDROID_ARCH_ABI= \ + -DCMAKE_ANDROID_NDK=/path/to/android-ndk +> cmake --build . ``` -Ensure that you avoid exposing godot-cpp symbols - this might lead to hard to debug errors if you ever load multiple -plugins using difference godot-cpp versions. Use visibility hidden whenever possible: -```cmake -set_target_properties( PROPERTIES CXX_VISIBILITY_PRESET hidden) +Using the toolchain file from the Android ndk + +Defaults to minimum supported version( android-16 in my case) and armv7-a. +```shell +> mkdir build-android +> cd build-android +> cmake ../ --toolchain $ANDROID_HOME/ndk//build/cmake/android.toolchain.cmake +> cmake --build . + ``` -## Todo -Test build for Windows, Mac and mingw. +Specify Android platform and ABI + +```shell +> mkdir build-android +> cd build-android +> cmake ../ --toolchain $ANDROID_HOME/ndk//build/cmake/android.toolchain.cmake \ + -DANDROID_PLATFORM:STRING=android-29 \ + -DANDROID_ABI:STRING=armeabi-v7a +> cmake --build . +``` + + +