🧑‍💻 Base Example Device on Template

.github/codecov.yml

@@ -1,5 +1,5 @@
 ignore:
-  - "test/**/*"
+  - "/**/test/**/*"
 
 coverage:
   range: 60..90

.github/workflows/ci.yml

@@ -49,8 +49,7 @@ jobs:
     with:
       clang-version: 21
       cpp-linter-extra-args: "-std=c++20"
-      # do not try to build docs in linter builds
-      cmake-args: "-DBUILD_QDMI_DOCS=OFF"
+      cmake-args: "-DBUILD_CXX_QDMI_TESTS=ON"
 
   template:
     name: 🏗️ Build and Test Templates

.github/workflows/reusable-cpp-ci.yml

@@ -61,7 +61,7 @@ jobs:
         run: pipx install ninja
       - name: Configure CMake
         run: |
-          cmake -G Ninja -S . -B build -DCMAKE_BUILD_TYPE=Debug -DENABLE_COVERAGE=ON -DBUILD_QDMI_DOCS=OFF
+          cmake -G Ninja -S . -B build -DCMAKE_BUILD_TYPE=Debug -DENABLE_COVERAGE=ON -DBUILD_CXX_QDMI_TESTS=ON
       - name: Build
         run: cmake --build build --config Debug
       - name: Test

.github/workflows/reusable-cpp-install-tests.yml

@@ -58,7 +58,7 @@ jobs:
       # configure CMake for using the installed QDMI
       - name: Configure CMake for use of installed QDMI
         run:
-          cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DUSE_INSTALLED_QDMI=ON
+          cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DUSE_INSTALLED_QDMI=ON -DBUILD_CXX_QDMI_TESTS=ON
           -DCMAKE_PREFIX_PATH=install-dir ${{ inputs.cmake-args }}
       # build the project
       - name: Build QDMI examples, templates, and tests with installed QDMI

CHANGELOG.md

@@ -11,6 +11,17 @@ clients compiled against a different minor or major version.
 
 ## [Unreleased]
 
