add comments

SlopeCraft · Jul 11, 2023 · b1b2cde · b1b2cde
1 parent e8523c5
commit b1b2cde
Showing 1 changed file with 40 additions and 37 deletions.
diff --git a/DLLDeployer.cmake b/DLLDeployer.cmake
@@ -1,12 +1,11 @@
 cmake_minimum_required(VERSION 3.20)
 
+# If CMAKE_GENERATOR is defined, we guess that this script is running at configuration time
 if (DEFINED CMAKE_GENERATOR)
-    #    message(STATUS "CMAKE_SOURCE_DIR = ${CMAKE_SOURCE_DIR}")
-    #    message(STATUS "CMAKE_BINARY_DIR = ${CMAKE_BINARY_DIR}")
-    #    message(STATUS "CMAKE_GENERATOR = ${CMAKE_GENERATOR}")
     message(STATUS "Running at configuration time")
     option(DLLD_configure_time "Whether this script is running at configuration time" ON)
 else ()
+    # Otherwise we guess that it's running at build or installation time.
     message(STATUS "Running at build/install time")
     option(DLLD_configure_time "Whether this script is running at configuration time" OFF)
 endif ()
@@ -17,7 +16,8 @@ if (NOT ${WIN32})
 endif ()
 
 
-function(DLLD_replace_inv_slash in_var out_var)
+# Replace backslash \ with slash /
+function(DLLD_replace_backslash in_var out_var)
     set(temp)
     foreach (item ${${in_var}})
         string(REPLACE "\\" "/" item ${item})
@@ -27,26 +27,28 @@ function(DLLD_replace_inv_slash in_var out_var)
 endfunction()
 
 if (NOT ${DLLD_configure_time})
-    set(DLLD_msvc_utils @DLLD_msvc_utils@)
-    set(DLLD_msvc_dumpbin_exe "@DLLD_msvc_dumpbin_exe@")
-    set(DLLD_gnu_objdump_exe "@DLLD_gnu_objdump_exe@")
-    set(CMAKE_C_COMPILER "@CMAKE_C_COMPILER@")
-    set(CMAKE_CXX_COMPILER "@CMAKE_CXX_COMPILER@")
-    set(CMAKE_CXX_COMPILER_ID "@CMAKE_CXX_COMPILER_ID@")
-    set(CMAKE_PREFIX_PATH "@CMAKE_PREFIX_PATH@")
-    set(MSVC @MSVC@)
-    set(DLLD_filename @DLLD_filename@)
-    set(DLLD_this_script_file @DLLD_configured_script_file@)
-    set(ENV{Path} "@DLLD_env_path@")
-
-    option(DLLD_install_mode "Run with install mode" ON)
-    set(DLLD_install_prefix @DLLD_add_deploy_INSTALL_DESTINATION@)
+    # These variables are necessary when the script running at build or installation time. They are kept by configure_file
+    set(DLLD_msvc_utils @DLLD_msvc_utils@)                              # Whether to use binary utils provided by msvc toolchain
+    set(DLLD_msvc_dumpbin_exe "@DLLD_msvc_dumpbin_exe@")                # dumpbin.exe
+    set(DLLD_gnu_objdump_exe "@DLLD_gnu_objdump_exe@")                  # objdump.exe
+    set(CMAKE_C_COMPILER "@CMAKE_C_COMPILER@")                          # C compiler
+    set(CMAKE_CXX_COMPILER "@CMAKE_CXX_COMPILER@")                      # C++ compiler
+    set(CMAKE_CXX_COMPILER_ID "@CMAKE_CXX_COMPILER_ID@")                # C++ compiler id
+    set(CMAKE_PREFIX_PATH "@CMAKE_PREFIX_PATH@")                        # CMAKE_PREFIX_PATH is extremely important for find_file
+    set(MSVC @MSVC@)                                                    # If the compiler is MSVC-like
+    set(DLLD_filename @DLLD_filename@)                                  # The executable file to be deployed
+    set(DLLD_this_script_file @DLLD_configured_script_file@)            # The location of this file(generated by configure_file)
+    set(ENV{Path} "@DLLD_env_path@")                                    # Path
+
+    option(DLLD_install_mode "Run with install mode" ON)                # Whether the script is run during installation
+    set(DLLD_install_prefix @DLLD_add_deploy_INSTALL_DESTINATION@)      # The installation prefix of executable
     #message(WARNING "CMAKE_CXX_COMPILER_ID = ${CMAKE_CXX_COMPILER_ID}")
 else ()
