UseSWIG: Add new behavior for better support files management

fixes: #17840

1 files changed, 115 insertions, 40 deletions

diff --git a/Modules/UseSWIG.cmake b/Modules/UseSWIG.cmake
index 8e7ca41..5f9afc1 100644
--- a/Modules/UseSWIG.cmake
+++ b/Modules/UseSWIG.cmake
@@ -5,7 +5,10 @@
 UseSWIG
 -------
 
-Defines the following command for use with SWIG:
+This file provides support for ``SWIG``. It is assumed that :module:`FindSWIG`
+module has already been loaded.
+
+Defines the following command for use with ``SWIG``:
 
 .. command:: swig_add_library
 
@@ -20,17 +23,19 @@ Defines the following command for use with SWIG:
                      SOURCES <file>...
                     )
 
-  Targets created with command ``swig_add_library`` have the same capabilities as targets
-  created with command :command:`add_library`, so can be used with any command accepting a target
-  especially command :command:`target_link_libraries`.
+  Targets created with the ``swig_add_library`` command have the same
+  capabilities as targets created with the :command:`add_library` command, so
+  those targets can be used with any command expecting a target (e.g.
+  :command:`target_link_libraries`).
 
   The arguments are:
 
   ``TYPE``
-    ``SHARED``, ``MODULE`` and ``STATIC`` have same semantic as command :command:`add_library`.
-    if ``USE_BUILD_SHARED_LIBS`` is specified, library type will be ``STATIC`` or ``SHARED``
-    based on whether the current value of the variable :variable:`BUILD_SHARED_LIBS` is ``ON``.
-    If none is specified, ``MODULE`` will be used.
+    ``SHARED``, ``MODULE`` and ``STATIC`` have the same semantic as for the
+    :command:`add_library` command. If ``USE_BUILD_SHARED_LIBS`` is specified,
+    the library type will be ``STATIC`` or ``SHARED`` based on whether the
+    current value of the :variable:`BUILD_SHARED_LIBS` variable is ``ON``. If
+    no type is specified, ``MODULE`` will be used.
 
   ``LANGUAGE``
     Specify the target language.
@@ -39,22 +44,40 @@ Defines the following command for use with SWIG:
     Prevent the generation of the wrapper layer (swig ``-noproxy`` option).
 
   ``OUTPUT_DIR``
-    Specify where to write the language specific files (swig ``-outdir`` option).
-    If not specified, variable ``CMAKE_SWIG_OUTDIR`` will be used. If none is specified,
-    :variable:`CMAKE_CURRENT_BINARY_DIR` is used.
+    Specify where to write the language specific files (swig ``-outdir``
+    option). If not given, the ``CMAKE_SWIG_OUTDIR`` variable will be used.
+    If neither is specified, the default depends on the value of the
+    ``UseSWIG_MODULE_VERSION`` variable as follows:
+
+    * If ``UseSWIG_MODULE_VERSION`` is 1 or is undefined, output is written to
+      the :variable:`CMAKE_CURRENT_BINARY_DIR` directory.
+    * If ``UseSWIG_MODULE_VERSION`` is 2, a dedicated directory will be used.
+      The path of this directory can be retrieved from the
+      ``SWIG_SUPPORT_FILES_DIRECTORY`` target property.
 
   ``OUTFILE_DIR``
-    Specify an output directory name where the generated source file will be placed
-    (swig -o option). If not specified, variable ``SWIG_OUTFILE_DIR`` will be used.
-    If none is specified, option ``OUTPUT_DIR`` or variable ``CMAKE_SWIG_OUTDIR`` is used.
+    Specify an output directory name where the generated source file will be
+    placed (swig -o option). If not specified, the ``SWIG_OUTFILE_DIR`` variable
+    will be used. If neither is specified, ``OUTPUT_DIR`` or
+    ``CMAKE_SWIG_OUTDIR`` is used instead.
 
   ``SOURCES``
-    List of sources for the library. Files with extension ``.i`` will be identified as sources
-    for ``SWIG`` tool. Other files will be handled in the standard way.
+    List of sources for the library. Files with extension ``.i`` will be
+    identified as sources for the ``SWIG`` tool. Other files will be handled in
+    the standard way.
+
+.. note::
 