+### Added
+
+- 👨‍💻 Add an option to disable installation instructions for QDMI (example and template) device ([#326])
+  ([\@ystade])
+
+### Changed
+
+- 👨‍💻 Base the example device implementation on the device template ([#326])
+  ([\@ystade])
+- 🚸 Export _all_ device headers (incl. `constants.h`) into device implementation ([#325]) ([\@ystade])
+
 ## [1.2.1] - 2025-12-22
 
 _If you are upgrading: please see [`UPGRADING.md`](UPGRADING.md#121)._
@@ -112,6 +123,8 @@ changelogs._
 
 <!-- PR links -->
 
+[#326]: https://github.com/Munich-Quantum-Software-Stack/QDMI/pull/326
+[#325]: https://github.com/Munich-Quantum-Software-Stack/QDMI/pull/325
 [#285]: https://github.com/Munich-Quantum-Software-Stack/QDMI/pull/285
 [#275]: https://github.com/Munich-Quantum-Software-Stack/QDMI/pull/275
 [#274]: https://github.com/Munich-Quantum-Software-Stack/QDMI/pull/274

CMakeLists.txt

@@ -29,6 +29,8 @@ set(PROJECT_VERSION_FULL "${PROJECT_VERSION}${PROJECT_VERSION_PRERELEASE}")
 # enable organization of targets into folders
 set_property(GLOBAL PROPERTY USE_FOLDERS ON)
 
+include(CMakeDependentOption)
+
 # Set a default build type if none was specified
 if(NOT CMAKE_BUILD_TYPE AND NOT CMAKE_CONFIGURATION_TYPES)
   message(STATUS "Setting build type to 'Release' as none was specified.")
@@ -52,14 +54,9 @@ option(
   "Use an installed version of QDMI to build examples, templates, and tests"
   OFF)
 
-if(USE_INSTALLED_QDMI)
-  set(QDMI_INSTALL
-      OFF
-      CACHE BOOL "Generate installation instructions for QDMI" FORCE)
-else()
-  option(QDMI_INSTALL "Generate installation instructions for QDMI"
-         ${QDMI_MASTER_PROJECT})
-endif()
+cmake_dependent_option(
+  INSTALL_QDMI "Generate installation instructions for QDMI"
+  ${QDMI_MASTER_PROJECT} "NOT USE_INSTALLED_QDMI" OFF)
 option(BUILD_QDMI_TESTS "Also build tests for the QDMI project"
        ${QDMI_MASTER_PROJECT})
 option(BUILD_QDMI_EXAMPLES "Also build examples for the QDMI project"
@@ -178,7 +175,7 @@ if(BUILD_QDMI_TESTS)
 endif()
 
 # Installation instructions for the main library
-if(QDMI_INSTALL)
+if(INSTALL_QDMI)
   set(QDMI_CONFIG_INSTALL_DIR
       "${CMAKE_INSTALL_DATADIR}/cmake/${PROJECT_NAME}"
       CACHE INTERNAL "Config install directory")

cmake/GenerateTemplate.cmake

@@ -42,8 +42,22 @@ if("${QDMI_TEMPLATE_CLEAN}" STREQUAL "")
   set(QDMI_TEMPLATE_CLEAN OFF)
 endif()
 
-file(REAL_PATH "${QDMI_TEMPLATE_SOURCE_DIR}" QDMI_TEMPLATE_SOURCE_DIR)
-file(REAL_PATH "${QDMI_TEMPLATE_OUTPUT_DIR}" QDMI_TEMPLATE_OUTPUT_DIR)
+# file(REAL_PATH ...) fails if the path doesn't (yet) exist on some
+# platforms/CMakes. Use REAL_PATH only when the path exists; otherwise compute
+# an absolute path which does not require the target to exist.
+if(EXISTS "${QDMI_TEMPLATE_SOURCE_DIR}")
+  file(REAL_PATH "${QDMI_TEMPLATE_SOURCE_DIR}" QDMI_TEMPLATE_SOURCE_DIR)
+else()
+  get_filename_component(QDMI_TEMPLATE_SOURCE_DIR "${QDMI_TEMPLATE_SOURCE_DIR}"
+                         ABSOLUTE)
+endif()
+
+if(EXISTS "${QDMI_TEMPLATE_OUTPUT_DIR}")
+  file(REAL_PATH "${QDMI_TEMPLATE_OUTPUT_DIR}" QDMI_TEMPLATE_OUTPUT_DIR)
+else()
+  get_filename_component(QDMI_TEMPLATE_OUTPUT_DIR "${QDMI_TEMPLATE_OUTPUT_DIR}"
+                         ABSOLUTE)
+endif()
 
 string(TOLOWER "${QDMI_TEMPLATE_PREFIX}" QDMI_TEMPLATE_prefix)
 

cmake/PrefixHandling.cmake

@@ -31,8 +31,8 @@ function(generate_prefixed_qdmi_headers prefix)
   endif()
 
   # Get the list of all QDMI device headers.
-  file(GLOB_RECURSE QDMI_DEVICE_HEADERS ${QDMI_INCLUDE_DIR}/qdmi/device.h
-       ${QDMI_INCLUDE_DIR}/qdmi/types.h)
+  file(GLOB_RECURSE QDMI_DEVICE_HEADERS ${QDMI_INCLUDE_DIR}/qdmi/constants.h
+       ${QDMI_INCLUDE_DIR}/qdmi/device.h ${QDMI_INCLUDE_DIR}/qdmi/types.h)
 
   # Determine the correct CMake directory for prefix_defs.txt
   set(QDMI_PREFIX_DIR "${QDMI_CMAKE_DIR}")
@@ -55,7 +55,7 @@ function(generate_prefixed_qdmi_headers prefix)
     # Replace the include for the device header with the prefixed version.
     string(
       REGEX
-      REPLACE "#include (\"|<)qdmi/(device|types).h(\"|>)"
+      REPLACE "#include (\"|<)qdmi/(constants|device|types).h(\"|>)"
               "#include \\1${QDMI_prefix}_qdmi/\\2.h\\3" header_content
               "${header_content}")
     # Replace the prefix definitions.
@@ -116,5 +116,5 @@ function(generate_device_defs_executable prefix)
     qdmi_test_${QDMI_prefix}_device_defs PRIVATE qdmi::qdmi ${DEVICE_TARGET}
                                                  qdmi::qdmi_project_warnings)
   target_compile_features(qdmi_test_${QDMI_prefix}_device_defs
-                          PRIVATE cxx_std_17)
+                          PRIVATE cxx_std_20)
 endfunction()

docs/CMakeLists.txt

@@ -27,8 +27,14 @@ set(DOXYGEN_INPUT_DIRS ${PROJECT_SOURCE_DIR}/include)
 # correctly and is not passed to Doxygen. Whenever such a file is modified,
 # CMake detects that change and will rerun the Doxygen command instead of using
 # the cached result when the target `qdmi_docs` is built.
-file(GLOB_RECURSE DOXYGEN_INPUT_FILES ${PROJECT_SOURCE_DIR}/include/*.h
-     ${CMAKE_CURRENT_SOURCE_DIR}/*.md)
+file(
+  GLOB_RECURSE
+  DOXYGEN_INPUT_FILES
+  ${PROJECT_SOURCE_DIR}/include/*.h
+  ${CMAKE_CURRENT_SOURCE_DIR}/*.md
+  ${PROJECT_SOURCE_DIR}/CHANGELOG.md
+  ${PROJECT_SOURCE_DIR}/UPGRADING.md
+  ${PROJECT_SOURCE_DIR}/README.md)
 # After the variable above is correctly initialized, we can add the additional
 # files that are not source code but still part of the documentation. IMPORTANT:
 # The order the files with the static content are added here influences their
@@ -52,8 +58,13 @@ string(REPLACE ";" " " DOXYGEN_INPUT_DIRS "${DOXYGEN_INPUT_DIRS}")
 # can be included with the `\include`or `\snippet` command, we need to add the
 # directories where these files are located.
 set(DOXYGEN_EXAMPLE_DIRS
-    ${PROJECT_SOURCE_DIR}/examples ${PROJECT_SOURCE_DIR}/.github
-    ${PROJECT_SOURCE_DIR}/CHANGELOG.md ${PROJECT_SOURCE_DIR}/UPGRADING.md
+    ${PROJECT_SOURCE_DIR}/examples/device/src
+    ${PROJECT_SOURCE_DIR}/examples/driver
+    ${PROJECT_SOURCE_DIR}/examples/fomac
+    ${PROJECT_SOURCE_DIR}/examples/tool
+    ${PROJECT_SOURCE_DIR}/.github
+    ${PROJECT_SOURCE_DIR}/CHANGELOG.md
+    ${PROJECT_SOURCE_DIR}/UPGRADING.md
     ${PROJECT_SOURCE_DIR}/README.md)
 # Again, replace the semicolon with a space such that Doxygen can handle it.
 string(REPLACE ";" " " DOXYGEN_EXAMPLE_DIRS "${DOXYGEN_EXAMPLE_DIRS}")

docs/examples.md

@@ -31,7 +31,7 @@ are returned by the @ref QDMI_device_session_query_device_property function. Bel
 respective implementation in C++.
 
 <!-- prettier-ignore-start -->
-\dontinclude device.cpp
+\dontinclude cxx_device.cpp
 \skip int CXX_QDMI_device_session_query_device_property
 \until QDMI_DEVICE_PROPERTY_LIBRARYVERSION
 \until size_ret)
@@ -48,23 +48,23 @@ The following macro is used to add string properties to the device. The macro is
 implementation of the @ref QDMI_device_session_query_device_property function.
 
 <!-- prettier-ignore-start -->
-\dontinclude device.cpp
+\dontinclude cxx_device.cpp
 \skip #define ADD_STRING_PROPERTY
 \until DOXYGEN MACRO END
 <!-- prettier-ignore-end -->
 
 A similar macro is defined for other (fixed length) data types, for example, `int`, `double`.
 
 <!-- prettier-ignore-start -->
-\dontinclude device.cpp
+\dontinclude cxx_device.cpp
 \skip #define ADD_SINGLE_VALUE_PROPERTY
 \until DOXYGEN MACRO END
 <!-- prettier-ignore-end -->
 
 Another macro is defined for list properties of the data types above.
 
 <!-- prettier-ignore-start -->
-\dontinclude device.cpp
+\dontinclude cxx_device.cpp
 \skip #define ADD_LIST_PROPERTY
 \until DOXYGEN MACRO END
 <!-- prettier-ignore-end -->
@@ -77,7 +77,7 @@ The following two examples demonstrate how to return integer or enumeration prop
 device.
 
 <!-- prettier-ignore-start -->
-\dontinclude device.cpp
+\dontinclude cxx_device.cpp
 \skip int CXX_QDMI_device_session_query_device_property
 \until {
 \skip QDMI_DEVICE_PROPERTY_STATUS
@@ -94,7 +94,7 @@ return the coupling map of the device as a list of @ref QDMI_Site pairs. The pai
 into a single list of @ref QDMI_Site's.
 
 <!-- prettier-ignore-start -->
-\dontinclude device.cpp
+\dontinclude cxx_device.cpp
 \skipline constexpr std::array<const CXX_QDMI_Site_impl_d *, 20>
 \skip DEVICE_COUPLING_MAP
 \until ;
@@ -114,7 +114,7 @@ demonstrates how different properties of operations, for example, varying fideli
 gates can be returned.
 
 <!-- prettier-ignore-start -->
-\dontinclude device.cpp
+\dontinclude cxx_device.cpp
 \skip QDMI_Pair_hash
 \until OPERATION_FIDELITIES
 \until ;
@@ -129,7 +129,7 @@ following example provides a mock implementation of the necessary functions to s
 first example shows a mock implementation of @ref QDMI_device_session_create_device_job.
 
 <!-- prettier-ignore-start -->
-\dontinclude device.cpp
+\dontinclude cxx_device.cpp
 \skip QDMI_device_session_create_device_job
 \until DOXYGEN FUNCTION END
 <!-- prettier-ignore-end -->
@@ -138,7 +138,7 @@ The function @ref QDMI_device_job_set_parameter allows setting different paramet
 example, the number of shots (@ref QDMI_JOB_PARAMETER_SHOTSNUM).
 
 <!-- prettier-ignore-start -->
-\dontinclude device.cpp
+\dontinclude cxx_device.cpp
 \skip QDMI_device_job_set_parameter
 \until DOXYGEN FUNCTION END
 <!-- prettier-ignore-end -->
@@ -147,12 +147,12 @@ After the job is set up, it can be submitted to the device. The following exampl
 implementation of @ref QDMI_device_job_submit.
 
 <!-- prettier-ignore-start -->
-\dontinclude device.cpp
+\dontinclude cxx_device.cpp
 \skip QDMI_device_job_submit
 \until DOXYGEN FUNCTION END
 <!-- prettier-ignore-end -->
 
 For the full implementation of the example devices we refer to the respective source files in the
 QDMI repository, that is,
-[`device.cpp`](https://github.com/Munich-Quantum-Software-Stack/QDMI/blob/develop/examples/device/device.cpp)
+[`cxx_device.cpp`](https://github.com/Munich-Quantum-Software-Stack/QDMI/blob/develop/examples/device/cxx_device.cpp)
 for the C++ implementation.

examples/device/.clang-format

@@ -0,0 +1,3 @@
+BasedOnStyle: LLVM
+IncludeBlocks: Regroup
+Standard: c++20

examples/device/.clang-tidy

@@ -0,0 +1,69 @@
+FormatStyle: file
+
+Checks: |
+  bugprone-*,
+  -bugprone-easily-swappable-parameters,
+  clang-analyzer-*,
+  -clang-analyzer-security.insecureAPI.*,
+  clang-diagnostic-*,
+  cppcoreguidelines-*,
+  -cppcoreguidelines-non-private-member-variables-in-classes,
+  -cppcoreguidelines-avoid-magic-numbers,
+  -cppcoreguidelines-macro-usage,
+  -cppcoreguidelines-pro-bounds-constant-array-index,
+  -cppcoreguidelines-pro-bounds-array-to-pointer-decay,
+  -cppcoreguidelines-pro-bounds-pointer-arithmetic,
+  -cppcoreguidelines-owning-memory,
+  google-*,
+  -google-readability-todo,
+  -google-build-using-namespace,
+  misc-*,
+  -misc-no-recursion,
+  -misc-non-private-member-variables-in-classes,
+  modernize-*,
+  -modernize-use-trailing-return-type,
+  performance-*,
+  portability-*,
+  -portability-avoid-pragma-once
+  readability-*,
+  -readability-identifier-length,
+  -readability-magic-numbers,
+  -readability-function-cognitive-complexity
+
+CheckOptions:
+  - key: readability-identifier-naming.ClassCase
+    value: CamelCase
+  - key: readability-identifier-naming.ConstantParameterCase
+    value: lower_case
+  - key: readability-identifier-naming.EnumCase
+    value: UPPER_CASE
+  - key: readability-identifier-naming.EnumConstantCase
+    value: UPPER_CASE
+  - key: readability-identifier-naming.FunctionCase
+    value: Leading_upper_snake_case
+  - key: readability-identifier-naming.FunctionIgnoredRegexp
+    value: ".*QDMI.*"
+  - key: readability-identifier-naming.GlobalConstantCase
+    value: UPPER_CASE
+  - key: readability-identifier-naming.IgnoreMainLikeFunctions
+    value: "true"
+  - key: readability-identifier-naming.LocalConstantCase
+    value: lower_case
+  - key: readability-identifier-naming.MemberCase
+    value: lower_case
+  - key: readability-identifier-naming.MemberIgnoredRegexp
+    value: ".*QDMI.*"
+  - key: readability-identifier-naming.MethodCase
+    value: lower_case
+  - key: readability-identifier-naming.ParameterCase
+    value: lower_case
+  - key: readability-identifier-naming.NamespaceCase
+    value: lower_case
+  - key: readability-identifier-naming.StaticConstantCase
+    value: UPPER_CASE
+  - key: readability-identifier-naming.StructCase
+    value: Leading_upper_snake_case
+  - key: readability-identifier-naming.StructIgnoredRegexp
+    value: ".*QDMI.*"
+  - key: readability-identifier-naming.VariableCase
+    value: lower_case

examples/device/.cmake-format.yaml

@@ -0,0 +1,6 @@
+format:
+  line_width: 80
+  keyword_case: "upper"
+  autosort: true
+markup:
+  first_comment_is_literal: true