📦 Switch to component-based installation for the MQT Core Python package (#1596)

burgholzer · burgholzer · commit 8ac203d411a8 · 2026-03-31T09:59:15.000+02:00
## Description This PR switches the MQT Core Python package build to use component-based installation. This is a first step towards enabling MLIR as part of the Python package. The majority of the work in this PR was to properly define our external dependencies (nlohmann_json, spdlog, QDMI) in a way that they can be included as part of our installation components configuration. This requires defining our own installation instructions for these libraries (except for QDMI). One of the big plus points of this is that it allows us to drop all the `DISABLE_INSTALL` in the MLIR code, as the respective code is not added to any of the components we define at the moment. ## 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://github.com/munich-quantum-toolkit/core/blob/main/docs/ai_usage.md). - [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. --------- Signed-off-by: burgholzer <burgholzer@me.com> (cherry picked from commit 8cec5ca) Signed-off-by: burgholzer <burgholzer@me.com> # Conflicts: # CMakeLists.txt # cmake/ExternalDependencies.cmake # mlir/lib/Compiler/CMakeLists.txt # mlir/lib/Conversion/MQTOptToMQTRef/CMakeLists.txt # mlir/lib/Conversion/MQTRefToMQTOpt/CMakeLists.txt # mlir/lib/Conversion/MQTRefToQIR/CMakeLists.txt # mlir/lib/Conversion/QCOToJeff/CMakeLists.txt # mlir/lib/Conversion/QIRToMQTRef/CMakeLists.txt # mlir/lib/Dialect/MQTOpt/IR/CMakeLists.txt # mlir/lib/Dialect/MQTRef/IR/CMakeLists.txt # mlir/lib/Dialect/MQTRef/Translation/CMakeLists.txt # mlir/lib/Dialect/QC/Builder/CMakeLists.txt # mlir/lib/Dialect/QC/Translation/CMakeLists.txt # mlir/lib/Dialect/QCO/IR/CMakeLists.txt # mlir/lib/Dialect/QCO/Utils/CMakeLists.txt # mlir/lib/Dialect/QIR/Builder/CMakeLists.txt # mlir/lib/Dialect/QIR/Utils/CMakeLists.txt # mlir/lib/Support/CMakeLists.txt
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -15,6 +15,7 @@ This project adheres to [Semantic Versioning], with the exception that minor rel
 
 ### Changed
 
+- 📦 Switch to component-based installation for the MQT Core Python package ([#1596]) ([**@burgholzer**])
 - ⬆️ Update QDMI to latest version from stable `v1.2.x` branch ([#1593]) ([**@burgholzer**])
 
 ## [3.4.1] - 2026-02-01
@@ -320,6 +321,7 @@ _📚 Refer to the [GitHub Release Notes](https://github.com/munich-quantum-tool
 
 <!-- PR links -->
 
+[#1596]: https://github.com/munich-quantum-toolkit/core/pull/1596
 [#1593]: https://github.com/munich-quantum-toolkit/core/pull/1593
 [#1507]: https://github.com/munich-quantum-toolkit/core/pull/1507
 [#1481]: https://github.com/munich-quantum-toolkit/core/pull/1481
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -63,6 +63,29 @@ option(MQT_CORE_INSTALL "Generate installation instructions for MQT Core"
 option(BUILD_MQT_CORE_TESTS "Build tests for the MQT Core project" ${MQT_CORE_MASTER_PROJECT})
 option(BUILD_MQT_CORE_SHARED_LIBS "Build MQT Core libraries as shared libraries"
        ${BUILD_SHARED_LIBS})
+option(BUILD_MQT_CORE_MLIR "Build the MLIR submodule of the MQT Core project" OFF)
+if(APPLE AND CMAKE_CXX_COMPILER_ID STREQUAL "GNU")
+  set(BUILD_MQT_CORE_MLIR
+      OFF
+      CACHE BOOL
+            "Disable MLIR build on macOS with GCC to avoid ABI issues between STL and libstdc++"
+            FORCE)
+  message(
+    WARNING "Disabling MLIR build on macOS with GCC to avoid ABI issues between STL and libstdc++")
+endif()
+if(APPLE AND CMAKE_CXX_COMPILER_ID STREQUAL "AppleClang")
+  if(CMAKE_CXX_COMPILER_VERSION VERSION_LESS "17.0.0")
+    set(BUILD_MQT_CORE_MLIR
+        OFF
+        CACHE
+          BOOL
+          "Disable MLIR build on macOS with Apple Clang < 17 due to missing complete C++20 support"
+          FORCE)
+    message(
+      WARNING
+        "Disabling MLIR build on macOS with Apple Clang < 17 due to missing complete C++20 support")
+  endif()
+endif()
 
 # try to determine the project version
 include(GetVersion)
@@ -74,6 +97,12 @@ project(
   VERSION ${MQT_CORE_VERSION}
   DESCRIPTION "MQT Core - The Backbone of the Munich Quantum Toolkit")
 
+set(MQT_CORE_TARGET_NAME "mqt-core")
+
+if(BUILD_MQT_CORE_MLIR)
+  include(SetupMLIR)
+endif()
+
 include(cmake/ExternalDependencies.cmake)
 
 # set the include directory for the build tree
@@ -91,34 +120,6 @@ if(MQT_CORE_INSTALL)
   set(CMAKE_BUILD_WITH_INSTALL_RPATH TRUE)
 endif()
 
-set(MQT_CORE_TARGET_NAME "mqt-core")
-
-option(BUILD_MQT_CORE_MLIR "Build the MLIR submodule of the MQT Core project" OFF)
-if(APPLE AND CMAKE_CXX_COMPILER_ID STREQUAL "GNU")
-  set(BUILD_MQT_CORE_MLIR
-      OFF
-      CACHE BOOL
-            "Disable MLIR build on macOS with GCC to avoid ABI issues between STL and libstdc++"
-            FORCE)
-  message(
-    WARNING "Disabling MLIR build on macOS with GCC to avoid ABI issues between STL and libstdc++")
-endif()
-if(APPLE AND CMAKE_CXX_COMPILER_ID STREQUAL "AppleClang")
-  if(CMAKE_CXX_COMPILER_VERSION VERSION_LESS "17.0.0")
-    set(BUILD_MQT_CORE_MLIR
-        OFF
-        CACHE
-          BOOL
-          "Disable MLIR build on macOS with Apple Clang < 17 due to missing complete C++20 support"
-          FORCE)
-    message(
-      WARNING
-        "Disabling MLIR build on macOS with Apple Clang < 17 due to missing complete C++20 support")
-  endif()
-endif()
-if(BUILD_MQT_CORE_MLIR)
-  include(SetupMLIR)
-endif()
 cmake_dependent_option(BUILD_MQT_CORE_QIR_RUNNER "Build the QIR runner of the MQT Core project" ON
                        "BUILD_MQT_CORE_MLIR" OFF)
 
diff --git a/cmake/ExternalDependencies.cmake b/cmake/ExternalDependencies.cmake
@@ -29,7 +29,12 @@ set(JSON_URL https://github.com/nlohmann/json/releases/download/v${JSON_VERSION}
 set(JSON_SystemInclude
     ON
     CACHE INTERNAL "Treat the library headers like system headers")
-cmake_dependent_option(JSON_Install "Install nlohmann_json library" ON "MQT_CORE_INSTALL" OFF)
+cmake_dependent_option(MQT_CORE_JSON_INSTALL "Install nlohmann_json library" ON "MQT_CORE_INSTALL"
+                       OFF)
+# Disable upstream nlohmann_json install rules and install with explicit MQT components below.
+set(JSON_Install
+    OFF
+    CACHE BOOL "Disable upstream nlohmann_json install rules; handled by mqt-core" FORCE)
 FetchContent_Declare(nlohmann_json URL ${JSON_URL} FIND_PACKAGE_ARGS ${JSON_VERSION})
 list(APPEND FETCH_PACKAGES nlohmann_json)
 
@@ -94,7 +99,11 @@ set(SPDLOG_BUILD_PIC ON)
 set(SPDLOG_SYSTEM_INCLUDES
     ON
     CACHE INTERNAL "Treat the library headers like system headers")
-cmake_dependent_option(SPDLOG_INSTALL "Install spdlog library" ON "MQT_CORE_INSTALL" OFF)
+cmake_dependent_option(MQT_CORE_SPDLOG_INSTALL "Install spdlog library" ON "MQT_CORE_INSTALL" OFF)
+# Disable upstream spdlog install rules and install with explicit MQT components below.
+set(SPDLOG_INSTALL
+    OFF
+    CACHE BOOL "Disable upstream spdlog install rules; handled by mqt-core" FORCE)
 cmake_dependent_option(SPDLOG_BUILD_SHARED "Build spdlog as shared library" ON
                        "BUILD_MQT_CORE_SHARED_LIBS" OFF)
 FetchContent_Declare(spdlog URL ${SPDLOG_URL} FIND_PACKAGE_ARGS ${SPDLOG_VERSION})
@@ -103,6 +112,62 @@ list(APPEND FETCH_PACKAGES spdlog)
 # Make all declared dependencies available.
 FetchContent_MakeAvailable(${FETCH_PACKAGES})
 
+# Install nlohmann_json with explicit MQT components.
+if(MQT_CORE_JSON_INSTALL AND TARGET nlohmann_json)
+  set(MQT_CORE_JSON_CONFIG_INSTALL_DIR "${CMAKE_INSTALL_DATADIR}/cmake/nlohmann_json")
+  set(MQT_CORE_JSON_TARGETS_EXPORT_NAME "nlohmann_jsonTargets")
+  set(MQT_CORE_JSON_CONFIG_FILE "${CMAKE_CURRENT_BINARY_DIR}/nlohmann_jsonConfig.cmake")
+  set(MQT_CORE_JSON_VERSION_CONFIG_FILE
+      "${CMAKE_CURRENT_BINARY_DIR}/nlohmann_jsonConfigVersion.cmake")
+
+  # nlohmann_json's upstream templates expect these names.
+  set(_mqt_core_saved_project_name "${PROJECT_NAME}")
+  set(_mqt_core_saved_project_version "${PROJECT_VERSION}")
+  set(_mqt_core_saved_project_version_major "${PROJECT_VERSION_MAJOR}")
+  set(PROJECT_NAME "nlohmann_json")
+  set(PROJECT_VERSION "${JSON_VERSION}")
+  string(REGEX MATCH "^[0-9]+" PROJECT_VERSION_MAJOR "${JSON_VERSION}")
+  set(NLOHMANN_JSON_TARGET_NAME "nlohmann_json")
+  set(NLOHMANN_JSON_TARGETS_EXPORT_NAME "${MQT_CORE_JSON_TARGETS_EXPORT_NAME}")
+
+  configure_file(${nlohmann_json_SOURCE_DIR}/cmake/config.cmake.in ${MQT_CORE_JSON_CONFIG_FILE}
+                 @ONLY)
+  configure_file(${nlohmann_json_SOURCE_DIR}/cmake/nlohmann_jsonConfigVersion.cmake.in
+                 ${MQT_CORE_JSON_VERSION_CONFIG_FILE} @ONLY)
+
+  set(PROJECT_NAME "${_mqt_core_saved_project_name}")
+  set(PROJECT_VERSION "${_mqt_core_saved_project_version}")
+  set(PROJECT_VERSION_MAJOR "${_mqt_core_saved_project_version_major}")
+  unset(_mqt_core_saved_project_name)
+  unset(_mqt_core_saved_project_version)
+  unset(_mqt_core_saved_project_version_major)
+  unset(NLOHMANN_JSON_TARGET_NAME)
+  unset(NLOHMANN_JSON_TARGETS_EXPORT_NAME)
+
+  install(
+    DIRECTORY ${nlohmann_json_SOURCE_DIR}/include/
+    DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}
+    COMPONENT ${MQT_CORE_TARGET_NAME}_Development)
+
+  install(
+    TARGETS nlohmann_json
+    EXPORT ${MQT_CORE_JSON_TARGETS_EXPORT_NAME}
+    INCLUDES
+    DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}
+    COMPONENT ${MQT_CORE_TARGET_NAME}_Development)
+
+  install(
+    EXPORT ${MQT_CORE_JSON_TARGETS_EXPORT_NAME}
+    NAMESPACE nlohmann_json::
+    DESTINATION ${MQT_CORE_JSON_CONFIG_INSTALL_DIR}
+    COMPONENT ${MQT_CORE_TARGET_NAME}_Development)
+
+  install(
+    FILES ${MQT_CORE_JSON_CONFIG_FILE} ${MQT_CORE_JSON_VERSION_CONFIG_FILE}
+    DESTINATION ${MQT_CORE_JSON_CONFIG_INSTALL_DIR}
+    COMPONENT ${MQT_CORE_TARGET_NAME}_Development)
+endif()
+
 # Ensure external shared libraries end up in a common lib layout used by our RUNPATH
 if(TARGET spdlog)
   set_target_properties(
@@ -112,17 +177,59 @@ if(TARGET spdlog)
                RUNTIME_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/${CMAKE_INSTALL_BINDIR}")
 endif()
 
-# Patch for spdlog cmake files to be installed in a common cmake directory
-if(SPDLOG_INSTALL)
+# Install spdlog with explicit MQT components.
+if(MQT_CORE_SPDLOG_INSTALL
+   AND TARGET spdlog
+   AND TARGET spdlog_header_only)
+  include(CMakePackageConfigHelpers)
+
+  set(MQT_CORE_SPDLOG_CONFIG_INSTALL_DIR "${CMAKE_INSTALL_DATADIR}/cmake/spdlog")
+  set(MQT_CORE_SPDLOG_CONFIG_TARGETS_FILE "spdlogConfigTargets.cmake")
+  set(MQT_CORE_SPDLOG_CONFIG_FILE "${CMAKE_CURRENT_BINARY_DIR}/spdlogConfig.cmake")
+  set(MQT_CORE_SPDLOG_VERSION_CONFIG_FILE "${CMAKE_CURRENT_BINARY_DIR}/spdlogConfigVersion.cmake")
+
+  install(
+    TARGETS spdlog spdlog_header_only
+    EXPORT spdlog
+    RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR} COMPONENT ${MQT_CORE_TARGET_NAME}_Runtime
+    LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
+            COMPONENT ${MQT_CORE_TARGET_NAME}_Runtime
+            NAMELINK_COMPONENT ${MQT_CORE_TARGET_NAME}_Development
+    ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR} COMPONENT ${MQT_CORE_TARGET_NAME}_Development)
+
+  install(
+    DIRECTORY ${spdlog_SOURCE_DIR}/include/
+    DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}
+    COMPONENT ${MQT_CORE_TARGET_NAME}_Development
+    PATTERN "fmt/bundled" EXCLUDE)
+
+  if(NOT SPDLOG_USE_STD_FORMAT
+     AND NOT SPDLOG_FMT_EXTERNAL
+     AND NOT SPDLOG_FMT_EXTERNAL_HO)
+    install(
+      DIRECTORY ${spdlog_SOURCE_DIR}/include/spdlog/fmt/bundled/
+      DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/spdlog/fmt/bundled
+      COMPONENT ${MQT_CORE_TARGET_NAME}_Development)
+  endif()
+
+  install(
+    EXPORT spdlog
+    FILE ${MQT_CORE_SPDLOG_CONFIG_TARGETS_FILE}
+    NAMESPACE spdlog::
+    DESTINATION ${MQT_CORE_SPDLOG_CONFIG_INSTALL_DIR}
+    COMPONENT ${MQT_CORE_TARGET_NAME}_Development)
+
+  set(config_targets_file ${MQT_CORE_SPDLOG_CONFIG_TARGETS_FILE})
+  configure_package_config_file(
+    ${spdlog_SOURCE_DIR}/cmake/spdlogConfig.cmake.in ${MQT_CORE_SPDLOG_CONFIG_FILE}
+    INSTALL_DESTINATION ${MQT_CORE_SPDLOG_CONFIG_INSTALL_DIR})
+  write_basic_package_version_file(
+    ${MQT_CORE_SPDLOG_VERSION_CONFIG_FILE}
+    VERSION ${SPDLOG_VERSION}
+    COMPATIBILITY SameMajorVersion)
+
   install(
-    CODE "
-    file(GLOB SPDLOG_CMAKE_FILES
-      \"\${CMAKE_INSTALL_PREFIX}/${CMAKE_INSTALL_LIBDIR}/cmake/spdlog/*\")
-    if(SPDLOG_CMAKE_FILES)
-      file(MAKE_DIRECTORY \"\${CMAKE_INSTALL_PREFIX}/${CMAKE_INSTALL_DATADIR}/cmake/spdlog\")
-      file(COPY \${SPDLOG_CMAKE_FILES}
-        DESTINATION \"\${CMAKE_INSTALL_PREFIX}/${CMAKE_INSTALL_DATADIR}/cmake/spdlog\")
-      file(REMOVE_RECURSE \"\${CMAKE_INSTALL_PREFIX}/${CMAKE_INSTALL_LIBDIR}/cmake/spdlog\")
-    endif()
-  ")
+    FILES ${MQT_CORE_SPDLOG_CONFIG_FILE} ${MQT_CORE_SPDLOG_VERSION_CONFIG_FILE}
+    DESTINATION ${MQT_CORE_SPDLOG_CONFIG_INSTALL_DIR}
+    COMPONENT ${MQT_CORE_TARGET_NAME}_Development)
 endif()
diff --git a/mlir/lib/Conversion/MQTOptToMQTRef/CMakeLists.txt b/mlir/lib/Conversion/MQTOptToMQTRef/CMakeLists.txt
@@ -19,5 +19,4 @@ add_mlir_library(
   MLIRMemRefDialect
   MLIRTransforms
   MLIRFuncDialect
-  MLIRFuncTransforms
-  DISABLE_INSTALL)
+  MLIRFuncTransforms)
diff --git a/mlir/lib/Conversion/MQTRefToMQTOpt/CMakeLists.txt b/mlir/lib/Conversion/MQTRefToMQTOpt/CMakeLists.txt
@@ -19,5 +19,4 @@ add_mlir_library(
   MLIRMemRefDialect
   MLIRTransforms
   MLIRFuncDialect
-  MLIRFuncTransforms
-  DISABLE_INSTALL)
+  MLIRFuncTransforms)
diff --git a/mlir/lib/Conversion/MQTRefToQIR/CMakeLists.txt b/mlir/lib/Conversion/MQTRefToQIR/CMakeLists.txt
@@ -19,5 +19,4 @@ add_mlir_library(
   MLIRTransforms
   MLIRLLVMDialect
   MLIRFuncToLLVM
-  MLIRReconcileUnrealizedCasts
-  DISABLE_INSTALL)
+  MLIRReconcileUnrealizedCasts)
diff --git a/mlir/lib/Conversion/QIRToMQTRef/CMakeLists.txt b/mlir/lib/Conversion/QIRToMQTRef/CMakeLists.txt
@@ -17,5 +17,4 @@ add_mlir_library(
   MLIRMQTRef
   MLIRMemRefDialect
   MLIRTransforms
-  MLIRLLVMDialect
-  DISABLE_INSTALL)
+  MLIRLLVMDialect)
diff --git a/mlir/lib/Dialect/MQTOpt/IR/CMakeLists.txt b/mlir/lib/Dialect/MQTOpt/IR/CMakeLists.txt
@@ -14,8 +14,7 @@ add_mlir_dialect_library(
   MLIRMQTOptInterfacesIncGen
   LINK_LIBS
   MLIRIR
-  MLIRInferTypeOpInterface
-  DISABLE_INSTALL)
+  MLIRInferTypeOpInterface)
 
 # collect header files
 file(GLOB_RECURSE IR_HEADERS_SOURCE "${MQT_MLIR_SOURCE_INCLUDE_DIR}/mlir/Dialect/MQTOpt/IR/*.h")
diff --git a/mlir/lib/Dialect/MQTOpt/Transforms/CMakeLists.txt b/mlir/lib/Dialect/MQTOpt/Transforms/CMakeLists.txt
@@ -11,14 +11,8 @@ set(LIBRARIES ${dialect_libs} MQT::CoreIR)
 
 file(GLOB_RECURSE TRANSFORMS_SOURCES *.cpp)
 
-add_mlir_library(
-  MLIRMQTOptTransforms
-  ${TRANSFORMS_SOURCES}
-  LINK_LIBS
-  ${LIBRARIES}
-  DEPENDS
-  MLIRMQTOptTransformsIncGen
-  DISABLE_INSTALL)
+add_mlir_library(MLIRMQTOptTransforms ${TRANSFORMS_SOURCES} LINK_LIBS ${LIBRARIES} DEPENDS
+                 MLIRMQTOptTransformsIncGen)
 
 # collect header files
 file(GLOB_RECURSE TRANSFORMS_HEADERS_SOURCE
diff --git a/mlir/lib/Dialect/MQTRef/IR/CMakeLists.txt b/mlir/lib/Dialect/MQTRef/IR/CMakeLists.txt
@@ -14,8 +14,7 @@ add_mlir_dialect_library(
   MLIRMQTRefInterfacesIncGen
   LINK_LIBS
   MLIRIR
-  MLIRInferTypeOpInterface
-  DISABLE_INSTALL)
+  MLIRInferTypeOpInterface)
 
 # collect header files
 file(GLOB_RECURSE IR_HEADERS_SOURCE "${MQT_MLIR_SOURCE_INCLUDE_DIR}/mlir/Dialect/MQTRef/IR/*.h")
diff --git a/mlir/lib/Dialect/MQTRef/Translation/CMakeLists.txt b/mlir/lib/Dialect/MQTRef/Translation/CMakeLists.txt
@@ -15,8 +15,7 @@ add_mlir_library(
   MLIRMemRefDialect
   MLIRSCFDialect
   MLIRMQTRef
-  MQT::CoreIR
-  DISABLE_INSTALL)
+  MQT::CoreIR)
 
 # collect header files
 file(GLOB_RECURSE TRANSLATION_HEADERS_SOURCE
diff --git a/pyproject.toml b/pyproject.toml
@@ -103,6 +103,13 @@ build.targets = [
   "mqt-core-qdmi-sc-device-dyn",
 ]
 
+install.components = [
+  "mqt-core_Runtime",
+  "mqt-core_Development",
+  "mqt-core_Python",
+  "qdmi_Development",
+]
+
 metadata.version.provider = "scikit_build_core.metadata.setuptools_scm"
 sdist.include = ["python/mqt/core/_version.py"]
 sdist.exclude = [