-Source files properties on module files **must** be set before the invocation
-of the ``swig_add_library`` command to specify special behavior of SWIG and ensure
-generated files will receive required settings.
+  If ``UseSWIG_MODULE_VERSION`` is set to 2, it is **strongly** recommended
+  to use a dedicated directory unique to the target when either the
+  ``OUTPUT_DIR`` option or the ``CMAKE_SWIG_OUTDIR`` variable are specified.
+  The output directory contents are erased as part of the target build, so
+  to prevent interference between targets or losing other important files, each
+  target should have its own dedicated output directory.
+
+Source file properties on module files **must** be set before the invocation
+of the ``swig_add_library`` command to specify special behavior of SWIG and
+ensure generated files will receive the required settings.
 
 ``CPLUSPLUS``
   Call SWIG in c++ mode.  For example:
@@ -66,7 +89,8 @@ generated files will receive required settings.
 
 ``INCLUDE_DIRECTORIES``, ``COMPILE_DEFINITIONS`` and ``COMPILE_OPTIONS``
   Add custom flags to SWIG compiler and have same semantic as properties
-  :prop_sf:`INCLUDE_DIRECTORIES`, :prop_sf:`COMPILE_DEFINITIONS` and :prop_sf:`COMPILE_OPTIONS`.
+  :prop_sf:`INCLUDE_DIRECTORIES`, :prop_sf:`COMPILE_DEFINITIONS` and
+  :prop_sf:`COMPILE_OPTIONS`.
 
 ``GENERATED_INCLUDE_DIRECTORIES``, ``GENERATED_COMPILE_DEFINITIONS`` and ``GENERATED_COMPILE_OPTIONS``
   Add custom flags to the C/C++ generated source. They will fill, respectively,
@@ -85,12 +109,13 @@ generated files will receive required settings.
 
     set_property(SOURCE mymod.i PROPERTY SWIG_MODULE_NAME mymod_realname)
 
-Target library properties can be set to apply same configuration to all SWIG input files.
+Target library properties can be set to apply same configuration to all SWIG
+input files.
 
 ``SWIG_INCLUDE_DIRECTORIES``, ``SWIG_COMPILE_DEFINITIONS`` and ``SWIG_COMPILE_OPTIONS``
-  These properties will be applied to all SWIG input files and have same semantic as
-  target properties :prop_tgt:`INCLUDE_DIRECTORIES`, :prop_tgt:`COMPILE_DEFINITIONS` and
-  :prop_tgt:`COMPILE_OPTIONS`.
+  These properties will be applied to all SWIG input files and have same
+  semantic as target properties :prop_tgt:`INCLUDE_DIRECTORIES`,
+  :prop_tgt:`COMPILE_DEFINITIONS` and :prop_tgt:`COMPILE_OPTIONS`.
 
   .. code-block:: cmake
 
@@ -99,12 +124,16 @@ Target library properties can be set to apply same configuration to all SWIG inp
     set_property(TARGET mymod PROPERTY SWIG_COMPILE_OPTIONS -bla -blb)
 
 ``SWIG_GENERATED_INCLUDE_DIRECTORIES``, ``SWIG_GENERATED_COMPILE_DEFINITIONS`` and ``SWIG_GENERATED_COMPILE_OPTIONS``
-  These properties will populate, respectively, properties :prop_sf:`INCLUDE_DIRECTORIES`,
-  :prop_sf:`COMPILE_DEFINITIONS` and :prop_sf:`COMPILE_FLAGS` of all generated C/C++ files.
+  These properties will populate, respectively, properties
+  :prop_sf:`INCLUDE_DIRECTORIES`, :prop_sf:`COMPILE_DEFINITIONS` and
+  :prop_sf:`COMPILE_FLAGS` of all generated C/C++ files.
 
 ``SWIG_DEPENDS``
   Add dependencies to all SWIG input files.
 
+The following target properties are output properties and can be used to get
+information about support files generated by ``SWIG`` interface compilation.
+
 ``SWIG_SUPPORT_FILES``
   This output property list of wrapper files generated during SWIG compilation.
 
@@ -113,7 +142,26 @@ Target library properties can be set to apply same configuration to all SWIG inp
     swig_add_library(mymod LANGUAGE python SOURCES mymod.i)
     get_property(support_files TARGET mymod PROPERTY SWIG_SUPPORT_FILES)
 
