P3: Somewhat important
For QML modules, we generally recommend that all QML files are directly located in the module's root folder. This has the benefit that each file will find the module via its implicit import. Not following this rule might lead to types missing altogether. Worse, it might lead to a singleton being treated as a non-singleton as it's in the same folder, but that folder doesn't contain a qmldir; and then we just do a directory import.
However, while we have a good reason to promote a flat structure, such a structure has shortcomings. There are reasons for having nested folder, among them:
- separating QDS generated ui.qml files from QML file with application logic
- similarly, separating QtQuickEffect maker generated files
- grouping logically related sets of files (e.g. samegame's levels)
- putting all singletons into their own folder
There's also file selector's, but let's ignore that use case for now.
Currently, qt_add_qml_module won't stop you from creating such a structure, but it also doesn't help you to avoid the footguns mentioned before. However, before we can provide more help for this use case, we first need to decide which solution we should promote:
- insist that all files (or at least, all QML files) are in the top-level folder
- allow full flexibility in the source folder, but rearrange the files in the build directory/during deployment to flatten the structure
- allow full flexibility in the source folder; auto-generate qmldirs to ensure that the implicit import is still working. If we put "import mymodule" into a directory qmldir file of each subdirectory in the module, you'll get the same effect with the implicit import as if all files were in the toplevel folder (compare module_nested.targ.gz)
- allow full flexibility in the source; warn users that they are on their own (and maybe check that they explicitly import their module in each QML file)
- Make it easier to create more/nested QML modules, so that you don't have to spread one module over several directories anymore