`find_package(Qt6Core)` is broken - dependency finders should be `include`d directly

The following works with Qt5:

find_package(Qt5Core)

assuming the Qt5Core package config files are available.

In general the reasonable assumption for any user of CMake wishing to use a library which provides package config files is for something so simple to work by either finding a system package or finding the package in the CMAKE_PREFIX_PATH.

See https://cmake.org/cmake/help/latest/guide/using-dependencies/index.html#libraries-providing-config-file-packages

The following does not work on linux:

find_package(Qt6Core)

Part of the output is:

  By not providing "FindAtomic.cmake" in CMAKE_MODULE_PATH this project has
  asked CMake to find a package configuration file provided by "Atomic", but
  CMake did not find one.

  Could not find a package configuration file provided by "Atomic" with any
  of the following names:

    AtomicConfig.cmake
    atomic-config.cmake

  Add the installation prefix of "Atomic" to CMAKE_PREFIX_PATH or set
  "Atomic_DIR" to a directory containing one of the above files.  If "Atomic"
  provides a separate development package or SDK, be sure it has been
  installed.
Call Stack (most recent call first):
  /home/steveire/dev/src/qtbase/build/prefix/lib/cmake/Qt6Core/Qt6CoreDependencies.cmake:17 (find_dependency)
  /home/steveire/dev/src/qtbase/build/prefix/lib/cmake/Qt6Core/Qt6CoreConfig.cmake:39 (include)
  CMakeLists.txt:6 (find_package)


-- Configuring incomplete, errors occurred!
See also "/home/steveire/dev/src/playground/qt/build/CMakeFiles/CMakeOutput.log".

The problem is that find_package(Qt6Core) leads to find_package(Atomic) where the required FindAtomic.cmake is located in <qtprefix>/lib/cmake/Qt6/FindAtomic.cmake.

I can solve the problem by adding <qtprefix>/lib/cmake/Qt6 to my CMAKE_MODULE_PATH. Users should not have to modify their CMAKE_MODULE_PATH in order for find_package(Qt6Core) to work.

Modifying CMAKE_MODULE_PATH inside the Qt6 config file packages (as Qt6Config.cmake does, which is why find_package(Qt6 COMPONENTS Core) does not fail in the same way) is also not the answer. CMAKE_MODULE_PATH is a variable which the user should modify for themselves.

Modifying it on behalf of the user is hostile to the user because it means that FindFoo.cmake which the user maintains themselves will no longer be found if a file by the same name exists in <qtprefix>/lib/cmake/Qt6. We knew this years ago, which is why for example extra-cmake-modules does not modify the variable on the users behalf: https://cgit.kde.org/extra-cmake-modules.git/tree/docs/manual/ecm-find-modules.7.rst?h=ebc874095b4d78bc6a6e71da8f4ea3bed31713f9

Populating CMAKE_MODULE_PATH on the users behalf in a config-file package is a bug and a step backwards in best practices for creating cmake config-file packages. It means for example that the order of a users find_package calls is relevant. The order of find_package calls should not be relevant.

Assuming a user has their own FindMySql.cmake which must be used in their build,

find_package(Qt6Core)
find_package(MySql)

and

find_package(MySql)
find_package(Qt6Core)

should work the same and find the users FindMySql.cmake. That requires that finding Qt6 does not modify the users CMAKE_MODULE_PATH.

So, what's the alternative of populating CMAKE_MODULE_PATH? There is no need to use the find_package command at all because we know the relative location of the FindFoo.cmake files which must be used. So, you can just use include:

include(${CMAKE_CURRENT_LIST_DIR}/../Qt6/FindAtomic.cmake)

You should then also consider renaming those files.