MSVC: Use Qt Release runtime in Debug config (#1256)

LeonMatthesKDAB · web-flow · commit ee3c26170cce · 2025-04-25T13:04:39.000+01:00
* MSVC: Link Qt components to Release runtime

* Windows CI: Build Qt6 in Debug

To ensure we can actually build and run tests in Debug mode, run at
least one Windows CI runner in Debug mode.

* Document MSVC runtime mismatch issues

* qml_multi_crates: Map config for Qt::Network
diff --git a/.github/workflows/github-cxx-qt-tests.yml b/.github/workflows/github-cxx-qt-tests.yml
@@ -285,6 +285,7 @@ jobs:
             clang_format_path: /home/runner/.local/bin/clang-format
             cargo_dir: ~/.cargo
             rustc_wrapper: sccache
+            build_type: Release
           - name: Ubuntu 24.04 (gcc) Qt6
             os: ubuntu-24.04
             qt_version: 6
@@ -301,6 +302,7 @@ jobs:
             clang_format_path: /home/runner/.local/bin/clang-format
             cargo_dir: ~/.cargo
             rustc_wrapper: sccache
+            build_type: Release
             packages-extra: >-
                 libgl1-mesa-dev
                 libvulkan-dev
@@ -327,6 +329,7 @@ jobs:
             cc: clang
             cxx: clang++
             rustc_wrapper: sccache
+            build_type: Release
           - name: macOS 14 (clang) Qt6
             os: macos-14
             qt_version: 6
@@ -348,6 +351,7 @@ jobs:
             cc: clang
             cxx: clang++
             rustc_wrapper: sccache
+            build_type: Release
 
           - name: Windows 2022 (MSVC) Qt5
             os: windows-2022
@@ -366,6 +370,7 @@ jobs:
             cc: cl
             cxx: cl
             rustc_wrapper: sccache
+            build_type: Release
           - name: Windows 2022 (MSVC2019) Qt6
             os: windows-2022
             qt_version: 6
@@ -383,7 +388,9 @@ jobs:
             cc: cl
             cxx: cl
             rustc_wrapper: sccache
-          - name: Windows 2022 (MSVC2022) Qt6
+            build_type: Release
+            # Use a Debug build to ensure we can build and run tests in Debug mode with MSVC
+          - name: Windows 2022 (MSVC2022) Qt6 Debug
             os: windows-2022
             qt_version: 6
             aqt_version: '6.9.0'
@@ -400,6 +407,7 @@ jobs:
             cc: cl
             cxx: cl
             rustc_wrapper: sccache
+            build_type: Debug
 
     runs-on: ${{ matrix.os }}
     name: ${{ matrix.name }}
@@ -536,23 +544,23 @@ jobs:
       run: >-
         cmake ${{ matrix.cmake_args }}
         -D USE_QT5=${{ matrix.qt_version == 5 }}
-        -D CMAKE_BUILD_TYPE=Release
+        -D CMAKE_BUILD_TYPE=${{ matrix.build_type }}
         -G Ninja
         -S . -B build
       env:
         RUSTC_WRAPPER: ${{ matrix.rustc_wrapper }}
         CC: ${{ matrix.cc }}
         CXX: ${{ matrix.cxx }}
     - name: "Build"
-      run: cmake --build build --config Release --parallel ${{ matrix.cores }}
+      run: cmake --build build --config ${{ matrix.build_type }} --parallel ${{ matrix.cores }}
       env:
         RUSTC_WRAPPER: ${{ matrix.rustc_wrapper }}
 
     - name: "Print compiler cache statistics"
       run: sccache --show-stats
 
     - name: "Test"
-      run: ctest ${{ matrix.ctest_args }} -C Release -T test --output-on-failure --parallel ${{ matrix.cores }}
+      run: ctest ${{ matrix.ctest_args }} -C ${{ matrix.build_type }} -T test --output-on-failure --parallel ${{ matrix.cores }}
       working-directory: ./build
       env:
         # Use the version of clang-format from pip
diff --git a/book/src/getting-started/5-cmake-integration.md b/book/src/getting-started/5-cmake-integration.md
@@ -207,6 +207,31 @@ You should now see the two Labels that display the state of our `MyObject`, as w
 
 ### Windows with MSVC
 
-If you're building CXX-Qt on Windows using MSVC generator, you need to ensure that `set(CMAKE_MSVC_RUNTIME_LIBRARY "MultiThreadedDLL")` is set in CMake (or use the `-DCMAKE_MSVC_RUNTIME_LIBRARY=MultiThreadedDLL` flag) when building with the `Debug` configuration. This flag is necessary to ensure that the correct C Runtime Library is used. Then you can build using `cmake --build build --config Debug`.
+MSVC provides multiple versions of its runtime library.
+Unfortunately the Debug and Release versions are not binary compatible.
+The recommendation by Microsoft is to not mix different runtimes.
 
-This issue is caused by a bug in the [cc](https://docs.rs/cc/latest/cc/index.html) crate (as described in [this pull request](https://github.com/rust-lang/cc-rs/pull/717)), which has not been merged yet. Specifically, the problem is that cc generated code always links to the MultiThreaded runtime, even when building in Debug mode. We hope that this step won't be necessary in the future, once the cc crate fix is merged and released.
+See also: <https://learn.microsoft.com/en-us/cpp/c-runtime-library/crt-library-features?view=msvc-170>
+
+Currently, Rust by default [links to the Multi-Threaded **Release** DLL runtime](https://github.com/rust-lang/rust/issues/39016).
+This is a mismatch with the default CMake MSVC Debug configurations, which uses the Multi-Threaded **Debug** DLLs.
+
+To resolve this mismatch, we currently recommend to stick with the Multi-Threaded Release DLL runtime (`/MD`) **for the entire program**!
+
+For CMake, make sure to call `set(CMAKE_MSVC_RUNTIME_LIBRARY "MultiThreadedDLL")` (or use the `-DCMAKE_MSVC_RUNTIME_LIBRARY=MultiThreadedDLL` flag) when building with the `Debug` configuration.
+See also the [Corrosion documentation](https://corrosion-rs.github.io/corrosion/common_issues.html#linking-debug-cc-libraries-into-rust-fails-on-windows-msvc-targets).
+
+Additionally, the Qt Debug DLLs also use the Debug runtime.
+We can force Qt to use the Release DLLs instead in the Debug configuration by setting the `MAP_IMPORTED_CONFIG_DEBUG` property to `"RELEASE"` on **all Qt components** that are linked into the final binary.
+
+```cmake
+# Note: The Qt:: targets are ALIAS targets that do not support setting properties directly.
+# We therefore need to resolve the target names to either Qt5 or Qt6 directly.
+set_property(
+    TARGET Qt6::Core Qt6::Gui Qt6::Qml Qt6::Test Qt6::QuickControls2
+    PROPERTY MAP_IMPORTED_CONFIG_DEBUG "RELEASE")
+```
+
+We hope that in the future the Rust ecosystem can be configured to use the Debug runtime, so that these additional configurations are not necessary.
+
+Note: These issues do not apply to Cargo-only builds, as these always use the Release runtime and Release Qt DLLs.
diff --git a/examples/demo_threading/CMakeLists.txt b/examples/demo_threading/CMakeLists.txt
@@ -35,9 +35,20 @@ endif()
 
 if(NOT USE_QT5)
     find_package(Qt6 COMPONENTS ${CXXQT_QTCOMPONENTS})
+    set(Qt "Qt6")
 endif()
 if(NOT Qt6_FOUND)
     find_package(Qt5 5.15 COMPONENTS ${CXXQT_QTCOMPONENTS} REQUIRED)
+    set(Qt "Qt5")
+endif()
+
+if(MSVC)
+    # Qt also needs to link against the non-debug version of the MSVC Runtime libraries, see the previous comment.
+    # Note: The Qt:: targets are ALIAS targets that do not support setting properties directly.
+    # We therefore need to resolve the target names to either Qt5 or Qt6 directly.
+    set_property(
+        TARGET ${Qt}::Core ${Qt}::Gui ${Qt}::Qml ${Qt}::QuickControls2
+        PROPERTY MAP_IMPORTED_CONFIG_DEBUG "RELEASE")
 endif()
 
 find_package(CxxQt QUIET)
diff --git a/examples/qml_features/CMakeLists.txt b/examples/qml_features/CMakeLists.txt
@@ -35,9 +35,20 @@ endif()
 
 if(NOT USE_QT5)
     find_package(Qt6 COMPONENTS ${CXXQT_QTCOMPONENTS})
+    set(Qt "Qt6")
 endif()
 if(NOT Qt6_FOUND)
     find_package(Qt5 5.15 COMPONENTS ${CXXQT_QTCOMPONENTS} REQUIRED)
+    set(Qt "Qt5")
+endif()
+
+if(MSVC)
+    # Qt also needs to link against the non-debug version of the MSVC Runtime libraries, see the previous comment.
+    # Note: The Qt:: targets are ALIAS targets that do not support setting properties directly.
+    # We therefore need to resolve the target names to either Qt5 or Qt6 directly.
+    set_property(
+        TARGET ${Qt}::Core ${Qt}::Gui ${Qt}::Qml ${Qt}::Quick ${Qt}::QuickControls2 ${Qt}::QuickTest ${Qt}::Test
+        PROPERTY MAP_IMPORTED_CONFIG_DEBUG "RELEASE")
 endif()
 
 find_package(CxxQt QUIET)
diff --git a/examples/qml_minimal/CMakeLists.txt b/examples/qml_minimal/CMakeLists.txt
@@ -41,12 +41,24 @@ endif()
 # ANCHOR: book_cmake_setup-4
 if(NOT USE_QT5)
     find_package(Qt6 COMPONENTS ${CXXQT_QTCOMPONENTS})
+    set(Qt "Qt6")
 endif()
 if(NOT Qt6_FOUND)
     find_package(Qt5 5.15 COMPONENTS ${CXXQT_QTCOMPONENTS} REQUIRED)
+    set(Qt "Qt5")
+endif()
+
+if(MSVC)
+    # Qt also needs to link against the non-debug version of the MSVC Runtime libraries.
+    # Note: The Qt:: targets are ALIAS targets that do not support setting properties directly.
+    # We therefore need to resolve the target names to either Qt5 or Qt6 directly.
+    set_property(
+        TARGET ${Qt}::Core ${Qt}::Gui ${Qt}::Qml ${Qt}::QuickControls2 ${Qt}::QuickTest ${Qt}::Test
+        PROPERTY MAP_IMPORTED_CONFIG_DEBUG "RELEASE")
 endif()
 # ANCHOR_END: book_cmake_setup-4
 
+
 # ANCHOR: book_cmake_find_cxx_qt_start
 find_package(CxxQt QUIET)
 if(NOT CxxQt_FOUND)
diff --git a/examples/qml_multi_crates/CMakeLists.txt b/examples/qml_multi_crates/CMakeLists.txt
@@ -34,9 +34,20 @@ endif()
 
 if(NOT USE_QT5)
     find_package(Qt6 COMPONENTS ${CXXQT_QTCOMPONENTS})
+    set(Qt "Qt6")
 endif()
 if(NOT Qt6_FOUND)
     find_package(Qt5 5.15 COMPONENTS ${CXXQT_QTCOMPONENTS} REQUIRED)
+    set(Qt "Qt5")
+endif()
+
+if(MSVC)
+    # Qt also needs to link against the non-debug version of the MSVC Runtime libraries, see the previous comment.
+    # Note: The Qt:: targets are ALIAS targets that do not support setting properties directly.
+    # We therefore need to resolve the target names to either Qt5 or Qt6 directly.
+    set_property(
+        TARGET ${Qt}::Core ${Qt}::Gui ${Qt}::Qml ${Qt}::QuickControls2 ${Qt}::QuickTest ${Qt}::Test ${Qt}::Network
+        PROPERTY MAP_IMPORTED_CONFIG_DEBUG "RELEASE")
 endif()
 
 find_package(CxxQt QUIET)
diff --git a/tests/basic_cxx_only/CMakeLists.txt b/tests/basic_cxx_only/CMakeLists.txt
@@ -24,10 +24,21 @@ set(CMAKE_CXX_STANDARD 17)
 set(CMAKE_CXX_STANDARD_REQUIRED ON)
 
 if(NOT USE_QT5)
-    find_package(Qt6 COMPONENTS Core Gui Qml Test)
+    find_package(Qt6 COMPONENTS Core Gui Qml Test QuickControls2)
+    set(Qt "Qt6")
 endif()
 if(NOT Qt6_FOUND)
     find_package(Qt5 5.15 COMPONENTS Core Gui Qml Test QuickControls2 REQUIRED)
+    set(Qt "Qt5")
+endif()
+
+if(MSVC)
+    # Qt also needs to link against the non-debug version of the MSVC Runtime libraries, see the previous comment.
+    # Note: The Qt:: targets are ALIAS targets that do not support setting properties directly.
+    # We therefore need to resolve the target names to either Qt5 or Qt6 directly.
+    set_property(
+        TARGET ${Qt}::Core ${Qt}::Gui ${Qt}::Qml ${Qt}::Test ${Qt}::QuickControls2
+        PROPERTY MAP_IMPORTED_CONFIG_DEBUG "RELEASE")
 endif()
 
 find_package(CxxQt QUIET)
diff --git a/tests/basic_cxx_qt/CMakeLists.txt b/tests/basic_cxx_qt/CMakeLists.txt
@@ -24,10 +24,21 @@ set(CMAKE_CXX_STANDARD 17)
 set(CMAKE_CXX_STANDARD_REQUIRED ON)
 
 if(NOT USE_QT5)
-    find_package(Qt6 COMPONENTS Core Gui Qml Test)
+    find_package(Qt6 COMPONENTS Core Gui Qml Test QuickControls2)
+    set(Qt "Qt6")
 endif()
 if(NOT Qt6_FOUND)
     find_package(Qt5 5.15 COMPONENTS Core Gui Qml Test QuickControls2 REQUIRED)
+    set(Qt "Qt5")
+endif()
+
+if(MSVC)
+    # Qt also needs to link against the non-debug version of the MSVC Runtime libraries, see the previous comment.
+    # Note: The Qt:: targets are ALIAS targets that do not support setting properties directly.
+    # We therefore need to resolve the target names to either Qt5 or Qt6 directly.
+    set_property(
+        TARGET ${Qt}::Core ${Qt}::Gui ${Qt}::Qml ${Qt}::Test ${Qt}::QuickControls2
+        PROPERTY MAP_IMPORTED_CONFIG_DEBUG "RELEASE")
 endif()
 
 find_package(CxxQt QUIET)
diff --git a/tests/qt_types_standalone/CMakeLists.txt b/tests/qt_types_standalone/CMakeLists.txt
@@ -24,10 +24,21 @@ set(CMAKE_CXX_STANDARD 17)
 set(CMAKE_CXX_STANDARD_REQUIRED ON)
 
 if(NOT USE_QT5)
-    find_package(Qt6 COMPONENTS Core Gui Qml Test)
+    find_package(Qt6 COMPONENTS Core Gui Qml Test QuickControls2)
+    set(Qt "Qt6")
 endif()
 if(NOT Qt6_FOUND)
     find_package(Qt5 5.15 COMPONENTS Core Gui Qml Test QuickControls2 REQUIRED)
+    set(Qt "Qt5")
+endif()
+
+if(MSVC)
+    # Qt also needs to link against the non-debug version of the MSVC Runtime libraries, see the previous comment.
+    # Note: The Qt:: targets are ALIAS targets that do not support setting properties directly.
+    # We therefore need to resolve the target names to either Qt5 or Qt6 directly.
+    set_property(
+        TARGET ${Qt}::Core ${Qt}::Gui ${Qt}::Qml ${Qt}::Test ${Qt}::QuickControls2
+        PROPERTY MAP_IMPORTED_CONFIG_DEBUG "RELEASE")
 endif()
 
 find_package(CxxQt QUIET)
