Updating commenting to be consistent

(cherry picked from commit 671e309cfa2c06ab60cb528aa7937bf6d65c09c2)

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_<PROJECT-NAME>_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/<platform>.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)

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)
 

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/<platform>.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_<PROJECT-NAME>_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 "$<VERSION_GREATER_EQUAL:$<CXX_COMPILER_VERSION>,11>")
 set(GNU_LT_V11 "$<VERSION_LESS:$<CXX_COMPILER_VERSION>,11>")
 set(GNU_GE_V12 "$<VERSION_GREATER_EQUAL:$<CXX_COMPILER_VERSION>,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.

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 )

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 <n> only specifies

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)
 

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)
 

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)
 

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}

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)
 

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 ``<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
 ~~~~~~~~~~
 
-: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 <https://visualstudio.microsoft.com/vs/>`_
-    :Target: x86_64-w64
-
-`LLVM <https://llvm.org/>`_
-    :Target: x86_64-pc-windows-msvc
-
-`AndroidSDK <https://developer.android.com/studio/#command-tools>`_
-    armv7-none-linux-androideabi16
-
-`Emscripten <https://emscripten.org/>`_
-    :Compiler: Emscripten
-    :Target: 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/>`_
+* `Microsoft Visual Studio 17 2022 <https://visualstudio.microsoft.com/vs/>`_
+* `LLVM <https://llvm.org/>`_
+* `LLVM-MinGW <https://github.com/mstorsjo/llvm-mingw/releases>`_
 
-        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 <https://developer.android.com/studio/#command-tools>`_
+* `Emscripten <https://emscripten.org/>`_
+* `MinGW-W64-builds <https://github.com/niXman/mingw-builds-binaries/releases>`_
+* `Jetbrains-CLion <https://www.jetbrains.com/clion/>`_
 
-    `LLVM-MinGW <https://github.com/mstorsjo/llvm-mingw/releases>`_
+	Jetbrains builtin compiler is just the MingW64 above.
 
-    `MinGW-W64-builds <https://github.com/niXman/mingw-builds-binaries/releases>`_
-        :Compiler: gcc
-        :Target: x86_64-w64-mingw32-ucrt
+* `MSYS2 <https://www.msys2.org/>`_
+	Necessary reading about MSYS2 `environments <https://www.msys2.org/docs/environments/>`_
 
-    `Jetbrains-CLion <https://www.jetbrains.com/clion/>`_
-        :Target: x86_64-w64-mingw32-msvcrt
+	* ucrt64
+	* clang64
+	* mingw32
+	* mingw64
+	* clangarm64