Background

Based on many support requests and forum posts, a common cry for help is, "My project obviously runs just fine... so why does Qt Creator say that it can't find my imports?!"

I've encountered a variety of "problematic" project structures (summarized at QTBUG-137199). There is a simple workaround that helps all of these cases, described below.

Existing mechanisms we can take advantage of

• When we set a global QT_QML_OUTPUT_DIRECTORY, the project-defined QML modules get generated into that directory with the same structure as :/qt/qml/
• ${CMAKE_BINARY_DIR} is currently a default import path for qmllint and qmlls

Assumptions

• Most projects create custom QML modules using unique URIs. Duplicated URIs are uncommon.
• Most developers don't care/think about the exact OUTPUT_DIRECTORY's used by their modules.

Core Proposal

Idea

If QML modules are organized in the build folder just like how they're organized in :/qt/qml, then the QML tools can see the same thing that the QQmlEngine sees at runtime. This means: No more discrepancy between runtime and build-time warnings.

Possible Implementation

Add a new policy which applies this by default:

set(QT_QML_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR})

Core Benefit

qmllint and qmlls will see all QML modules created via qt_add_qml_module() out-of-the-box, regardless of the project structure (see Scenario 3 at QTBUG-137199). Thus, developers won't see warnings about finding imports even if they aren't familiar with QML best practices.

Result: Less confusion/frustration for people who're trying to start using QML modules, less calls for help, and more time for everyone to do more useful things.

Limitations and further considerations/improvements

• We do support certain scenarios where the same URI is used by more than 1 QML module in the same project (e.g. a project with a "real module" + a "mock module"). In such cases, setting QT_QML_OUTPUT_DIRECTORY will cause configuration errors due to clashing OUTPUT_DIRECTORY paths. Projects with this use-case need to opt-out of this proposed policy.
• Unlike qmllint/qmlls, ${CMAKE_BINARY_DIR} is not currently passed to qmlsc as a default import path. Users who forget to add DEPENDENCIES TARGETS will silently miss out on achievable optimizations.
  • QTBUG-141554 calls for unifying the import paths for qmllint and qmlsc, but let's put this aside for now out of an abundance of caution.
• Generating modules into the build folder's root feels a bit messy. Perhaps we should use a subfolder instead (e.g. ${CMAKE_BINARY_DIR}/.qmlstaging/) and point the QML tools there?