Skip to content

Commit b94be74

Browse files
burgholzerburgholzer
authored
✨ Export stable metadata from QDMI device targets (#475)
🤖 *AI text below* 🤖 ## Description Add the QDMI-owned `configure_qdmi_device_target` CMake helper for publishing a device target's stable ID and symbol prefix through the neutral `QDMI_DEVICE_ID` and `QDMI_DEVICE_PREFIX` target properties. The properties are preserved when the target is exported and installed. Update the C++ example and generated device template to use the helper. Newly generated projects receive an overridable `<PREFIX>_QDMI_DEVICE_ID` with the default `<lowercase-prefix>.default`, and document why that identifier should remain stable. This is the QDMI side of [MQT Core #1912](munich-quantum-toolkit/core#1912), which is the first consumer of this metadata. Device implementations do not gain a build-time or runtime dependency on MQT Core. ## Checklist - [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. - [x] 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. **If PR contains AI-assisted content:** - [x] I have disclosed the use of AI tools in the PR description as per our [AI Usage Guidelines](https://munich-quantum-software-stack.github.io/QDMI/latest/md_docs_2ai__usage.html). - [x] AI-assisted commits include an `Assisted-by: [Model Name] via [Tool Name]` footer. - [x] I confirm that I have personally reviewed and understood all AI-generated content, and accept full responsibility for it.
1 parent f07a319 commit b94be74

10 files changed

Lines changed: 88 additions & 0 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,11 @@ clients compiled against a different minor or major version.
1212

1313
## [Unreleased]
1414

15+
### Added
16+
17+
- 👨‍💻 Add stable device IDs and symbol-prefix metadata to exported device targets
18+
and generated projects ([#475]) ([\@burgholzer])
19+
1520
## [1.3.2] - 2026-07-08
1621

1722
### Added
@@ -204,6 +209,7 @@ for previous changelogs._
204209

205210
<!-- PR links -->
206211

212+
[#475]: https://github.com/Munich-Quantum-Software-Stack/QDMI/pull/475
207213
[#457]: https://github.com/Munich-Quantum-Software-Stack/QDMI/pull/457
208214
[#456]: https://github.com/Munich-Quantum-Software-Stack/QDMI/pull/456
209215
[#426]: https://github.com/Munich-Quantum-Software-Stack/QDMI/pull/426

‎cmake/GenerateTemplate.cmake‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -175,6 +175,8 @@ foreach(_src IN LISTS _files)
175175
"${_content}")
176176
string(REPLACE "my.qdmi" "${QDMI_TEMPLATE_prefix}.qdmi" _content
177177
"${_content}")
178+
string(REPLACE "my.default" "${QDMI_TEMPLATE_prefix}.default" _content
179+
"${_content}")
178180
string(REPLACE "\"my\"" "\"${QDMI_TEMPLATE_PREFIX}\"" _content "${_content}")
179181
string(REPLACE "--namespace-pkg my" "--namespace-pkg ${QDMI_TEMPLATE_prefix}"
180182
_content "${_content}")

‎cmake/PrefixHandling.cmake‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -74,6 +74,30 @@ function(generate_prefixed_qdmi_headers prefix)
7474
endforeach()
7575
endfunction()
7676

77+
# Publish the metadata that build-system consumers need to identify a QDMI
78+
# device target.
79+
function(configure_qdmi_device_target)
80+
cmake_parse_arguments(ARG "" "TARGET;ID;PREFIX" "" ${ARGN})
81+
foreach(required_argument IN ITEMS TARGET ID PREFIX)
82+
if(NOT ARG_${required_argument})
83+
message(
84+
FATAL_ERROR
85+
"configure_qdmi_device_target requires TARGET, ID, and PREFIX")
86+
endif()
87+
endforeach()
88+
if(NOT TARGET ${ARG_TARGET})
89+
message(FATAL_ERROR "Unknown QDMI device target: ${ARG_TARGET}")
90+
endif()
91+
92+
set_target_properties(
93+
${ARG_TARGET} PROPERTIES QDMI_DEVICE_ID "${ARG_ID}" QDMI_DEVICE_PREFIX
94+
"${ARG_PREFIX}")
95+
set_property(
96+
TARGET ${ARG_TARGET}
97+
APPEND
98+
PROPERTY EXPORT_PROPERTIES QDMI_DEVICE_ID QDMI_DEVICE_PREFIX)
99+
endfunction()
100+
77101
# A function for generating test executables that check if all functions are
78102
# implemented by a device.
79103
#

‎docs/templates.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -55,6 +55,18 @@ that. To this end, adjust the `QDMI_REV` variable in
5555
+ set(QDMI_REV "v1.2.0"
5656
```
5757

58+
The generated project assigns the stable ID `prefix.default` to its device.
59+
Change the project-specific `PREFIX_QDMI_DEVICE_ID` CMake cache variable if the
60+
device needs a different ID. Once selected and distributed, keep this ID stable
61+
so that applications and configuration files can continue to refer to the same
62+
device.
63+
64+
The device target calls `configure_qdmi_device_target` to export its stable ID
65+
and symbol prefix as the `QDMI_DEVICE_ID` and `QDMI_DEVICE_PREFIX` target
66+
properties. Build-system consumers such as MQT Core can use this metadata to
67+
package and register the device without project-specific loader code or a
68+
runtime dependency from the device implementation to that consumer.
69+
5870
When you want to change the prefix after the creation of the template, you need
5971
to change the prefix in a couple of places. We want to give you some hints where
6072
you have to change it, but depending on your personal project setup, they might

‎examples/device/CMakeLists.txt‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,9 @@ set(CMAKE_VERIFY_INTERFACE_HEADER_SETS
5151
CACHE BOOL "Verify interface header sets" FORCE)
5252

5353
set(QDMI_PREFIX "CXX")
54+
set(CXX_QDMI_DEVICE_ID
55+
"cxx.default"
56+
CACHE STRING "Stable identifier for the CXX QDMI Device")
5457

5558
cmake_dependent_option(
5659
INSTALL_CXX_QDMI_DEVICE
@@ -78,6 +81,17 @@ endif()
7881

7982
# Add the tests
8083
if(BUILD_CXX_QDMI_TESTS)
84+
get_target_property(EXPORTED_QDMI_DEVICE_ID ${QDMI_TARGET_NAME}
85+
QDMI_DEVICE_ID)
86+
get_target_property(EXPORTED_QDMI_DEVICE_PREFIX ${QDMI_TARGET_NAME}
87+
QDMI_DEVICE_PREFIX)
88+
if(NOT EXPORTED_QDMI_DEVICE_ID STREQUAL "${CXX_QDMI_DEVICE_ID}")
89+
message(FATAL_ERROR "The CXX QDMI target does not export its stable ID")
90+
endif()
91+
if(NOT EXPORTED_QDMI_DEVICE_PREFIX STREQUAL "${QDMI_PREFIX}")
92+
message(FATAL_ERROR "The CXX QDMI target does not export its symbol prefix")
93+
endif()
94+
8195
enable_testing()
8296
include(GoogleTest)
8397
add_subdirectory(test)

‎examples/device/README.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,12 @@
1111

1212
A C++20 library that implements the QDMI Device interface.
1313

14+
The exported CMake target publishes the stable device ID configured through
15+
`CXX_QDMI_DEVICE_ID` and the QDMI symbol prefix through
16+
`configure_qdmi_device_target`. Consumers such as MQT Core can use this metadata
17+
to package and register the device without project-specific loader code. This
18+
metadata does not add MQT Core as a dependency.
19+
1420
## Documentation
1521

1622
The full documentation, including a user guide, development guide, and the C++

‎examples/device/src/CMakeLists.txt‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,8 @@ set_target_properties(
3737
PROPERTIES C_VISIBILITY_PRESET hidden
3838
CXX_VISIBILITY_PRESET hidden
3939
VISIBILITY_INLINES_HIDDEN 1)
40+
configure_qdmi_device_target(TARGET ${QDMI_TARGET_NAME} ID
41+
${CXX_QDMI_DEVICE_ID} PREFIX ${QDMI_PREFIX})
4042
target_sources(${QDMI_TARGET_NAME} PRIVATE ${SRC_FILES})
4143

4244
target_sources(

‎templates/device/CMakeLists.txt‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,9 @@ set(CMAKE_VERIFY_INTERFACE_HEADER_SETS
5151
CACHE BOOL "Verify interface header sets" FORCE)
5252

5353
set(QDMI_PREFIX "MY")
54+
set(MY_QDMI_DEVICE_ID
55+
"my.default"
56+
CACHE STRING "Stable identifier for the MY QDMI Device")
5457

5558
cmake_dependent_option(
5659
INSTALL_MY_QDMI_DEVICE
@@ -78,6 +81,17 @@ endif()
7881

7982
# Add the tests
8083
if(BUILD_MY_QDMI_TESTS)
84+
get_target_property(EXPORTED_QDMI_DEVICE_ID ${QDMI_TARGET_NAME}
85+
QDMI_DEVICE_ID)
86+
get_target_property(EXPORTED_QDMI_DEVICE_PREFIX ${QDMI_TARGET_NAME}
87+
QDMI_DEVICE_PREFIX)
88+
if(NOT EXPORTED_QDMI_DEVICE_ID STREQUAL "${MY_QDMI_DEVICE_ID}")
89+
message(FATAL_ERROR "The MY QDMI target does not export its stable ID")
90+
endif()
91+
if(NOT EXPORTED_QDMI_DEVICE_PREFIX STREQUAL "${QDMI_PREFIX}")
92+
message(FATAL_ERROR "The MY QDMI target does not export its symbol prefix")
93+
endif()
94+
8195
enable_testing()
8296
include(GoogleTest)
8397
add_subdirectory(test)

‎templates/device/README.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,12 @@ A C++20 library that implements the QDMI Device interface.
1515

1616
<!-- [DOXYGEN MAIN] -->
1717

18+
The exported CMake target publishes the stable device ID configured through
19+
`MY_QDMI_DEVICE_ID` and the QDMI symbol prefix through
20+
`configure_qdmi_device_target`. Consumers such as MQT Core can use this metadata
21+
to package and register the device without project-specific loader code. This
22+
metadata does not add MQT Core as a dependency.
23+
1824
## Documentation
1925

2026
The full documentation, including project guides, a contributing guide, and the

‎templates/device/src/CMakeLists.txt‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,8 @@ set_target_properties(
4141
PROPERTIES C_VISIBILITY_PRESET hidden
4242
CXX_VISIBILITY_PRESET hidden
4343
VISIBILITY_INLINES_HIDDEN 1)
44+
configure_qdmi_device_target(TARGET ${QDMI_TARGET_NAME} ID ${MY_QDMI_DEVICE_ID}
45+
PREFIX ${QDMI_PREFIX})
4446
target_sources(${QDMI_TARGET_NAME} PRIVATE ${SRC_FILES})
4547

4648
target_sources(

0 commit comments

Comments
 (0)