-    set(DLLDeployer_script_file ${CMAKE_CURRENT_LIST_FILE}
+    # These variables are necessary in the configuration time
+    set(DLLDeployer_script_file ${CMAKE_CURRENT_LIST_FILE}              # The file location of this script
         CACHE FILEPATH "This cmake script")
-    set(DLLD_env_path $ENV{Path})
-    DLLD_replace_inv_slash(DLLD_env_path DLLD_env_path)
+    set(DLLD_env_path $ENV{Path})                                       # Convert backslash in path to slash
+    DLLD_replace_backslash(DLLD_env_path DLLD_env_path)
 endif ()
 
 
@@ -98,6 +100,7 @@ function(DLLD_is_system_dll lib_file out_var_name)
     endif ()
 endfunction(DLLD_is_system_dll)
 
+# Guess the abi of c++ compiler, and then
 if (${DLLD_configure_time})
     if (${MSVC})
         # if the compiler is msvc-like use msvc utils
@@ -113,32 +116,30 @@ if (${DLLD_configure_time})
             cmake_path(GET compiler_prefix PARENT_PATH compiler_prefix)
 
             if (EXISTS ${compiler_prefix}/bin/c++.exe)
-                # Clang with mingw abi
+                # Clang with mingw abi(libstdc++ or libc++)
                 set(DLLD_msvc_utils_default_val OFF)
             else ()
-                # clang-msvc with gnu-like command line
+                # clang with msvc abi and gnu-like command line
                 set(DLLD_msvc_utils_default_val ON)
             endif ()
         endif ()
 
-
         if (${CMAKE_CXX_COMPILER_ID} STREQUAL "MSVC")
+            # MSVC
             set(DLLD_msvc_utils_default_val ON)
         endif ()
     endif ()
 
 endif ()
 
-#if(${DLLD_configure_time})
 option(DLLD_msvc_utils "Use msvc utils" ${DLLD_msvc_utils_default_val})
-#endif ()
 
 
 if (${DLLD_msvc_utils})
     #find_program(DLLD_msvc_lib_exe NAMES lib REQUIRED)
     unset(DLLD_msvc_dumpbin_exe)
     find_program(DLLD_msvc_dumpbin_exe NAMES dumpbin REQUIRED)
-    # Get dll dependents of a dll
+    # Get dll dependents of a dll. This function runs directly without recursion
     function(DLLD_get_dll_dependents_norecurse dll_file result_var_name)
         DLLD_is_dll(${dll_file} is_dll)
         #        if (NOT ${is_dll})
@@ -149,12 +150,12 @@ if (${DLLD_msvc_utils})
         if (NOT DLLD_msvc_dumpbin_exe)
             message(FATAL_ERROR "dumpbin.exe is not found on this computer, but you are using a msvc-like compiler, please install msvc and make sure the environment variables are initialized for msvc.")
         endif ()
-
+        # dumpbin /dependents xxx.dll
         execute_process(COMMAND ${DLLD_msvc_dumpbin_exe} /dependents ${dll_file}
             OUTPUT_VARIABLE lib_output
             #OUTPUT_QUIET
             COMMAND_ERROR_IS_FATAL ANY)
-
+        # parse the output of dumpbin
         string(REPLACE "\n" ";" lib_output ${lib_output})
         set(result)
         foreach (output ${lib_output})
@@ -188,12 +189,12 @@ else ()
         if (NOT DLLD_gnu_objdump_exe)
             message(FATAL_ERROR "You are using a non-msvc compiler, but objdump is not found")
         endif ()
-
+        # objdump xxx.dll -x --section=.idata | findstr "DLL Name:"
         execute_process(COMMAND ${DLLD_gnu_objdump_exe} ${dll_file} -x --section=.idata
             COMMAND findstr "DLL Name:"
             OUTPUT_VARIABLE outputs
             COMMAND_ERROR_IS_FATAL ANY)
-
+        # Parse the output of objdump
         string(REPLACE "\n" ";" outputs ${outputs})
 
         set(result)
@@ -213,6 +214,7 @@ else ()
     endfunction(DLLD_get_dll_dependents_norecurse)
 endif ()
 
+# Get dll deps recursively
 function(DLLD_get_dll_dependents dll_location out_var_name)
     unset(${out_var_name} PARENT_SCOPE)
 
@@ -319,9 +321,8 @@ function(DLLD_deploy_runtime file_location)
     endforeach ()
 endfunction()
 
-#message("CMAKE_CURRENT_LIST_FILE = ${CMAKE_CURRENT_LIST_FILE}")
 
-#message(WARNING "Function DLLD_add_deploy is not finished. No way to get the filename of this script")
+# Main API
 function(DLLD_add_deploy target_name)
     cmake_parse_arguments(DLLD_add_deploy
         "BUILD_MODE;INSTALL_MODE;ALL" "INSTALL_DESTINATION" "" ${ARGN})
@@ -340,8 +341,8 @@ function(DLLD_add_deploy target_name)
         ${DLLD_configured_script_file}
         @ONLY)
 
