🔧 improve QDMI installation setup and header management (#228)

## Description

This pull request refactors the CMake build and installation setup for
the `qdmi` library to improve header file management, installation
consistency, and package configuration. The changes modernize how
headers are handled, align installation paths and components, and ensure
that all necessary CMake scripts are installed and loaded with the
package.

Header management improvements:
* Switched from manually setting include directories to using
`target_sources` with a `FILE_SET` for headers, ensuring more robust and
modern header management for the `qdmi` target.

Installation and packaging enhancements:
* Refactored installation instructions to use project-specific runtime
and development components, aligned header installation with library and
archive installation using `FILE_SET`, and set a consistent config
install directory (`QDMI_CONFIG_INSTALL_DIR`).
* Updated package configuration to install and load additional CMake
scripts (`Cache.cmake`, `PrefixHandling.cmake`) needed for consumers,
and ensured these are included in the installed package config file.
* Changed the compatibility mode for the package version file from
`SameMajorVersion` to `SameMinorVersion` for more precise version
matching.

## Checklist:

<!---
This checklist serves as a reminder of a couple of things that ensure
your pull request will be merged swiftly.
-->

- [x] The pull request only contains commits that are focused and
relevant to this change.
- [x] I have added appropriate tests that cover the new/changed
functionality.
- [x] I have updated the documentation to reflect these changes.
- [ ] I have added entries to the changelog for any noteworthy
additions, changes, fixes, or
      removals.
- [x] I have added migration instructions to the upgrade guide (if
needed).
- [x] The changes follow the project's style guidelines and introduce no
new warnings.
- [x] The changes are fully tested and pass the CI checks.
- [x] I have reviewed my own code changes.

---------

Signed-off-by: burgholzer <burgholzer@me.com>

Author: burgholzer

CHANGELOG.md

@@ -31,6 +31,7 @@ clients compiled against a different minor or major version.
 
 ### Changed
 
+- 🔧 Improve library installation setup and header management ([#228]) ([\@burgholzer])
 - 🔧 Set c++ standard target based ([#165]) ([\@ystade])
 - **Breaking**: 🚸 Change order of `QDMI_SESSION_PARAMETER` and `QDMI_DEVICE_SESSION` enum values
   due to new authentication options ([#160]) ([\@ystade], [\@burgholzer])
@@ -61,6 +62,7 @@ changelogs._
 
 <!-- PR links -->
 
+[#228]: https://github.com/Munich-Quantum-Software-Stack/QDMI/pull/228
 [#214]: https://github.com/Munich-Quantum-Software-Stack/QDMI/pull/214
 [#211]: https://github.com/Munich-Quantum-Software-Stack/QDMI/pull/211
 [#210]: https://github.com/Munich-Quantum-Software-Stack/QDMI/pull/210

CMakeLists.txt

@@ -117,10 +117,12 @@ if(NOT TARGET qdmi::qdmi)
   # add main library code
   add_library(qdmi INTERFACE)
 
-  # set include directories
-  target_include_directories(
-    qdmi INTERFACE $<BUILD_INTERFACE:${QDMI_INCLUDE_BUILD_DIR}>
-                   $<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}>)
+  # collect header files
+  file(GLOB_RECURSE QDMI_HEADERS ${QDMI_INCLUDE_BUILD_DIR}/qdmi/*.h)
+
+  # add headers using file sets
+  target_sources(qdmi PUBLIC FILE_SET HEADERS BASE_DIRS
+                             ${QDMI_INCLUDE_BUILD_DIR} FILES ${QDMI_HEADERS})
 
   # set required C standard
   target_compile_features(qdmi INTERFACE c_std_11)
@@ -174,35 +176,52 @@ endif()
 
 # Installation instructions for the main library
 if(QDMI_INSTALL)
-  install(
-    TARGETS qdmi qdmi_project_warnings
-    EXPORT ${PROJECT_NAME}-targets
-    ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR} COMPONENT Development
-    LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
-            COMPONENT Runtime
-            NAMELINK_COMPONENT Development
-    RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR} COMPONENT Runtime
-    PUBLIC_HEADER DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/${PROJECT_NAME})
+  set(QDMI_CONFIG_INSTALL_DIR
+      "${CMAKE_INSTALL_DATADIR}/cmake/${PROJECT_NAME}"
+      CACHE INTERNAL "Config install directory")
 
   include(CMakePackageConfigHelpers)
-  write_basic_package_version_file(
-    "${PROJECT_NAME}-config-version.cmake"
-    VERSION ${PROJECT_VERSION}
-    COMPATIBILITY SameMajorVersion)
   configure_package_config_file(
     "${PROJECT_SOURCE_DIR}/cmake/${PROJECT_NAME}-config.cmake.in"
     "${PROJECT_BINARY_DIR}/${PROJECT_NAME}-config.cmake"
-    INSTALL_DESTINATION ${CMAKE_INSTALL_DATAROOTDIR}/${PROJECT_NAME}/cmake)
+    INSTALL_DESTINATION ${QDMI_CONFIG_INSTALL_DIR}
+    NO_SET_AND_CHECK_MACRO NO_CHECK_REQUIRED_COMPONENTS_MACRO)
+  write_basic_package_version_file(
+    "${PROJECT_NAME}-config-version.cmake"
+    VERSION ${PROJECT_VERSION}
+    COMPATIBILITY SameMinorVersion)
+
+  install(FILES "${PROJECT_BINARY_DIR}/${PROJECT_NAME}-config.cmake"
+                "${PROJECT_BINARY_DIR}/${PROJECT_NAME}-config-version.cmake"
+          DESTINATION ${QDMI_CONFIG_INSTALL_DIR})
+
+  # FILE_SET should be aligned with LIBRARY and ARCHIVE, so we turn cmake-format
+  # off
+  # cmake-format: off
+  install(
+    TARGETS qdmi qdmi_project_warnings
+    EXPORT ${PROJECT_NAME}-targets
+    RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR} COMPONENT ${PROJECT_NAME}_Runtime
+    LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
+            COMPONENT ${PROJECT_NAME}_Runtime
+            NAMELINK_COMPONENT ${PROJECT_NAME}_Development
+    ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR} COMPONENT ${PROJECT_NAME}_Development
+    FILE_SET HEADERS
+             DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/${PROJECT_NAME}
+             COMPONENT ${PROJECT_NAME}_Development)
+  # cmake-format: on
 
   install(
     EXPORT ${PROJECT_NAME}-targets
     FILE ${PROJECT_NAME}-targets.cmake
     NAMESPACE ${PROJECT_NAME}::
-    DESTINATION ${CMAKE_INSTALL_DATAROOTDIR}/${PROJECT_NAME}/cmake)
+    DESTINATION ${QDMI_CONFIG_INSTALL_DIR}
+    COMPONENT ${PROJECT_NAME}_Development)
 
-  install(FILES "${PROJECT_BINARY_DIR}/${PROJECT_NAME}-config.cmake"
-                "${PROJECT_BINARY_DIR}/${PROJECT_NAME}-config-version.cmake"
-          DESTINATION ${CMAKE_INSTALL_DATAROOTDIR}/${PROJECT_NAME}/cmake)
-
-  install(DIRECTORY ${PROJECT_SOURCE_DIR}/include/qdmi DESTINATION include)
+  install(
+    FILES ${PROJECT_SOURCE_DIR}/cmake/Cache.cmake
+          ${PROJECT_SOURCE_DIR}/cmake/prefix_defs.txt
+          ${PROJECT_SOURCE_DIR}/cmake/PrefixHandling.cmake
+    DESTINATION ${QDMI_CONFIG_INSTALL_DIR}
+    COMPONENT ${PROJECT_NAME}_Development)
 endif()

cmake/qdmi-config.cmake.in

@@ -26,6 +26,8 @@ if(TARGET qdmi::qdmi)
   return()
 endif()
 
+include("${CMAKE_CURRENT_LIST_DIR}/Cache.cmake")
+include("${CMAKE_CURRENT_LIST_DIR}/PrefixHandling.cmake")
 include("${CMAKE_CURRENT_LIST_DIR}/qdmi-targets.cmake")
 
 if(NOT qdmi_FIND_QUIETLY)