Munich-Quantum-Software-Stack · burgholzer · Jul 29, 2026 · Jul 27, 2026 · Jul 27, 2026
diff --git 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._
 
 <!-- PR links -->
 
+[#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

diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -15,6 +15,12 @@ A C++20 library that implements the QDMI Device interface.
 
 <!-- [DOXYGEN MAIN] -->
 
+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
@@ -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(