Find modules wrapping config modules and help documentation (Was Re: kactivities)

[Stephen Kelly]

Alexander Neundorf wrote:

> -at the top it contains documentation, so you know which variables to use
> for that package

This came up on the buildsystem list in August:

http://thread.gmane.org/gmane.comp.kde.devel.buildsystem/6588/focus=6594

(Context for the cmake list: 
http://thread.gmane.org/gmane.comp.kde.devel.frameworks/101/focus=142)

At the time I tried to implement cmake --help-package Foo, but got drawn 
into other things.

Currently you can use, eg, cmake --help-module FindQt4 to get the 
documentation about that find module.

I'd like cmake --help-package Qt4 to look for FindQt4 in the appropriate 
places, then Qt4Config in the appropriate places, and show the documentation 
from the Config file if that is what is found.

Otherwise, if as you suggest, the documentation is in a Find module and the 
implementation in a Config file (for example like we could do for Qt5), the 
documentation could get out of date compared to the Config file, or the 
documentation could be updated for a Config file that is not yet on the 
users computer.

The other reasons you gave for creating Find modules where Config files 
already exist might be good reasons for it (eg better messages when a 
package is not found), but there would need to be a special doc syntax to 
tell cmake --help-package to look for the real documentation in a config 
file. Eg:

FindQt5Core.cmake:
# -> HelpLocation Config

find_package(Qt5Core NOMODULE)
if (NOT Qt5Core_FOUND)
  message("Something detailed")
endif()

I used a syntax '# -> HelpLocation Config' as the special help forwarding 
syntax, but anything unambiguous (and preferably previously invalid) would 
be fine.

What do you think of that?

Thanks,

Steve.