+    # Build mode
     if (${DLLD_add_deploy_BUILD_MODE})
-
         if (${DLLD_add_deploy_ALL})
             set(DLLD_all_tag ALL)
         else ()
@@ -366,9 +367,8 @@ function(DLLD_add_deploy target_name)
         if(DLLD_add_deploy_ALL)
             message(FATAL_ERROR "\"ALL\" can only be assigned for BUILD_MODE")
         endif ()
-
     endif ()
-
+    # Install mode
     if (${DLLD_add_deploy_INSTALL_MODE})
         message("DLLD_add_deploy_INSTALL_DESTINATION = ${DLLD_add_deploy_INSTALL_DESTINATION}")
         if(NOT DEFINED DLLD_add_deploy_INSTALL_DESTINATION)
@@ -383,9 +383,9 @@ function(DLLD_add_deploy target_name)
         install(SCRIPT ${DLLD_configured_script_file}
             DESTINATION ${DLLD_add_deploy_INSTALL_DESTINATION})
     endif ()
-
 endfunction()
 
+# This code will execute only during build or installation
 if (NOT ${DLLD_configure_time})
     #cmake_path(GET DLLD_this_script_file PARENT_PATH parent_path)
 
@@ -394,6 +394,7 @@ if (NOT ${DLLD_configure_time})
 #    endif ()
 
     if(NOT ${DLLD_install_mode})
+        # Deploy dlls directly in current dir
         message(STATUS "Deploying dlls for ${DLLD_filename}")
         #message(STATUS "CMAKE_CURRENT_SOURCE_DIR = ${CMAKE_CURRENT_SOURCE_DIR}")
         #message(WARNING "DLLD_filename = ${DLLD_filename}")
@@ -403,6 +404,8 @@ if (NOT ${DLLD_configure_time})
             DESTINATION .)
         return()
     else ()
+        # Run this script in another location(installation prefix)
+        # This is necessary because although the script is installed by install(SCRIPT ... DESTINATION...), the execution directory is still the same dir of the configured script.
         message(STATUS "Running ${DLLD_this_script_file} indirectly...")
         execute_process(COMMAND cmake -DDLLD_install_mode:BOOL=false -P ${DLLD_this_script_file}
             WORKING_DIRECTORY "${CMAKE_INSTALL_PREFIX}/${DLLD_install_prefix}"