[cmake-developers] find_package module-only policy (was: find_package error wording)

[Brad King]

On 2/19/2012 10:54 AM, Alexander Neundorf wrote:
> I don't see a problem with needing an additional keyword.
>
> find_package(Qt5)
> vs.
> find_package(Qt5 CONFIG_MODE)

Remember we decided on

   find_package(Qt5 CONFIG)

instead which reads better.

I'm not opposed outright to this syntax in the future.  However, I
think the policy as proposed is too aggressive for transition.  It
will create a warning on every config-mode find_package call that
exists in any project release to date.  This penalizes everyone who
was proactive enough to have read, understood, and used the more
powerful config-mode.  The warning will remain in all the old releases
of their projects forever and make it look like they did something
wrong.  Furthermore, to avoid the warning in new versions they will
have to add extra decoration to their calls, and during the transition
period that decoration will be spelled NO_MODULE which is pretty ugly
when not in a Find module.

----------------------------------------------------------------------

We need a smoother transition plan.  It must not create warnings
in old projects.  Here is a plan I can accept:

(1) Improve the current ambiguous error message (see below).

(2) Add the explicit MODULE and CONFIG mode keywords.  Warn if they
are used and the current minimum CMake version is not >= 2.8.8 so that
people do not add them in places that will break old versions.

(3) Add two possible AUTHOR_WARNING messages in the case that no mode
keyword or Find module is present:

  - If the current minimum CMake required version is >= 2.8.8 then
    warn that MODULE or CONFIG should be used.

  - Otherwise if CMAKE_FIND_PACKAGE_WARN_NO_MODULE is set to true then
    warn that NO_MODULE should be used to get the config mode.

The first one will not appear in old projects but will become more
common over time.  The second one can be used in projects (KDE) to get
the warning even before bumping the min required version to 2.8.8.

In either case the warning should appear even when the package
configuration file is found.  This will convince developers to
add the keyword because it is required to avoid the warning.

(4) In the future, e.g. CMake 3.0.0, add the policy if necessary.  At
that point it will be able to leverage the new features added above so
that the NEW behavior is clean.

----------------------------------------------------------------------

Now to improve the error message (step 1 above).  The current
ambiguous error message originated here:

   http://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=53d9d84f

Prior to that it only talked about the package config file.  It was
only in an attempt to help developers debug their CMAKE_MODULE_PATH
that the ambiguous message was added, but at the cost of making it
unclear to users what is needed.

The message needs to be clear to users and developers, but with a
preference for users because it will appear even in properly written
projects when the package config file is not found.

We can extend what I previously proposed:

  CMake Error at CMakeLists.txt:7 (find_package):
    No package configuration file for "ecm" found by names:

      ecmConfig.cmake
      ecm-config.cmake

    Add the installation prefix of "ecm" to CMAKE_PREFIX_PATH or
    set "ecm_DIR" to a directory containing one of the above files.
    If "ecm" provides separate development package or SDK be sure
    it has been installed.

    If "ecm" does not provide a package configuration file then
    this project must ensure that a Findecm.cmake module lies in
    its CMAKE_MODULE_PATH before calling find_package.

The last paragraph should not appear with NO_MODULE or CONFIG.

If no Find module is available but MODULE was used then one can
write a very detailed message about setting CMAKE_MODULE_PATH.
The future policy in step 4 above can make this the default
in its NEW behavior.

-Brad