diff --git a/doc/cmake.md b/doc/cmake.md index ab643f805c..51edca2aaa 100644 --- a/doc/cmake.md +++ b/doc/cmake.md @@ -1,35 +1,11 @@ # CMake -> **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) +> **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](https://github.com/IvanInventor/godot-cpp/tree/cmake-rewrite) | [Vorlac's godot-roguelite Project](https://github.com/vorlac/godot-roguelite) -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 +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 a practical example on how to consume the godot-cpp library as part of a Godot extension. [Configuration examples](#Examples) are listed at the bottom of the page. -## Tested Toolchains -I'm still trying to make sense of cross compiling infrastructure, so I apologize 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-w64-ucrt - * clang64 - * llvm - x86_64-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-w64-msvcrt -* [LLVM](https://llvm.org/) - * llvm - x86_64-w64-ucrt -* [AndroidSDK](https://developer.android.com/studio/#command-tools) - * armv7-none-linux-androideabi16 -* [Emscripten](https://emscripten.org/) - * emcc - wasm32 - ## Clone the git repository ```shell @@ -48,11 +24,14 @@ Create a build directory for cmake to put caches and build artifacts in and chan ## 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` +To see the list of generators run `cmake --help` + +The current working directory is the build directory that was created in the previous step. -Current working directory is the build directory from the previous step. +Configure and generate Ninja build files. +Review [build-configurations](https://cmake.org/cmake/help/latest/manual/cmake-buildsystem.7.html#build-configurations) for more information. -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` +> **NOTE**: The build configuration does not yet match the SCons targets of 'editor', 'template_release', 'template_debug' ```shell > cmake ../ -DCMAKE_BUILD_TYPE=Debug -G "Ninja" @@ -63,10 +42,10 @@ To list the available options cmake use the `-L[AH]` option. `A` is for advanced > 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 +Review [setting-build-variables](https://cmake.org/cmake/help/latest/guide/user-interaction/index.html#setting-build-variables) for more information. + ```shell > cmake ../ -DGODOT_USE_HOT_RELOAD:BOOL=ON -DGODOT_PRECISION:STRING=double ``` @@ -103,22 +82,24 @@ GODOT_WARNING_AS_ERROR:BOOL=OFF ## Building -Building the default `all` target +Building the default `all` target, this will just be the `godot-cpp` target. ```shell > cmake --build . ``` -Listing build a targets +Listing build a targets may show a lot of files due to the way the bindings generator works, but there are really only two targets `godot-cpp` and `godot-cpp-test` + ```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. +When using multi-config generators like `Ninja Multi-Config`, `Visual Studio *` or `Xcode` the build configuration needs to be specified at build time. ```shell > cmake --build . -t godot-cpp --config Release @@ -126,9 +107,12 @@ When using multi-config generators like `Ninja Multi-Config`, `Visual Studio *` ## Examples +> **NOTE**: Because the CMake scripts do not yet have feature parity with SCons, these examples are very simplistic and do not build the editor/template_release/template_debug equivalents. + #### 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. +Assuming the current working directory is the godot-cpp project root: ```shell > mkdir build-msvc > cd build-msvc @@ -217,3 +201,49 @@ Specify Android platform and ABI -DANDROID_ABI:STRING=armeabi-v7a > cmake --build . ``` + +## Toolchains +This section attempts to list the host and target combinations that have been at tested. + +Info on cross compiling triplets indicates that the naming is a little more freeform that expected, and tailored to its use case. Triplets tend to have the format `[sub][-vendor][-OS][-env]` + +* [osdev.org](https://wiki.osdev.org/Target_Triplet) +* [stack overflow](https://stackoverflow.com/questions/13819857/does-a-list-of-all-known-target-triplets-in-use-exist) +* [LLVM](https://llvm.org/doxygen/classllvm_1_1Triple.html) +* [clang target triple](https://clang.llvm.org/docs/CrossCompilation.html#target-triple) +* [vcpkg](https://learn.microsoft.com/en-us/vcpkg/concepts/triplets) +* [wasm32-unknown-emscripten](https://blog.therocode.net/2020/10/a-guide-to-rust-sdl2-emscripten) + +### Linux Host +Untested + +### MacOS Host +Untested + +### Windows Host + +#### [Microsoft Visual Studio 17 2022](https://visualstudio.microsoft.com/vs/) + x86_64-w64 + +#### [LLVM](https://llvm.org/) + x86_64-pc-windows-msvc + +#### [AndroidSDK](https://developer.android.com/studio/#command-tools) + armv7-none-linux-androideabi16 + +#### [Emscripten](https://emscripten.org/) + wasm32-unknown-emscripten + +#### [MinGW-w64](https://www.mingw-w64.org/) based toolchains + +##### [MSYS2](https://www.msys2.org/) +Necessary reading about MSYS2 [environments](https://www.msys2.org/docs/environments/) + + ucrt64/gcc - x86_64-w64-mingw32 + clang64/clang - x86_64-w64-mingw32 + +##### [LLVM-MinGW](https://github.com/mstorsjo/llvm-mingw/releases) +##### [MinGW-W64-builds](https://github.com/niXman/mingw-builds-binaries/releases) + gcc - x86_64-w64-mingw32-ucrt +##### [Jetbrains-CLion](https://www.jetbrains.com/clion/) + x86_64-w64-mingw32-msvcrt