Generate qmldir files for extra directories with QML files

Those qmldir files contain only a prefer directive for the canonical
resource location of the module. This way, any time another component
from the implicit import is requested, it will not be located in the
extra directory (where it probably doesn't exist), but instead in the
canonical location.

Since people may have manually written qmldir files with different
content in those places, or worse, relied on the other components to be
inaccessible, we need a new policy to opt into this.

Fixes: QTBUG-111763
Change-Id: If236feb7dd7c8d704b813ea56482ff758799d0a7
Reviewed-by: Fabian Kosmale <fabian.kosmale@qt.io>

2 files changed, 40 insertions, 0 deletions

diff --git a/src/qml/doc/src/cmake/policy/qtp0004.qdoc b/src/qml/doc/src/cmake/policy/qtp0004.qdoc
new file mode 100644
index 0000000000..9d3428e52b
--- /dev/null
+++ b/src/qml/doc/src/cmake/policy/qtp0004.qdoc
@@ -0,0 +1,34 @@
+// Copyright (C) 2024 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
+
+/*!
+\page qt-cmake-policy-qtp0004.html
+\ingroup qt-cmake-policies
+
+\title QTP0004
+\keyword qt_cmake_policy_qtp0004
+
+\summary {Extra directories with QML files in a QML module need extra qmldir files.}
+
+This policy was introduced in Qt 6.8. It causes the build system to generate
+an extra qmldir file for each additional directory that contains QML files in
+a QML module.
+
+Enabling this policy ensures that the implicit import of each of the QML
+components in your module is the same as the module itself. This means that
+all the components can see each other without explicitly importing the module.
+
+The \c OLD behavior of this policy is that a qmldir file is only generated for
+the root directory of a module.
+
+The \c NEW behavior of this policy is that for each directory with QML files in
+a module a separate qmldir file is generated.
+
+Qt 6.8 issues warnings if you do not explicitly set the policy.
+
+\qtpolicydeprecatedbehavior
+
+\sa qt_policy, {qt6_standard_project_setup}{qt_standard_project_setup()},
+    qt_cmake_policies, qt_add_qml_module
+
+*/
diff --git a/src/qml/doc/src/cmake/qt_add_qml_module.qdoc b/src/qml/doc/src/cmake/qt_add_qml_module.qdoc
index 94a7a9d67f..4ca7635b9c 100644
--- a/src/qml/doc/src/cmake/qt_add_qml_module.qdoc
+++ b/src/qml/doc/src/cmake/qt_add_qml_module.qdoc
@@ -171,6 +171,12 @@ The \l OUTPUT_DIRECTORY argument determines where the \c qmldir and typeinfo
 files will be written to. If the QML module has a plugin, that plugin will also
 be created in the same directory as the \c qmldir file.
 
+If \l{QTP0004} policy is set to \c NEW, for each further directory that contains
+\c{.qml} files another \c qmldir file is generated. These extra \c qmldir files
+merely redirect to the module's base directory via a \c prefer directive. This
+is so that all the QML components in a module can access each other, no matter
+which directory they are stored in.
+
 If using a statically built Qt, the backing target's \c{.qml} files will be
 scanned during the CMake configure run to determine the imports used by the
 module and to set up linking relationships (the \c{NO_IMPORT_SCAN} keyword