Skip to content

Commit

Permalink
More work on the documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@enetheru
enetheru committed Oct 24, 2024
1 parent 1f685dc commit a6b206b
Showing 1 changed file with 64 additions and 34 deletions.
98 changes: 64 additions & 34 deletions doc/cmake.md
View file
Original file line number Diff line number Diff line change
@@ -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: `<compiler> - <arch>-<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-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
Expand All @@ -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"
Expand All @@ -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
```
Expand Down Expand Up @@ -103,32 +82,37 @@ 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
```

## 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
Expand Down Expand Up @@ -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 `<arch>[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

0 comments on commit a6b206b

Please sign in to comment.