diff --git a/CMakeLists.txt b/CMakeLists.txt index 5c7e53771..eb878dfe1 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -9,7 +9,9 @@ To enable use of the emscripten emsdk hack for pseudo shared library support without polluting options for consumers we need to use the CMAKE_PROJECT__INCLUDE which was introduced in version 3.17 -Scons Compatibility +For more information check cmake/emsdkHack.cmake + +SCons Compatibility ------------------- There is an understandable conflict between build systems as they define @@ -18,6 +20,9 @@ compromises need to be made to resolve those differences. As we are attempting to maintain feature parity, and ease of maintenance, these CMake scripts are built to resemble the SCons build system wherever possible. +Where they are not, we will attempt to document common difference in +doc/cmake.rst and platform specific differences in their respective +cmake/.cmake file. The file structure and file content are made to match, if not in content then in spirit. The closer the two build systems look the easier they will be to @@ -26,8 +31,7 @@ maintain. Where the SCons additional scripts in the tools directory, The CMake scripts are in the cmake directory. -For example, the tools/godotcpp.py is sourced into SCons, and the 'options' -function is run. +For example; the tools/godotcpp.py is matched by the cmake/godotcpp.cmake file .. highlight:: python @@ -58,7 +62,7 @@ if(GODOTCPP_ENABLE_TESTING) add_subdirectory(test) endif() -# If this is the top level CMakeLists.txt, Generators which honor the -# USE_FOLDERS flag will organize godot-cpp targets under the subfolder -# 'godot-cpp'. This is enable by default from CMake version 3.26 +#[[ If this is the top level CMakeLists.txt, Generators which honor the +USE_FOLDERS flag will organize godot-cpp targets under a subfolder named +'godot-cpp'. This is enable by default from CMake version 3.26 ]] set_property(GLOBAL PROPERTY USE_FOLDERS ON) diff --git a/cmake/android.cmake b/cmake/android.cmake index 72f34e914..b9f49f734 100644 --- a/cmake/android.cmake +++ b/cmake/android.cmake @@ -25,10 +25,23 @@ Android platforms. There is further information and examples in the doc/cmake.rst file. ]=======================================================================] + +#[============================[ Android Options ]============================] function(android_options) - # Android Options + #[[ Options from SCons + + The options below are managed by CMake toolchain files, doc.cmake.rst has + more information + + android_api_level : Target Android API level. + Default = 21 + + ANDROID_HOME : Path to your Android SDK installation. + Default = os.environ.get("ANDROID_HOME", os.environ.get("ANDROID_SDK_ROOT") + ]] endfunction() +#[===========================[ Target Generation ]===========================] function(android_generate) target_compile_definitions(${TARGET_NAME} PUBLIC ANDROID_ENABLED UNIX_ENABLED) diff --git a/cmake/common_compiler_flags.cmake b/cmake/common_compiler_flags.cmake index bfccca47d..ad035be19 100644 --- a/cmake/common_compiler_flags.cmake +++ b/cmake/common_compiler_flags.cmake @@ -7,6 +7,16 @@ configuration. It includes flags like optimization levels, warnings, and features. For target platform specific flags look to each of the ``cmake/.cmake`` files. +The default compile and link options CMake adds can be found in the +platform modules_. When a project is created it initializes its variables from +the ``CMAKE_*`` values. The cleanest way I have found to alter these defaults +is the use of the ``CMAKE_PROJECT__INCLUDE`` as demonstrated by +the emsdkHack.cmake to overcome the limitation on shared library creation. + +So far the emsdkHack is the only modification to the defaults we have made. + +.. _modules: https://github.com/Kitware/CMake/blob/master/Modules/Platform/ + ]=======================================================================] #[[ Compiler Configuration, not to be confused with build targets ]] @@ -25,6 +35,7 @@ set(GNU_GT_V11 "$,11>") set(GNU_LT_V11 "$,11>") set(GNU_GE_V12 "$,12>") +#[===========================[ compiler_detection ]===========================] #[[ Check for clang-cl with MSVC frontend The compiler is tested and set when the project command is called. The variable CXX_COMPILER_FRONTEND_VARIANT was introduced in 3.14 @@ -44,6 +55,9 @@ function(compiler_detection) endif() endfunction() +#[=========================[ common_compiler_flags ]=========================] +#[[ This function assumes it is being called from within one of the platform +generate functions, with all the variables from lower scopes defined. ]] function(common_compiler_flags) # gersemi: off # These compiler options reflect what is in godot/SConstruct. diff --git a/cmake/emsdkHack.cmake b/cmake/emsdkHack.cmake index 9962c0ae4..c5ccc6fc4 100644 --- a/cmake/emsdkHack.cmake +++ b/cmake/emsdkHack.cmake @@ -31,7 +31,7 @@ if(EMSCRIPTEN) set(CMAKE_STRIP FALSE) # used by default in pybind11 on .so modules # The Emscripten toolchain sets the default value for EMSCRIPTEN_SYSTEM_PROCESSOR to x86 - # and CMAKE_SYSTEM_PROCESSOR to this value. I don't want that. + # and copies that to CMAKE_SYSTEM_PROCESSOR. We don't want that. set(CMAKE_SYSTEM_PROCESSOR "wasm32") # the above prevents the need for logic like: #if( ${CMAKE_SYSTEM_NAME} STREQUAL Emscripten ) diff --git a/cmake/godotcpp.cmake b/cmake/godotcpp.cmake index 0d12c5db4..d7397fbca 100644 --- a/cmake/godotcpp.cmake +++ b/cmake/godotcpp.cmake @@ -11,18 +11,12 @@ This if statement simply silences that warning. if(CMAKE_C_COMPILER) endif() -#[=======================================================================[.rst: -Include Platform Files ----------------------- - -Because these files are included into the top level CMakelists.txt before the +#[[ Include Platform Files +Because these files are included into the top level CMakeLists.txt before the project directive, it means that -* ``CMAKE_CURRENT_SOURCE_DIR`` is the location of godot-cpp's CMakeLists.txt -* ``CMAKE_SOURCE_DIR`` is the location where any prior ``project(...)`` - directive was - -]=======================================================================] +CMAKE_CURRENT_SOURCE_DIR is the location of godot-cpp's CMakeLists.txt +CMAKE_SOURCE_DIR is the location where any prior project() directive was ]] include(${CMAKE_CURRENT_SOURCE_DIR}/cmake/GodotCPPModule.cmake) include(${CMAKE_CURRENT_SOURCE_DIR}/cmake/common_compiler_flags.cmake) include(${CMAKE_CURRENT_SOURCE_DIR}/cmake/android.cmake) @@ -59,7 +53,8 @@ set(ARCH_LIST wasm32 ) -# Function to map processors to known architectures +#[=============================[ godot_arch_name ]=============================] +#[[ Function to map CMAKE_SYSTEM_PROCESSOR names to godot arch equivalents ]] function(godot_arch_name OUTVAR) # Special case for macos universal builds that target both x86_64 and arm64 if(DEFINED CMAKE_OSX_ARCHITECTURES) @@ -109,7 +104,7 @@ endfunction() function(godotcpp_options) #NOTE: platform is managed using toolchain files. #NOTE: arch is managed by using toolchain files. - # Except for macos universal, which can be set by GODOTCPP_MACOS_UNIVERSAL=YES + # To create a universal build for macos, set CMAKE_OSX_ARCHITECTURES # Input from user for GDExtension interface header and the API JSON file set(GODOTCPP_GDEXTENSION_DIR @@ -183,7 +178,7 @@ function(godotcpp_options) windows_options() endfunction() -# Function to configure and generate the targets +#[===========================[ Target Generation ]===========================] function(godotcpp_generate) #[[ Multi-Threaded MSVC Compilation When using the MSVC compiler the build command -j only specifies diff --git a/cmake/ios.cmake b/cmake/ios.cmake index 0a14a5429..1ec38515f 100644 --- a/cmake/ios.cmake +++ b/cmake/ios.cmake @@ -1,15 +1,34 @@ #[=======================================================================[.rst: -Ios +iOS --- This file contains functions for options and configuration for targeting the -Ios platform +iOS platform ]=======================================================================] + +#[==============================[ iOS Options ]==============================] function(ios_options) - # iOS options + #[[ Options from SCons + + TODO ios_simulator: Target iOS Simulator + Default: False + + TODO ios_min_version: Target minimum iphoneos/iphonesimulator version + Default: 12.0 + + TODO IOS_TOOLCHAIN_PATH: Path to iOS toolchain + Default: "/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain", + + TODO IOS_SDK_PATH: Path to the iOS SDK + Default: '' + + TODO ios_triple: Triple for ios toolchain + Default: if has_ios_osxcross(): 'ios_triple' else '' + ]] endfunction() +#[===========================[ Target Generation ]===========================] function(ios_generate) target_compile_definitions(${TARGET_NAME} PUBLIC IOS_ENABLED UNIX_ENABLED) diff --git a/cmake/linux.cmake b/cmake/linux.cmake index eab107cc0..717a7d672 100644 --- a/cmake/linux.cmake +++ b/cmake/linux.cmake @@ -6,10 +6,17 @@ This file contains functions for options and configuration for targeting the Linux platform ]=======================================================================] + +#[=============================[ Linux Options ]=============================] function(linux_options) - # Linux Options + #[[ Options from SCons + use_llvm : Use the LLVM compiler + Not implemented as compiler selection is managed by CMake. Look to + doc/cmake.rst for examples. + ]] endfunction() +#[===========================[ Target Generation ]===========================] function(linux_generate) target_compile_definitions(${TARGET_NAME} PUBLIC LINUX_ENABLED UNIX_ENABLED) diff --git a/cmake/macos.cmake b/cmake/macos.cmake index 8b89d9dc2..1ae29bc65 100644 --- a/cmake/macos.cmake +++ b/cmake/macos.cmake @@ -5,9 +5,12 @@ MacOS This file contains functions for options and configuration for targeting the MacOS platform -# To build universal binaries, ie targeting both x86_64 and arm64, use -# the CMAKE_OSX_ARCHITECTURES variable prior to any project calls. -# https://cmake.org/cmake/help/latest/variable/CMAKE_OSX_ARCHITECTURES.html +Universal Builds +---------------- + +To build universal binaries, ie targeting both x86_64 and arm64, use +the CMAKE_OSX_ARCHITECTURES variable prior to any project calls. +https://cmake.org/cmake/help/latest/variable/CMAKE_OSX_ARCHITECTURES.html ]=======================================================================] @@ -24,9 +27,21 @@ if(APPLE) ) endif(APPLE) +#[=============================[ MacOS Options ]=============================] function(macos_options) + #[[ Options from SCons + TODO macos_deployment_target: macOS deployment target + Default: 'default' + + TODO macos_sdk_path: macOS SDK path + Default: '' + + TODO osxcross_sdk: OSXCross SDK version + Default: if has_osxcross(): "darwin16" else None + ]] endfunction() +#[===========================[ Target Generation ]===========================] function(macos_generate) target_compile_definitions(${TARGET_NAME} PUBLIC MACOS_ENABLED UNIX_ENABLED) diff --git a/cmake/web.cmake b/cmake/web.cmake index ef29b325b..e12d389c3 100644 --- a/cmake/web.cmake +++ b/cmake/web.cmake @@ -10,17 +10,13 @@ Web platform # Emscripten requires this hack for use of the SHARED option set(CMAKE_PROJECT_godot-cpp_INCLUDE cmake/emsdkHack.cmake) +#[==============================[ Web Options ]==============================] function(web_options) - # web options endfunction() +#[===========================[ Target Generation ]===========================] function(web_generate) - target_compile_definitions( - ${TARGET_NAME} - PUBLIC # - WEB_ENABLED - UNIX_ENABLED - ) + target_compile_definitions(${TARGET_NAME} PUBLIC WEB_ENABLED UNIX_ENABLED) target_compile_options( ${TARGET_NAME} diff --git a/cmake/windows.cmake b/cmake/windows.cmake index 0d330a0f0..d0c115204 100644 --- a/cmake/windows.cmake +++ b/cmake/windows.cmake @@ -53,7 +53,21 @@ documentation. .. _issues: https://github.com/godotengine/godot-cpp/issues/1699 ]=======================================================================] + +#[============================[ Windows Options ]============================] function(windows_options) + #[[ Options from SCons + + TODO silence_msvc: Silence MSVC's cl/link stdout bloat, redirecting errors to stderr + Default: True + + These three options will not implemented as compiler selection is managed + by CMake toolchain files. Look to doc/cmake.rst for examples. + use_mingw: Use the MinGW compiler instead of MSVC - only effective on Windows + use_llvm: Use the LLVM compiler (MVSC or MinGW depending on the use_mingw flag + mingw_prefix: MinGW prefix + ]] + option(GODOTCPP_USE_STATIC_CPP "Link MinGW/MSVC C++ runtime libraries statically" ON) option(GODOTCPP_DEBUG_CRT "Compile with MSVC's debug CRT (/MDd)" OFF) diff --git a/doc/cmake.rst b/doc/cmake.rst index 8045aa644..bde0a6a69 100644 --- a/doc/cmake.rst +++ b/doc/cmake.rst @@ -24,6 +24,22 @@ 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 I've seen 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 + Sets compiler flags so that debug symbols are generated to help godot + extension developers debug their extension. + + SCons Deviations ---------------- @@ -312,22 +328,9 @@ 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 `_ -* `stack overflow `_ -* `LLVM `_ -* `clang target triple `_ -* `vcpkg `_ -* `wasm32-unknown-emscripten `_ - Linux Host ~~~~~~~~~~ -:Target: x86_64-linux - Macos Host ~~~~~~~~~~ @@ -335,43 +338,36 @@ Macos Host :OS Name: Sequoia 15.0.1 :Processor: Apple M2 +* AppleClang + Windows Host ~~~~~~~~~~~~ -:OS Name: Microsoft Windows 11 Home, 10.0.22631 N/A Build 22631 +:OS Name: Windows 11 :Processor: AMD Ryzen 7 6800HS Creator Edition -`Microsoft Visual Studio 17 2022 `_ - :Target: x86_64-w64 - -`LLVM `_ - :Target: x86_64-pc-windows-msvc - -`AndroidSDK `_ - armv7-none-linux-androideabi16 - -`Emscripten `_ - :Compiler: Emscripten - :Target: wasm32-unknown-emscripten - -`MinGW-w64 `_ based toolchains - `MSYS2 `_ - Necessary reading about MSYS2 `environments `_ +* `Microsoft Visual Studio 17 2022 `_ +* `LLVM `_ +* `LLVM-MinGW `_ - ucrt64 - :Compiler: gcc version 14.2.0 (Rev1, Built by MSYS2 project) - :Target: x86_64-w64-mingw32 + * aarch64-w64-mingw32 + * armv7-w64-mingw32 + * i686-w64-mingw32 + * x86_64-w64-mingw32 - clang64 - :Compiler: clang version 18.1.8 - :Target: x86_64-w64-windows-gnu +* `AndroidSDK `_ +* `Emscripten `_ +* `MinGW-W64-builds `_ +* `Jetbrains-CLion `_ - `LLVM-MinGW `_ + Jetbrains builtin compiler is just the MingW64 above. - `MinGW-W64-builds `_ - :Compiler: gcc - :Target: x86_64-w64-mingw32-ucrt +* `MSYS2 `_ + Necessary reading about MSYS2 `environments `_ - `Jetbrains-CLion `_ - :Target: x86_64-w64-mingw32-msvcrt + * ucrt64 + * clang64 + * mingw32 + * mingw64 + * clangarm64