-Some variables can be set to specify special behavior of SWIG:
+  .. note::
+
+    Only most principal support files are listed. In case some advanced
+    features of ``SWIG`` are used (for example ``%template``), associated
+    support files may not be listed. Prefer to use the
+    ``SWIG_SUPPORT_FILES_DIRECTORY`` property to handle support files.
+
+``SWIG_SUPPORT_FILES_DIRECTORY``
+  This output property specifies the directory where support files will be
+  generated.
+
+Some variables can be set to customize the behavior of ``swig_add_library``
+as well as ``SWIG``:
+
+``UseSWIG_MODULE_VERSION``
+  Specify different behaviors for ``UseSWIG`` module.
+
+  * Set to 1 or undefined: Legacy behavior is applied.
+  * Set to 2: A new strategy is applied regarding support files: the output
+    directory of support files is erased before ``SWIG`` interface compilation.
 
 ``CMAKE_SWIG_FLAGS``
   Add flags to all swig calls.
@@ -158,7 +206,6 @@ macro(SWIG_MODULE_INITIALIZE name language)
   string(TOUPPER "${language}" SWIG_MODULE_${name}_LANGUAGE)
   string(TOLOWER "${language}" SWIG_MODULE_${name}_SWIG_LANGUAGE_FLAG)
 
-  set(SWIG_MODULE_${name}_NAME "${name}")
   set(SWIG_MODULE_${name}_EXTRA_FLAGS)
   if (NOT DEFINED SWIG_MODULE_${name}_NOPROXY)
     set (SWIG_MODULE_${name}_NOPROXY FALSE)
@@ -172,11 +219,6 @@ macro(SWIG_MODULE_INITIALIZE name language)
   endif()
   if(SWIG_MODULE_${name}_LANGUAGE STREQUAL "UNKNOWN")
     message(FATAL_ERROR "SWIG Error: Language \"${language}\" not found")
-  elseif(SWIG_MODULE_${name}_LANGUAGE STREQUAL "PYTHON" AND NOT SWIG_MODULE_${name}_NOPROXY)
-    # swig will produce a module.py containing an 'import _modulename' statement,
-    # which implies having a corresponding _modulename.so (*NIX), _modulename.pyd (Win32),
-    # unless the -noproxy flag is used
-    set(SWIG_MODULE_${name}_NAME "_${name}")
   elseif(SWIG_MODULE_${name}_LANGUAGE STREQUAL "PERL")
     list(APPEND SWIG_MODULE_${name}_EXTRA_FLAGS "-shadow")
   endif()
@@ -332,6 +374,14 @@ function(SWIG_ADD_SOURCE_TO_MODULE name outfiles infile)
     list (APPEND swig_dependencies ${file_depends})
   endif()
 
+  if (UseSWIG_MODULE_VERSION VERSION_EQUAL 2)
+    # as part of custom command, start by removing old generated files
+    # to ensure obsolete files do not stay
+    set (swig_cleanup_command COMMAND "${CMAKE_COMMAND}" -E remove_directory "${outdir}")
+  else()
+    unset (swig_cleanup_command)
+  endif()
+
   # IMPLICIT_DEPENDS below can not handle situations where a dependent file is
   # removed. We need an extra step with timestamp and custom target, see #16830
   # As this is needed only for Makefile generator do it conditionally
