[Cmake] Making the cmake FindXXX.cmake files more consistent

[Amitha Perera]

On Fri, Aug 16, 2002 at 01:50:09PM -0400, Brad King wrote:
> The module "FindFOO.cmake"  should
> define:
> 
> FOO_FOUND        = 1 for found, 0 for not found.
> FOO_INCLUDE_DIRS = Directories to add to compiler's header search path.
> FOO_LIBRARY_DIRS = Directories to add to linker's library search path.
> FOO_LIBRARIES    = Libraries to link.
> FOO_DEFINITIONS  = Preprocessor definitions to add for sources using FOO.
> FOO              = The path to the foo executable.

This list of variables brings a subtle assumption that I would rather
not have: the client of a library must specify the *directories* for
any dependent libraries.

Consider vil (vxl's image library). vil depends on libraries such as
jpeg, tiff, and png. We have somewhere

  TARGET_LINK_LIBRARIES( vil ${JPEG_LIBRARIES} ${PNG_LIBRARIES} )

In the executable, we have

  TARGET_LINK_LIBRARIES( myexec vil )

All works well, without the need for LINK_DIRECTORIES, because
JPEG_LIBRARIES is defined as /usr/local/lib/libjpeg.so. That is, the
full path is already embedded in the dependency. If it weren't, the
client would need to do a

  LINK_DIRECTORIES( ${JPEG_LIBRARY_DIRS} )

and much of the benefit of the dependency analysis is lost.

I believe the even works for separated libraries. For example,

  TARGET_LINK_LIBRARIES( vil "-L/usr/local/lib -lpng -lz" )

and

  TARGET_LINK_LIBRARIES( myexec vil )

will properly link against vil, png and libz, without the need to
specify additional directories.

I think, therefore, that the FOO_LIBRARY_DIRS should not exist. That
path should be embedded in FOO_LIBRARIES. Now, it may be somewhat
accidental that this works. If so, I think CMake should be made so
that this is not accidental. The less the client needs to know about
implementation details of a library, the better.

> I also propose that none of these variables should be a cache entry.
[...]
> Modules should never pollute the variable namespace.  All variables and
> cache entries used in module FOO should start with FOO_.

I agree with this. The fewer entries in the cache, the better. And
less pollution is better.


> Modules should never do anything that affects the build directly, such as
> ADD_DEFINITIONS, LINK_LIBRARIES, LINK_DIRECTORIES, etc.  When the
> CMakeLists.txt author is ready to use the library, the variables provided
> by the module can be used as arguments to the appropriate commands:
> 
> ADD_DEFINITIONS       ( ${FOO_DEFINITIONS} )
> INCLUDE_DIRECTORIES   ( ${FOO_INCLUDE_DIRS} )
> LINK_DIRECTORIES      ( ${FOO_LIBRARY_DIRS} )
> TARGET_LINK_LIBRARIES ( myExecutable ${FOO_LIBRARIES} )

Perhaps we should provide a corresponding UseFOO module that does the
first three (two, with my suggestion above)? Saves a _little_ bit of
typing, and may provide a convenient place for funny libraries. For
example, libpng needs special definitions depending on shared or
static libraries, client code or library code, etc.

> This will be fine for CMake 1.6 as long as the modules maintain backward
> compatability with the current modules.  This means only that the old
> names have to be kept, but deprecated.

But how long must the ugliness remain? :-) Perhaps we could use the
CMake minimum required version to conditionally do the backward
compatible stuff.

Amitha.