CMakePackageConfigHelpers: Add ARCH_INDEPENDENT option

Allow skipping the architecture check in the package version file generated from calling
write_basic_package_version_file. Document said architecture check.

Fixes: #16184

Modules/BasicConfigVersion-AnyNewerVersion.cmake.in

@@ -18,6 +18,12 @@ else()
   endif()
 endif()
 
+
+# if the installed project requested no architecture check, don't perform the check
+if("@CVF_ARCH_INDEPENDENT@")
+  return()
+endif()
+
 # if the installed or the using project don't have CMAKE_SIZEOF_VOID_P set, ignore it:
 if("${CMAKE_SIZEOF_VOID_P}" STREQUAL "" OR "@CMAKE_SIZEOF_VOID_P@" STREQUAL "")
    return()

Modules/BasicConfigVersion-ExactVersion.cmake.in

@@ -34,6 +34,11 @@ if(PACKAGE_FIND_VERSION STREQUAL PACKAGE_VERSION)
 endif()
 
 
+# if the installed project requested no architecture check, don't perform the check
+if("@CVF_ARCH_INDEPENDENT@")
+  return()
+endif()
+
 # if the installed or the using project don't have CMAKE_SIZEOF_VOID_P set, ignore it:
 if("${CMAKE_SIZEOF_VOID_P}" STREQUAL "" OR "@CMAKE_SIZEOF_VOID_P@" STREQUAL "")
    return()

Modules/BasicConfigVersion-SameMajorVersion.cmake.in

@@ -33,6 +33,11 @@ else()
 endif()
 
 
+# if the installed project requested no architecture check, don't perform the check
+if("@CVF_ARCH_INDEPENDENT@")
+  return()
+endif()
+
 # if the installed or the using project don't have CMAKE_SIZEOF_VOID_P set, ignore it:
 if("${CMAKE_SIZEOF_VOID_P}" STREQUAL "" OR "@CMAKE_SIZEOF_VOID_P@" STREQUAL "")
    return()

Modules/BasicConfigVersion-SameMinorVersion.cmake.in

@@ -37,6 +37,11 @@ else()
 endif()
 
 
+# if the installed project requested no architecture check, don't perform the check
+if("@CVF_ARCH_INDEPENDENT@")
+  return()
+endif()
+
 # if the installed or the using project don't have CMAKE_SIZEOF_VOID_P set, ignore it:
 if("${CMAKE_SIZEOF_VOID_P}" STREQUAL "" OR "@CMAKE_SIZEOF_VOID_P@" STREQUAL "")
    return()

Modules/CMakePackageConfigHelpers.cmake

@@ -124,7 +124,8 @@ Generating a Package Version File
 
    write_basic_package_version_file(<filename>
      [VERSION <major.minor.patch>]
-     COMPATIBILITY <AnyNewerVersion|SameMajorVersion|SameMinorVersion|ExactVersion> )
+     COMPATIBILITY <AnyNewerVersion|SameMajorVersion|SameMinorVersion|ExactVersion>
+     [ARCH_INDEPENDENT] )
 
 
 Writes a file for use as ``<PackageName>ConfigVersion.cmake`` file to
@@ -158,6 +159,18 @@ If your project has more elaborated version matching rules, you will need to
 write your own custom ``ConfigVersion.cmake`` file instead of using this
 macro.
 
+If ``ARCH_INDEPENDENT`` is given, the installed package version will be
+considered compatible even if it was built for a different architecture than
+the requested architecture.  Otherwise, an architecture check will be performed,
+and the package will be considered compatible only if the architecture matches
+exactly.  For example, if the package is built for a 32-bit architecture, the
+package is only considered compatible if it is used on a 32-bit architecture,
+unless ``ARCH_INDEPENDENT`` is given, in which case the package is considered
+compatible on any architecture.
+
+.. note:: ``ARCH_INDEPENDENT`` is intended for header-only libraries or similar
+   packages with no binaries.
+
 Internally, this macro executes :command:`configure_file()` to create the
 resulting version file.  Depending on the ``COMPATIBILITY``, the corresponding
 ``BasicConfigVersion-<COMPATIBILITY>.cmake.in`` file is used.

Modules/WriteBasicConfigVersionFile.cmake

