CMakePackageConfigHelpers: Add generate_apple_platform_selection_file()

Issue: #25262

Help/release/dev/install-export-xcframework.rst

@@ -4,3 +4,6 @@ install-export-xcframework
 * The :command:`export(SETUP)` command gained a new ``XCFRAMEWORK_LOCATION``
   argument, which can be used to specify the location of a ``.xcframework``
   that can be substituted for the installed library.
+* The :module:`CMakePackageConfigHelpers` module gained a new
+  :command:`generate_apple_platform_selection_file` function, which can be
+  used to generate a file that includes another Apple-platform-specific file.

Modules/CMakePackageConfigHelpers.cmake

@@ -190,6 +190,68 @@ Please note that these files are internal to CMake and you should not call
 :command:`configure_file()` on them yourself, but they can be used as starting
 point to create more sophisticated custom ``ConfigVersion.cmake`` files.
 
+Generating an Apple Platform Selection File
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. versionadded:: 3.29
+
+.. command:: generate_apple_platform_selection_file
+
+ Create an Apple platform selection file:
+
+   generate_apple_platform_selection_file(<filename>
+     INSTALL_DESTINATION <path>
+     [MACOS_CONFIG_FILE <file>]
+     [IOS_CONFIG_FILE <file>]
+     [IOS_SIMULATOR_CONFIG_FILE <file>]
+     [TVOS_CONFIG_FILE <file>]
+     [TVOS_SIMULATOR_CONFIG_FILE <file>]
+     [WATCHOS_CONFIG_FILE <file>]
+     [WATCHOS_SIMULATOR_CONFIG_FILE <file>]
+     [VISIONOS_CONFIG_FILE <file>]
+     [VISIONOS_SIMULATOR_CONFIG_FILE <file>]
+     )
+
+Writes a file for use as ``<PackageName>Config.cmake`` which can include an
+Apple-platform-specific ``<PackageName>Config.cmake`` from a different
+directory. This can be used in conjunction with the ``XCFRAMEWORK_LOCATION``
+argument of :command:`export(SETUP)` to export packages in a way that a project
+built for any Apple platform can use them.
+
+``INSTALL_DESTINATION <path>``
+  Path that the file will be installed to.
+
+``MACOS_CONFIG_FILE <file>``
+  File to include if the platform is macOS.
+
+``IOS_CONFIG_FILE <file>``
+  File to include if the platform is iOS.
+
+``IOS_SIMULATOR_CONFIG_FILE <file>``
+  File to include if the platform is iOS Simulator.
+
+``TVOS_CONFIG_FILE <file>``
+  File to include if the platform is tvOS.
+
+``TVOS_SIMULATOR_CONFIG_FILE <file>``
+  File to include if the platform is tvOS Simulator.
+
+``WATCHOS_CONFIG_FILE <file>``
+  File to include if the platform is watchOS.
+
+``WATCHOS_SIMULATOR_CONFIG_FILE <file>``
+  File to include if the platform is watchOS Simulator.
+
+``VISIONOS_CONFIG_FILE <file>``
+  File to include if the platform is visionOS.
+
+``VISIONOS_SIMULATOR_CONFIG_FILE <file>``
+  File to include if the platform is visionOS Simulator.
+
+If any of the optional config files are not specified, and the consuming
+project is built for their corresponding platform, an error will be thrown
+when including the generated file.
+
 Example Generating Package Files
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -344,3 +406,45 @@ endmacro()
   configure_file("${_inputFile}" "${_outputFile}" @ONLY)
 
 endfunction()
+
+function(generate_apple_platform_selection_file _output_file)
+  set(_config_file_options
+    MACOS_CONFIG_FILE
+    IOS_CONFIG_FILE
+    IOS_SIMULATOR_CONFIG_FILE
+    TVOS_CONFIG_FILE
+    TVOS_SIMULATOR_CONFIG_FILE
+    WATCHOS_CONFIG_FILE
+    WATCHOS_SIMULATOR_CONFIG_FILE
+    VISIONOS_CONFIG_FILE
+    VISIONOS_SIMULATOR_CONFIG_FILE
+    )
+
+  set(_options)
+  set(_single
+    INSTALL_DESTINATION
+    ${_config_file_options}
+    )
+  set(_multi)
+  cmake_parse_arguments(PARSE_ARGV 0 _gpsf "${_options}" "${_single}" "${_multi}")
+
+  set(_have_relative 0)
+  foreach(_opt IN LISTS _config_file_options)
+    if(_gpsf_${_opt})
+      set(_config_file "${_gpsf_${_opt}}")
+      if(NOT IS_ABSOLUTE "${_config_file}")
+        string(PREPEND _config_file [[${PACKAGE_PREFIX_DIR}/]])
+        set(_have_relative 1)
+      endif()
+      set(_branch_${_opt} "include(\"${_config_file}\")")
+    else()
+      set(_branch_${_opt} "message(FATAL_ERROR \"Platform not supported\")")
+    endif()
+  endforeach()
+
+  configure_package_config_file("${CMAKE_CURRENT_FUNCTION_LIST_DIR}/PlatformSelectionFile.cmake.in" "${_output_file}"
+    INSTALL_DESTINATION "${_gpsf_INSTALL_DESTINATION}"
+    NO_SET_AND_CHECK_MACRO
+    NO_CHECK_REQUIRED_COMPONENTS_MACRO
+    )
+endfunction()

Modules/PlatformSelectionFile.cmake.in

