Updating commenting to be consistent

2026-09-03 23:39:46 +03:00 · 2025-03-02 12:04:30 +10:30
parent 05f5d73876
commit 671e309cfa
11 changed files with 150 additions and 77 deletions
--- 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)

--- 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/<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.
--- 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 )
--- 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 <n> only specifies
--- 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)

--- 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)

--- 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)

--- 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}
--- 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)