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

[Alexander Neundorf]

On Thursday 08 December 2011, Stephen Kelly wrote:
> 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

I think you mean this one:
http://thread.gmane.org/gmane.comp.kde.devel.buildsystem/6588/focus=6592

> (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.

This would have first to run CMakeDetermineSystem.cmake, and then it can start 
searching.
Does it also need to run the 32/64 bit detection, to know whether it has to 
look in lib64/ ?

> 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.

Yes, these are issues.
Still it's nice to have the/some documentation available also if the package 
itself is not yet installed.
E.g. my idea with FeatureSummary.cmake is that information about the package 
(e.g. home page, what it is in general) is set in the Find-module, so you get 
that information also if the package is not installed, but it tells you where 
you can get it.

The NOMODULE mode also supports searching a specific version of a package if 
multiple versions are installed. I think this would have to be supported too 
by a --help-package, otherwise it could give you the help for a Config.cmake 
file you didn't want.

> 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?



Alex