@@ -15,6 +15,7 @@ WriteBasicConfigVersionFile
   WRITE_BASIC_CONFIG_VERSION_FILE( filename
     [VERSION major.minor.patch]
     COMPATIBILITY (AnyNewerVersion|SameMajorVersion|SameMinorVersion|ExactVersion)
+    [ARCH_INDEPENDENT]
     )
 
 
@@ -22,7 +23,7 @@ WriteBasicConfigVersionFile
 
 function(WRITE_BASIC_CONFIG_VERSION_FILE _filename)
 
-  set(options )
+  set(options ARCH_INDEPENDENT )
   set(oneValueArgs VERSION COMPATIBILITY )
   set(multiValueArgs )
 

Tests/RunCMake/WriteBasicConfigVersionFile/ArchIndependent.cmake

@@ -0,0 +1,63 @@
+# Hard-code architecture for test without a real compiler.
+set(CMAKE_SIZEOF_VOID_P 4)
+
+include(WriteBasicConfigVersionFile)
+
+set(_dummy_version 1.0.0)
+
+set(_compatibilities AnyNewerVersion
+                     SameMajorVersion
+                     SameMinorVersion
+                     ExactVersion)
+
+function(test_write_basic_config_version_file_arch_prepare filename_out compat arch_independent arch)
+  if(arch_independent)
+    set(arch_arg ARCH_INDEPENDENT)
+  else()
+    set(arch_arg )
+  endif()
+
+  set(filename "${CMAKE_CURRENT_BINARY_DIR}/${compat}Arch${arch_arg}ConfigVersion.cmake")
+
+  set(CMAKE_SIZEOF_VOID_P "${arch}")
+
+  write_basic_config_version_file("${filename}"
+                                  VERSION "${_dummy_version}"
+                                  COMPATIBILITY "${compat}"
+                                  ${arch_arg})
+
+  set("${filename_out}" "${filename}" PARENT_SCOPE)
+endfunction()
+
+function(test_write_basic_config_version_file_arch_check unsuitable_out filename arch)
+  set(CMAKE_SIZEOF_VOID_P "${arch}")
+  set(PACKAGE_FIND_VERSION "${_dummy_version}")
+
+  include("${filename}")
+
+  set("${unsuitable_out}" "${PACKAGE_VERSION_UNSUITABLE}" PARENT_SCOPE)
+endfunction()
+
+function(test_write_basic_config_version_file_arch_test expected_unsuitable compat arch_independent source_arch user_arch)
+  test_write_basic_config_version_file_arch_prepare(filename "${compat}" "${arch_independent}" "${source_arch}")
+  test_write_basic_config_version_file_arch_check(unsuitable "${filename}" "${user_arch}")
+  if(unsuitable AND NOT expected_unsuitable)
+    message(SEND_ERROR "Architecture was checked when it shouldn't have been. Compatibility: ${compat} ARCH_INDEPENDENT: ${arch_independent}.")
+  elseif(expected_unsuitable AND NOT unsuitable)
+    message(SEND_ERROR "Requested architecture check not performed. Compatibility: ${compat} ARCH_INDEPENDENT: ${arch_independent}.")
+  endif()
+endfunction()
+
+set(_unsuitable TRUE)
+set(_suitable FALSE)
+
+foreach(compat ${_compatibilities})
+  test_write_basic_config_version_file_arch_test("${_suitable}" "${compat}" TRUE 4 4)
+  test_write_basic_config_version_file_arch_test("${_suitable}" "${compat}" FALSE 4 4)
+  test_write_basic_config_version_file_arch_test("${_suitable}" "${compat}" TRUE 4 8)
+  test_write_basic_config_version_file_arch_test("${_unsuitable}" "${compat}" FALSE 4 8)
+  test_write_basic_config_version_file_arch_test("${_suitable}" "${compat}" TRUE 8 4)
+  test_write_basic_config_version_file_arch_test("${_unsuitable}" "${compat}" FALSE 8 4)
+  test_write_basic_config_version_file_arch_test("${_suitable}" "${compat}" TRUE 8 8)
+  test_write_basic_config_version_file_arch_test("${_suitable}" "${compat}" FALSE 8 8)
+endforeach()

Tests/RunCMake/WriteBasicConfigVersionFile/RunCMakeTest.cmake

@@ -1,3 +1,4 @@
 include(RunCMake)
 
 run_cmake(All)
+run_cmake(ArchIndependent)