Consider a qml module that is attached to an executable and where it makes use of other QML modules. The executable's QML module and the other QML modules will very often share a common resource prefix, but the directory structure in the source and build directories might be different to the TARGET_PATH structure (based on the module URIs). In particular, the executable will often be located in the directory structure at a point that is essentially the resource prefix, but since the executable is a QML module and has its own URI, it should be in a subdirectory below that to match its TARGET_PATH. As this is a very common and intuitive arrangement, we want to support it out-of-the-box. For tooling, the application executable's directory will be used as an implicit import path. That allows the other QML modules to be found. When running the executable, it might be relying solely on the compiled-in resources, so we need to add the resource prefix to the import path. We know the resource prefix of the executable's own QML module, so we should be able to automatically add that as an import path instead of requiring projects to explicitly add this themselves. This will remove a point of friction especially for new users setting up their first few QML-based applications.
To make that process automatic, the qml engine could try to look up a metadata file in a predefined qrc path that is private to Qt, e.g. qrc:/qt-project.org/qml_engine_private/app_metadata.json. This path will always be the same and does not depend on any project-specific details. Only the contents of the metadata file will be project-specific. The presence of this metadata file in the resources must be optional, no error or warning should be emitted if it is not present.
If such a file exists and it defines a resource prefix as described above, that will automatically be added as an additional import path by the QML engine in its constructors:
The CMake qt_add_qml_module() call will generate the above-mentioned app_metadata.json file and add it to the resources when it is given an executable target for the QML module.