Qt 6 Build System: Transitioning from qmake to CMake for Repeatable Environments

Answer the Question First

What is the recommended strategy to ensure find_package(Qt6) resolves to the same toolchain across different machines without hard‑coding paths?

• Pin the Qt installation via CMAKE_PREFIX_PATH, not in CMakeLists.txt.
• Use a CMakePresets.json (or qt‑cmake wrapper) to inject that prefix at configure time.
• Keep the same environment variable (e.g. QT_DIR or QTDIR) pointing to the kit root on every developer workstation and CI runner.
• Verify by printing Qt6_VERSION and inspecting CMakeCache.txt after configuration.

How does the qt-cmake wrapper specifically resolve toolchain discovery compared to a plain cmake call?

• It automatically sets CMAKE_PREFIX_PATH to the kit’s lib/cmake directory.
• It may also add a platform‑specific toolchain file and generator defaults (e.g. -G Ninja).
• Because the wrapper lives inside the kit, invoking qt‑cmake pins both the Qt version and the compiler kit, eliminating the need to pass explicit paths.
• In contrast, a plain cmake call relies on the user to provide the correct prefix or toolchain file via command‑line options or environment variables.

Step‑by‑Step Strategy

1. Choose a single Qt kit for the team. Install it on every machine and CI runner.
2. Set an environment variable. Export QT_DIR (or QTDIR) to the kit root. Example:

   export QT_DIR=/opt/Qt/6.5.1/gcc_64

3. Create CMakePresets.json in the project root. Add a preset that uses the variable:

   {
     "version": 3,
     "configurePresets": [
       {
         "name": "default",
         "hidden": false,
         "description": "Use the team Qt kit",
         "generator": "Ninja",
         "cacheVariables": {
           "CMAKE_PREFIX_PATH": "$env{QT_DIR}/lib/cmake"
         }
       }
     ]
   }

4. Configure and build. From the project root run:

   cmake --preset default -S . -B build
   cmake --build build

5. Verify repeatability. In build/CMakeCache.txt look for:

   Qt6_DIR:PATH=/opt/Qt/6.5.1/gcc_64/lib/cmake/Qt6

   and confirm Qt6_VERSION matches expected.

Using qt‑cmake Instead of CMake

When you run qt-cmake from the kit’s bin directory, it automatically injects the same CMAKE_PREFIX_PATH and may set additional defaults. The equivalent plain CMake command would be:

cmake -S . -B build -DCMAKE_PREFIX_PATH=/opt/Qt/6.5.1/gcc_64/lib/cmake -G Ninja

Thus, qt-cmake is a convenience wrapper that eliminates the need to remember those options, but the underlying discovery mechanism is identical.

Common Pitfalls and Quick Checks

• If find_package(Qt6) finds a different version, clear CMakeCache.txt or use cmake -U Qt6_* before reconfiguring.
• On Windows, ensure PATH contains the kit’s bin directory so that qt-cmake can be found.
• CI runners should install the same Qt kit and export QT_DIR before invoking CMake.

Ask for Missing Diagnostic Detail

To fine‑tune this recommendation, please confirm the CMake version in use (e.g. 3.27+ is required for full preset support) and whether you are cross‑compiling (in which case a toolchain file might be needed).