munich-quantum-toolkit · mergify · Mar 31, 2026 · Mar 31, 2026
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 = [