From 91f83c3b728551f0b336acbda00de0b05848ef60 Mon Sep 17 00:00:00 2001 From: Lukas Burgholzer Date: Mon, 27 Jul 2026 15:33:27 +0200 Subject: [PATCH 1/2] =?UTF-8?q?=E2=9C=A8=20Export=20QDMI=20device=20target?= =?UTF-8?q?=20metadata?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add a QDMI-owned CMake helper for publishing stable device IDs and symbol prefixes on exported device targets. Use it in the C++ example and generated device projects so consumers can integrate them without project-specific loader metadata. Assisted-by: GPT-5.6-sol via Codex --- cmake/GenerateTemplate.cmake | 2 ++ cmake/PrefixHandling.cmake | 24 ++++++++++++++++++++++++ docs/templates.md | 12 ++++++++++++ examples/device/CMakeLists.txt | 14 ++++++++++++++ examples/device/README.md | 6 ++++++ examples/device/src/CMakeLists.txt | 2 ++ templates/device/CMakeLists.txt | 14 ++++++++++++++ templates/device/README.md | 6 ++++++ templates/device/src/CMakeLists.txt | 2 ++ 9 files changed, 82 insertions(+) diff --git a/cmake/GenerateTemplate.cmake b/cmake/GenerateTemplate.cmake index a60216af..42a21fa4 100644 --- a/cmake/GenerateTemplate.cmake +++ b/cmake/GenerateTemplate.cmake @@ -175,6 +175,8 @@ foreach(_src IN LISTS _files) "${_content}") string(REPLACE "my.qdmi" "${QDMI_TEMPLATE_prefix}.qdmi" _content "${_content}") + string(REPLACE "my.default" "${QDMI_TEMPLATE_prefix}.default" _content + "${_content}") string(REPLACE "\"my\"" "\"${QDMI_TEMPLATE_PREFIX}\"" _content "${_content}") string(REPLACE "--namespace-pkg my" "--namespace-pkg ${QDMI_TEMPLATE_prefix}" _content "${_content}") diff --git a/cmake/PrefixHandling.cmake b/cmake/PrefixHandling.cmake index 2b1f9239..096d45f8 100644 --- a/cmake/PrefixHandling.cmake +++ b/cmake/PrefixHandling.cmake @@ -74,6 +74,30 @@ function(generate_prefixed_qdmi_headers prefix) endforeach() endfunction() +# Publish the metadata that build-system consumers need to identify a QDMI +# device target. +function(configure_qdmi_device_target) + cmake_parse_arguments(ARG "" "TARGET;ID;PREFIX" "" ${ARGN}) + foreach(required_argument IN ITEMS TARGET ID PREFIX) + if(NOT ARG_${required_argument}) + message( + FATAL_ERROR + "configure_qdmi_device_target requires TARGET, ID, and PREFIX") + endif() + endforeach() + if(NOT TARGET ${ARG_TARGET}) + message(FATAL_ERROR "Unknown QDMI device target: ${ARG_TARGET}") + endif() + + set_target_properties( + ${ARG_TARGET} PROPERTIES QDMI_DEVICE_ID "${ARG_ID}" QDMI_DEVICE_PREFIX + "${ARG_PREFIX}") + set_property( + TARGET ${ARG_TARGET} + APPEND + PROPERTY EXPORT_PROPERTIES QDMI_DEVICE_ID QDMI_DEVICE_PREFIX) +endfunction() + # A function for generating test executables that check if all functions are # implemented by a device. # diff --git a/docs/templates.md b/docs/templates.md index e1151081..5fa5c376 100644 --- a/docs/templates.md +++ b/docs/templates.md @@ -55,6 +55,18 @@ that. To this end, adjust the `QDMI_REV` variable in + set(QDMI_REV "v1.2.0" ``` +The generated project assigns the stable ID `prefix.default` to its device. +Change the project-specific `PREFIX_QDMI_DEVICE_ID` CMake cache variable if the +device needs a different ID. Once selected and distributed, keep this ID stable +so that applications and configuration files can continue to refer to the same +device. + +The device target calls `configure_qdmi_device_target` to export its stable ID +and symbol prefix as the `QDMI_DEVICE_ID` and `QDMI_DEVICE_PREFIX` target +properties. Build-system consumers such as MQT Core can use this metadata to +package and register the device without project-specific loader code or a +runtime dependency from the device implementation to that consumer. + When you want to change the prefix after the creation of the template, you need to change the prefix in a couple of places. We want to give you some hints where you have to change it, but depending on your personal project setup, they might diff --git a/examples/device/CMakeLists.txt b/examples/device/CMakeLists.txt index ccb022cd..c5c9a968 100644 --- a/examples/device/CMakeLists.txt +++ b/examples/device/CMakeLists.txt @@ -51,6 +51,9 @@ set(CMAKE_VERIFY_INTERFACE_HEADER_SETS CACHE BOOL "Verify interface header sets" FORCE) set(QDMI_PREFIX "CXX") +set(CXX_QDMI_DEVICE_ID + "cxx.default" + CACHE STRING "Stable identifier for the CXX QDMI Device") cmake_dependent_option( INSTALL_CXX_QDMI_DEVICE @@ -78,6 +81,17 @@ endif() # Add the tests if(BUILD_CXX_QDMI_TESTS) + get_target_property(EXPORTED_QDMI_DEVICE_ID ${QDMI_TARGET_NAME} + QDMI_DEVICE_ID) + get_target_property(EXPORTED_QDMI_DEVICE_PREFIX ${QDMI_TARGET_NAME} + QDMI_DEVICE_PREFIX) + if(NOT EXPORTED_QDMI_DEVICE_ID STREQUAL "${CXX_QDMI_DEVICE_ID}") + message(FATAL_ERROR "The CXX QDMI target does not export its stable ID") + endif() + if(NOT EXPORTED_QDMI_DEVICE_PREFIX STREQUAL "${QDMI_PREFIX}") + message(FATAL_ERROR "The CXX QDMI target does not export its symbol prefix") + endif() + enable_testing() include(GoogleTest) add_subdirectory(test) diff --git a/examples/device/README.md b/examples/device/README.md index 844e108a..fd20ebab 100644 --- a/examples/device/README.md +++ b/examples/device/README.md @@ -11,6 +11,12 @@ A C++20 library that implements the QDMI Device interface. +The exported CMake target publishes the stable device ID configured through +`CXX_QDMI_DEVICE_ID` and the QDMI symbol prefix through +`configure_qdmi_device_target`. Consumers such as MQT Core can use this metadata +to package and register the device without project-specific loader code. This +metadata does not add MQT Core as a dependency. + ## Documentation The full documentation, including a user guide, development guide, and the C++ diff --git a/examples/device/src/CMakeLists.txt b/examples/device/src/CMakeLists.txt index 8e30110a..78c4b232 100644 --- a/examples/device/src/CMakeLists.txt +++ b/examples/device/src/CMakeLists.txt @@ -37,6 +37,8 @@ set_target_properties( PROPERTIES C_VISIBILITY_PRESET hidden CXX_VISIBILITY_PRESET hidden VISIBILITY_INLINES_HIDDEN 1) +configure_qdmi_device_target(TARGET ${QDMI_TARGET_NAME} ID + ${CXX_QDMI_DEVICE_ID} PREFIX ${QDMI_PREFIX}) target_sources(${QDMI_TARGET_NAME} PRIVATE ${SRC_FILES}) target_sources( diff --git a/templates/device/CMakeLists.txt b/templates/device/CMakeLists.txt index 1096810a..948a6a99 100644 --- a/templates/device/CMakeLists.txt +++ b/templates/device/CMakeLists.txt @@ -51,6 +51,9 @@ set(CMAKE_VERIFY_INTERFACE_HEADER_SETS CACHE BOOL "Verify interface header sets" FORCE) set(QDMI_PREFIX "MY") +set(MY_QDMI_DEVICE_ID + "my.default" + CACHE STRING "Stable identifier for the MY QDMI Device") cmake_dependent_option( INSTALL_MY_QDMI_DEVICE @@ -78,6 +81,17 @@ endif() # Add the tests if(BUILD_MY_QDMI_TESTS) + get_target_property(EXPORTED_QDMI_DEVICE_ID ${QDMI_TARGET_NAME} + QDMI_DEVICE_ID) + get_target_property(EXPORTED_QDMI_DEVICE_PREFIX ${QDMI_TARGET_NAME} + QDMI_DEVICE_PREFIX) + if(NOT EXPORTED_QDMI_DEVICE_ID STREQUAL "${MY_QDMI_DEVICE_ID}") + message(FATAL_ERROR "The MY QDMI target does not export its stable ID") + endif() + if(NOT EXPORTED_QDMI_DEVICE_PREFIX STREQUAL "${QDMI_PREFIX}") + message(FATAL_ERROR "The MY QDMI target does not export its symbol prefix") + endif() + enable_testing() include(GoogleTest) add_subdirectory(test) diff --git a/templates/device/README.md b/templates/device/README.md index d23bc104..b078852e 100644 --- a/templates/device/README.md +++ b/templates/device/README.md @@ -15,6 +15,12 @@ A C++20 library that implements the QDMI Device interface. +The exported CMake target publishes the stable device ID configured through +`MY_QDMI_DEVICE_ID` and the QDMI symbol prefix through +`configure_qdmi_device_target`. Consumers such as MQT Core can use this metadata +to package and register the device without project-specific loader code. This +metadata does not add MQT Core as a dependency. + ## Documentation The full documentation, including project guides, a contributing guide, and the diff --git a/templates/device/src/CMakeLists.txt b/templates/device/src/CMakeLists.txt index df970628..6d2c8528 100644 --- a/templates/device/src/CMakeLists.txt +++ b/templates/device/src/CMakeLists.txt @@ -41,6 +41,8 @@ set_target_properties( PROPERTIES C_VISIBILITY_PRESET hidden CXX_VISIBILITY_PRESET hidden VISIBILITY_INLINES_HIDDEN 1) +configure_qdmi_device_target(TARGET ${QDMI_TARGET_NAME} ID ${MY_QDMI_DEVICE_ID} + PREFIX ${QDMI_PREFIX}) target_sources(${QDMI_TARGET_NAME} PRIVATE ${SRC_FILES}) target_sources( From f198f5a22b6d345f392dc4c88b40cd33d0cc3d41 Mon Sep 17 00:00:00 2001 From: Lukas Burgholzer Date: Mon, 27 Jul 2026 15:35:20 +0200 Subject: [PATCH 2/2] =?UTF-8?q?=F0=9F=93=9D=20Add=20QDMI=20target=20metada?= =?UTF-8?q?ta=20changelog=20entry?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Record the user-facing template and example integration with PR and author attribution. Assisted-by: GPT-5.6-sol via Codex --- CHANGELOG.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 1a418675..ca908690 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,6 +12,11 @@ clients compiled against a different minor or major version. ## [Unreleased] +### Added + +- 👨‍💻 Add stable device IDs and symbol-prefix metadata to exported device targets + and generated projects ([#475]) ([\@burgholzer]) + ## [1.3.2] - 2026-07-08 ### Added @@ -204,6 +209,7 @@ for previous changelogs._ +[#475]: https://github.com/Munich-Quantum-Software-Stack/QDMI/pull/475 [#457]: https://github.com/Munich-Quantum-Software-Stack/QDMI/pull/457 [#456]: https://github.com/Munich-Quantum-Software-Stack/QDMI/pull/456 [#426]: https://github.com/Munich-Quantum-Software-Stack/QDMI/pull/426