-
-
Notifications
You must be signed in to change notification settings - Fork 590
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
2 changed files
with
181 additions
and
37 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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: `<compiler> - <arch>-<vendor>-<OS>-<runtime>` | ||
| ### 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/<version>/build/cmake/android.toolchain.cmake` toolchain and make changes using the `ANDROID_*` variables listed there. Where `<version>` is whatever ndk version you have installed ( tested with `23.2.8568313`) and `<platform>` 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=<platform> \ | ||
| -DCMAKE_ANDROID_ARCH_ABI=<arch> \ | ||
| -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(<all-my-plugin-related-targets> 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/<version>/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/<version>/build/cmake/android.toolchain.cmake \ | ||
| -DANDROID_PLATFORM:STRING=android-29 \ | ||
| -DANDROID_ABI:STRING=armeabi-v7a | ||
| > cmake --build . | ||
| ``` | ||
|
|
||
|
|
||
|
|