[cmake-developers] Preparing for 2.8.11-rc1

[Alexander Neundorf]

On Wednesday 06 March 2013, Brad King wrote:
> On 3/5/2013 5:05 PM, Stephen Kelly wrote:
> > Stephen Kelly wrote:
> >> So, I think it's mature enough for release now, yes.
> > 
> > It might be worth documenting it a bit more prominently though...
> > 
> > Any opinion on this?
> 
> I think the patch can be simpler:
> 
> -    "through variables documented by the package itself.  "
> +    "through variables and imported targets documented by the package
> itself.  "
> 
> IMO it is up to the package to advertise imported targets
> in its documentation.

I think it's cool and a really good thing that imported targets can do more 
stuff now.  It should also be documented well so that people are aware that 
the results if find_package(SomePackage) or no longer necessarily only file 
paths and directories, but also imported targets.

But I think it's a step backward to use imported target names directly.

One thing cmake users do complain about regularly is that they can't rely on 
what the names of the variables defined after
find_package(SomePackage)
are, even though there are guidelines for the naming in readme.txt.
The results may be
SOMEPACKAGE_LIBS, SOMEPACKAGE_LIBRARY, SOMEPACKAGE_LIBRARIES,
SomePackage_LIBS, SomePackage_LIBRARY, SomePackage_LIBRARIES

This is the one single strongest complaint I hear about using find_package().

We should try to fix this complaint by making the Find-modules/Config-files 
comply as good as possible to readme.txt, which we agreed upon that the 
correct name would be SomePackage_LIBRARIES.

If we concentrate on that, using find_package() will become easier, since the 
variables will follow the standard naming.
If we reach this, we'll have real progress, and we'll have made cmake really 
easier to use.


If we now instead of following that strategy, start to recommend that packages 
may also document their exported/imported targets, we go in the opposite 
direction.
When doing
find_package(SomePackage)
the user now again will have to read the documentation, just to find out 
whether he should use SomePackage_LIBRARIES or the imported target 
"somepackagelib" directly.
So there would be two competing "standards" then ;-)
Additionally, currently there are no guidelines for how exported/imported 
targets should be named, so besides having to find out whether targets should 
be used directly, they would have to read the documentation to find out how 
those targets are named.

If we recommend using imported target names directory, readme.txt should 
contain guidelines for how to name the targets and namespaces.


Also, using imported target names directly removes the isolation layer between 
in-project developers and how they name their targets, and users of their 
projects, which is by now provided by the variables set in Find-
modules/Config-files.


Another idea would by to have a new, additional "standard" variable
SomePackage_TARGET or something like this. This would keep the advantage of 
the isolation layer, and the advantage of the standard naming, it would also 
make it visible that the thing is a target and may have include dirs attached, 
the downside would still be that the user has to find out whether he is 
supposed to use SomePackage_TARGET or SomePackage_LIBRARIES.


Alex