[cmake-developers] Recommended use of imported targets...

[Alexander Neundorf]

On Thursday 28 February 2013, Brad King wrote:
> On 02/27/2013 04:37 PM, Alexander Neundorf wrote:
> > 1) we should continue to recommend to use the variables (which will now
> > be set to the name of the target). In case of typos, this will lead to
> > an empty variable (as it did before with Find-modules), and undefined
> > references when linking. This is at least no regression.
> > Also, it shields users somewhat from potential renaming of the imported
> > targets.
> 
> This is up to individual projects based on their own requirements.
> Some interface may be more stable than others.  I do not think any
> general recommendation can be made without lots of contingencies.

...
> There is only so much CMake can do.  There are plenty of places
> that typos in CMake code can lead to breakage at build time.

but here the situation becomes worse than before.

A variable is a container of information.
If a developer uses a variable, set by a Find-module or a Config.cmake file, 
he is using information set by the author of the Find-module or the 
Config.cmake file.
If the developer enters the target name directly, he enters the information, 
hoping that it will be correct.

I am talking from the POV not of the developer using Foo itself, but from a 
user trying to just build the project.
Using a variable, it is obvious when looking at the cmake code:
tll(hello ... ${Foo_LIBRARIES} )

using a literal, it is not:
tll(hello ... foo )


There is a big difference between in-project target names, and imported target 
names.
Bad in-project target names more or less cannot happen. I mean, the code 
immediately doesn't build for the developer who entered the wrong name, so he 
will not commit or even release the code.

Imported target names can be bad, e.g. if the user has a different version of 
the package in question. Or of the find_package() result is not checked 
properly. And as shown above, from just looking at the cmake code it is not 
obvious whether this is a target or a library.

Of course exported target names must not change, the same way as variables 
documented for a Find-module must not change, in order to stay source 
compatible. Still the difference is that if you use a wrong variable, you 
don't get misleading errors (to start looking for a libfoo.so), but undefined 
references, which in general means some library is missing from the link 
command, as opposed to the library exists in the link command, but does not 
exist on disk. 


So since yesterday I think I'll stay with recommending using and documenting 
PackageName_LIBRARIES variables, and keep the targets internal.

Alex