@@ -352,10 +402,11 @@ function(SWIG_ADD_SOURCE_TO_MODULE name outfiles infile)
   add_custom_command(
     OUTPUT ${swig_custom_output}
     ${swig_custom_products}
+    ${swig_cleanup_command}
     # Let's create the ${outdir} at execution time, in case dir contains $(OutDir)
     COMMAND "${CMAKE_COMMAND}" -E make_directory ${outdir} ${outfiledir}
     ${swig_timestamp_command}
-    COMMAND "${SWIG_EXECUTABLE}"
+    COMMAND "${CMAKE_COMMAND}" -E env "SWIG_LIB=${SWIG_DIR}" "${SWIG_EXECUTABLE}"
     "-${SWIG_MODULE_${name}_SWIG_LANGUAGE_FLAG}"
     "${swig_source_file_flags}"
     -outdir "${outdir}"
@@ -434,6 +485,12 @@ function(SWIG_ADD_LIBRARY name)
     unset(_SAM_TYPE)
   endif()
 
+  if (NOT DEFINED UseSWIG_MODULE_VERSION)
+    set (UseSWIG_MODULE_VERSION 1)
+  elseif (NOT UseSWIG_MODULE_VERSION MATCHES "^(1|2)$")
+    message (FATAL_ERROR "UseSWIG_MODULE_VERSION: ${UseSWIG_MODULE_VERSION}: invalid value. 1 or 2 is expected.")
+  endif()
+
   set (workingdir "${CMAKE_CURRENT_BINARY_DIR}${CMAKE_FILES_DIRECTORY}/${name}.dir")
   # set special variable to pass extra information to command SWIG_ADD_SOURCE_TO_MODULE
   # which cannot be changed due to legacy compatibility
@@ -444,7 +501,11 @@ function(SWIG_ADD_LIBRARY name)
     if (CMAKE_SWIG_OUTDIR)
       set (outputdir "${CMAKE_SWIG_OUTDIR}")
     else()
-      set (outputdir "${CMAKE_CURRENT_BINARY_DIR}")
+      if (UseSWIG_MODULE_VERSION VERSION_EQUAL 2)
+        set (outputdir "${workingdir}/${_SAM_LANGUAGE}.files")
+      else()
+        set (outputdir "${CMAKE_CURRENT_BINARY_DIR}")
+      endif()
     endif()
   endif()
 
@@ -470,6 +531,9 @@ function(SWIG_ADD_LIBRARY name)
 
   set(swig_dot_i_sources ${_SAM_SOURCES})
   list(FILTER swig_dot_i_sources INCLUDE REGEX "\\.i$")
+  if (NOT swig_dot_i_sources)
+    message(FATAL_ERROR "SWIG_ADD_LIBRARY: no SWIG interface files specified")
+  endif()
   set(swig_other_sources ${_SAM_SOURCES})
   list(REMOVE_ITEM swig_other_sources ${swig_dot_i_sources})
 
@@ -486,12 +550,14 @@ function(SWIG_ADD_LIBRARY name)
   endforeach()
   set_property (DIRECTORY APPEND PROPERTY
     ADDITIONAL_MAKE_CLEAN_FILES ${swig_generated_sources} ${swig_generated_timestamps})
+  if (UseSWIG_MODULE_VERSION VERSION_EQUAL 2)
+    set_property (DIRECTORY APPEND PROPERTY ADDITIONAL_MAKE_CLEAN_FILES "${outputdir}")
+  endif()
 
   add_library(${name}
     ${_SAM_TYPE}
     ${swig_generated_sources}
     ${swig_other_sources})
-  set_target_properties(${name} PROPERTIES OUTPUT_NAME "${SWIG_MODULE_${name}_NAME}")
   if(CMAKE_GENERATOR MATCHES "Make")
     # see IMPLICIT_DEPENDS above
     add_custom_target(${name}_swig_compilation DEPENDS ${swig_generated_timestamps})
@@ -524,8 +590,14 @@ function(SWIG_ADD_LIBRARY name)
       set_target_properties(${name} PROPERTIES PREFIX "")
     endif()
   elseif (swig_lowercase_language STREQUAL "python")
-    # this is only needed for the python case where a _modulename.so is generated
-    set_target_properties(${name} PROPERTIES PREFIX "")
+    if (SWIG_MODULE_${name}_NOPROXY)
+      set_target_properties(${name} PROPERTIES PREFIX "")
+    else()
+      # swig will produce a module.py containing an 'import _modulename' statement,
+      # which implies having a corresponding _modulename.so (*NIX), _modulename.pyd (Win32),
+      # unless the -noproxy flag is used
+      set_target_properties(${name} PROPERTIES PREFIX "_")
+    endif()
     # Python extension modules on Windows must have the extension ".pyd"
     # instead of ".dll" as of Python 2.5.  Older python versions do support
     # this suffix.
@@ -560,7 +632,10 @@ function(SWIG_ADD_LIBRARY name)
     # assume empty prefix because we expect the module to be dynamically loaded
     set_target_properties (${name} PROPERTIES PREFIX "")
   endif ()
-  # target property SWIG_SUPPORT_FILES lists proxy support files
+
+  # target property SWIG_SUPPORT_FILES_DIRECTORY specify output directory of support files
+  set_property (TARGET ${name} PROPERTY SWIG_SUPPORT_FILES_DIRECTORY "${outputdir}")
+  # target property SWIG_SUPPORT_FILES lists principal proxy support files
   if (NOT SWIG_MODULE_${name}_NOPROXY)
     string(TOUPPER "${_SAM_LANGUAGE}" swig_uppercase_language)
     set(swig_all_support_files)
@@ -572,7 +647,7 @@ function(SWIG_ADD_LIBRARY name)
     if (swig_all_support_files)
       list(REMOVE_DUPLICATES swig_all_support_files)
     endif()
-    set_property (TARGET ${name} APPEND PROPERTY SWIG_SUPPORT_FILES ${swig_all_support_files})
+    set_property (TARGET ${name} PROPERTY SWIG_SUPPORT_FILES ${swig_all_support_files})
   endif()
 
   # to ensure legacy behavior, export some variables