@@ -0,0 +1,24 @@
+@PACKAGE_INIT@
+
+string(TOLOWER "${CMAKE_OSX_SYSROOT}" _CMAKE_OSX_SYSROOT_LOWER)
+if(_CMAKE_OSX_SYSROOT_LOWER MATCHES "(^|/)iphonesimulator")
+  @_branch_IOS_SIMULATOR_CONFIG_FILE@
+elseif(_CMAKE_OSX_SYSROOT_LOWER MATCHES "(^|/)iphoneos")
+  @_branch_IOS_CONFIG_FILE@
+elseif(_CMAKE_OSX_SYSROOT_LOWER MATCHES "(^|/)tvsimulator")
+  @_branch_TVOS_SIMULATOR_CONFIG_FILE@
+elseif(_CMAKE_OSX_SYSROOT_LOWER MATCHES "(^|/)tvos")
+  @_branch_TVOS_CONFIG_FILE@
+elseif(_CMAKE_OSX_SYSROOT_LOWER MATCHES "(^|/)watchsimulator")
+  @_branch_WATCHOS_SIMULATOR_CONFIG_FILE@
+elseif(_CMAKE_OSX_SYSROOT_LOWER MATCHES "(^|/)watchos")
+  @_branch_WATCHOS_CONFIG_FILE@
+elseif(_CMAKE_OSX_SYSROOT_LOWER MATCHES "(^|/)xrsimulator")
+  @_branch_VISIONOS_SIMULATOR_CONFIG_FILE@
+elseif(_CMAKE_OSX_SYSROOT_LOWER MATCHES "(^|/)xros")
+  @_branch_VISIONOS_CONFIG_FILE@
+elseif(CMAKE_SYSTEM_NAME STREQUAL "Darwin")
+  @_branch_MACOS_CONFIG_FILE@
+else()
+  message(FATAL_ERROR "Platform not supported")
+endif()

Tests/RunCMake/XcFramework/RunCMakeTest.cmake

@@ -222,3 +222,25 @@ endif()
 run_cmake_command(import-macos-build-specific-genex-build ${CMAKE_COMMAND} --build . ${_config_arg})
 unset(RunCMake_TEST_NO_CLEAN)
 unset(RunCMake_TEST_BINARY_DIR)
+
+set(RunCMake_TEST_BINARY_DIR ${RunCMake_BINARY_DIR}/import-macos-install-general-build)
+run_cmake_with_options(import-macos-install-general -DCMAKE_SYSTEM_NAME=Darwin -Dmylib_DIR=${RunCMake_BINARY_DIR}/export-install/lib/cmake/mylib)
+set(RunCMake_TEST_NO_CLEAN 1)
+set(_config_arg)
+if(RunCMake_GENERATOR_IS_MULTI_CONFIG)
+  set(_config_arg --config Release)
+endif()
+run_cmake_command(import-macos-install-general-build ${CMAKE_COMMAND} --build . ${_config_arg})
+unset(RunCMake_TEST_NO_CLEAN)
+unset(RunCMake_TEST_BINARY_DIR)
+
+set(RunCMake_TEST_BINARY_DIR ${RunCMake_BINARY_DIR}/import-macos-build-general-build)
+run_cmake_with_options(import-macos-build-general -DCMAKE_SYSTEM_NAME=Darwin -Dmylib_DIR=${RunCMake_BINARY_DIR}/export-macos-build/lib/cmake/mylib)
+set(RunCMake_TEST_NO_CLEAN 1)
+set(_config_arg)
+if(RunCMake_GENERATOR_IS_MULTI_CONFIG)
+  set(_config_arg --config Release)
+endif()
+run_cmake_command(import-macos-build-general-build ${CMAKE_COMMAND} --build . ${_config_arg})
+unset(RunCMake_TEST_NO_CLEAN)
+unset(RunCMake_TEST_BINARY_DIR)

Tests/RunCMake/XcFramework/export-macos.cmake

@@ -31,3 +31,14 @@ configure_package_config_file(mylib-config.cmake.in mylib-config-sub.cmake INSTA
 install(FILES ${CMAKE_CURRENT_BINARY_DIR}/mylib-config-sub.cmake DESTINATION lib/macos/cmake/mylib RENAME mylib-config.cmake)
 
 configure_package_config_file(mylib-config.cmake.in lib/macos/cmake/mylib/mylib-config.cmake INSTALL_DESTINATION lib/macos/cmake/mylib)
+
+generate_apple_platform_selection_file(mylib-config-top.cmake
+  INSTALL_DESTINATION lib/cmake/mylib
+  MACOS_CONFIG_FILE lib/macos/cmake/mylib/mylib-config.cmake
+  )
+install(FILES ${CMAKE_CURRENT_BINARY_DIR}/mylib-config-top.cmake DESTINATION lib/cmake/mylib RENAME mylib-config.cmake)
+
+generate_apple_platform_selection_file(lib/cmake/mylib/mylib-config.cmake
+  INSTALL_DESTINATION lib/cmake/mylib
+  MACOS_CONFIG_FILE lib/macos/cmake/mylib/mylib-config.cmake
+  )

Tests/RunCMake/XcFramework/import-macos-build-general-build-stdout.txt

@@ -0,0 +1,2 @@
+mylib location: [^
+]*/Tests/RunCMake/XcFramework/export-macos-build/lib/mylib\.xcframework/macos-(arm64|x86_64|arm64_x86_64)/libmylib\.a

Tests/RunCMake/XcFramework/import-macos-build-general.cmake

@@ -0,0 +1 @@
+include(import-common.cmake)

Tests/RunCMake/XcFramework/import-macos-install-general-build-stdout.txt

@@ -0,0 +1,2 @@
+mylib location: [^
+]*/Tests/RunCMake/XcFramework/export-install/lib/mylib\.xcframework/macos-(arm64|x86_64|arm64_x86_64)/libmylib\.a

Tests/RunCMake/XcFramework/import-macos-install-general.cmake

@@ -0,0 +1 @@
+include(import-common.cmake)