[cmake-developers] find_package error wording

[Alexander Neundorf]

On Sunday 19 February 2012, Stephen Kelly wrote:
> On Sunday, February 19, 2012 16:18:00 Alexander Neundorf wrote:
> > On Sunday 19 February 2012, Stephen Kelly wrote:
> > > > The only reason to distribute FindBlub for a CMake-aware project is
> > > > to wrap up find_package NO_MODULE to produce a nicer message, but
> > > > that
> > > > is totally optional.  If a project does want to distribute one for
> > > > reference it should go in the -doc package, not in -dev, and should
> > > > be
> > > > put in share/doc/blub or the distro's equivalent.
> > > 
> > > Good point.
> > 
> > ...but nobody does it or knows it.
> 
> Not many KDE developers at least. But KDE developers aren't really known
> for CMake knowledge anyway. They generally get exposed to as little CMake
> as possible, so I'm not sure they make a good target usecase.

Since 6 years KDE developers are my daily target usecase.
I think they are the biggest existing group of cmake users out there.
I don't think they are very different from other users. Also, what I always 
tried to do is to hide as little cmake stuff from them as possible. It 
shouldn't be seen as "magic" what is happening. All the macros etc. I wrote 
try to be in the same style as the original cmake commands.
Look at how boost is using cmake. They are hiding it. Almost completely. I 
don't like how they use it. Because their users won't have a clue about cmake.

> > > However, your suggestion above seems to indicate that that is exactly
> > > what's being done?
> > > 
> > > That will make this an error:
> > > 
> > > cmake_required_version(2.8.8)
> > > find_package(Qt5Core)
> > > 
> > > Instead this more noisy version would need to be used:
> > > 
> > > cmake_required_version(2.8.8)
> > > find_package(Qt5Core CONFIG_MODE)
> > 
> > Yes.
> > And this is good.
> 
> I disagree :)
> 
> > Then the error message is "Could not find config file". Above it has to
> > guess, and the developers will think that FindQt5.cmake is missing.
> > How should they know that Qt5 ships Qt5Config.cmake files ?
> 
> feature_summary() should tell them that they have to install the
> development package for Qt5.
> 
> Whether they need a Find module or a Config file, they still need to
> install that, so they might as well do it first.

Maybe they have already installed it, so they now think a FindQt5.cmake file 
is missing. It is good to have precise error messages.
 
> > We always had FindFoo.cmake files for everything, including
> > FindQt4.cmake. They will not think "oh, probably a Qt5Config.cmake could
> > not be found". I am 99% sure with this.
> > 
> > Somebody complained on google+ that cmake is a mess.
> > If you don't know what to make of an error message, this won't help the
> > perception.
> 
> Without knowing what specifically they think is a mess, I don't know. I
> expect that wasn't part of the + post. Specifics rarely are :)
> 
> > Just yesterday when I was trying to build parts of kdelibs, and got all
> > the complaints that neither a Find-module could be found nor a config-file
> > could be found, I completely didn't know what the right way to fix them
> > is. Is the Find-module missing, and I should add it, or is the package
> > missing, because it should have installed a config file.
> 
> It is usually easy at least with a package manager too see if libfoo-dev is
> installed.
> 
> That at least reduces the scope of the error to either CMake not finding
> the config file (unlikely if a distro package is used, and if you

See, and with the policy the scope is 100% reduced.
Then I know what's wrong.

> installed it yourself then you might know if you installed it) or
> requiring a
> FindFoo.cmake in your CMAKE_MODULE_PATH (and then you have to figure out
> where it should come from).
> 
> > I would have to check the sources of each of the missing packages to
> > figure out whether it installs a config file or not.
> > 
> > Making this explicit helps.
> > This will also help in making the Config mode more visible, since it will
> > not be "hidden" anymore.
> > You know, people will see
> > find_package(Qt5 CONFIG_MODE)
> > and they might have a look what that "CONFIG_MODE" means.
> > Without it, they won't.
> 
> Maybe.
> 
> The current branch isn't my preferred solution. Even after everyone has a
> firm understanding of what CONFIG_MODE means, we'll still always need it.

Yes.
I don't see a problem with needing an additional keyword.
This is what has happened with more or less all cmake commands: in the 
beginning they had simply a list of arguments, now most of them have two 
modes, the old one, and a new one which is a bit more verbose and more 
powerful.

Compare

find_package(Qt5)
vs.
find_package(Qt5 CONFIG_MODE)

IMO here it's completely "in your face" that "I want a config file".
The much better error message is IMO absolutely worth the one extra argument. 
Now and also in the future.

Alex