Make it easier for newcomers to understand and use the default QQmlEngine import paths

Consider the example at https://doc.qt.io/qt-6/cmake-build-reusable-qml-module.html

Project structure:

├── CMakeLists.txt
└── example
    └── mylib
        ├── CMakeLists.txt
        ├── mytype.cpp
        ├── mytype.h

Subdirectory's CMakeLists.txt contains:

qt6_add_qml_module(mylib
    URI example.mylib
    VERSION 1.0
    SOURCES
        mytype.h mytype.cpp
)

If we follow this example to implement a minimal QML module, then the path to the module's qmldir file will be ":/example/mylib/qmldir"

Things that are not clear and can cause confusion

import example.mylib will normally fail to find the module, unless we call engine.addImportPath(":/") first. To add to the confusion, omitting engine.addImportPath(":/") can seem to work just fine on the development machine but fail mysteriously when deployed. This is because CMake puts a copy of the QML module in the same build folder as the executable, allowing the QML engine to import the module from qApp->applicationDirPath() (which is a default import path).

Furthermore, the relationships between URI, RESOURCE_PREFIX, and import path is not clearly documented anywhere. Some aspects are described at https://doc.qt.io/qt-6/qt-add-qml-module.html#resource-prefix but this section is only really comprehensible to someone who already has a decent understanding of the QML engine.

Suggestions (Updated according to comments in January)

• Add the resource root directory (":/") as a default QQmlEngine import path so that users don't need to add it manually
• Document that the default RESOURCE_PREFIX is / at https://doc.qt.io/qt-6/qt-add-qml-module.html#resource-prefix
• Doc: Update the following pages to promote AUTO_RESOURCE_PREFIX:
  • https://doc-snapshots.qt.io/qt6-dev/cmake-build-reusable-qml-module.html
  • https://doc-snapshots.qt.io/qt6-dev/qtquick-bestpractices.html
• Doc: Add a simple, beginner-friendly section to https://doc.qt.io/qt-6/cmake-build-qml-application.html which describes how the example URI results in the final resource path

• Qt Creator: The "New Project" wizard should add "6.5" as a possible "Minimum required Qt version". If 6.5 is selected, then the generated template should contain AUTO_RESOURCE_PREFIX