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

[Brad King]

Ian,

> Our module files aim to follow the following conventions. FindFOO.cmake
> defines HAS_FOO, and FOO_INCLUDE_PATH, FOO_LIBRARY_PATH It also defines
> FOO_LIBRARIES containing all the libraries needed to use foo (e.g. for
> qt on windows it defines "imm32.lib ws2_32.lib qt.lib") Finally, it does
> an ADD_DEFINITIONS( -DHAS_JPEG )

Getting this consistency is a great idea!  It looks like you have a good
start, and we will be happy to accept your contribution.

I propose that all modules define the variables below.  If they are not
needed, they can be left undefined, and CMake will automatically replace
their expasion with the empty string.  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.

If FOO_FOUND is 0, all other variables should be set to the empty string
or left undefined.  FOO_INCLUDE_DIRS, FOO_LIBRARY_DIRS, and FOO_LIBRARIES
should be semi-colon separated lists if they include more than one entry.

I also propose that none of these variables should be a cache entry.
Instead, the module should define the minimum cache entries needed to set
the rest of the variables.  The cache entries should have a different name
from the other variables, and should make it clear to the CMake GUI user
what its value should be.  For example, if FindFOO is looking for
libfoo.a, it could have cache entry FOO_PATH_TO_LIBFOO.  Once this has
been set by the user, the other values can be calculated with relative
paths.

Modules should never pollute the variable namespace.  All variables and
cache entries used in module FOO should start with FOO_.  This is why I
changed "HAS_FOO" to "FOO_FOUND" for this proposal.

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} )

> Do you think this would be a worth doing for CMake1.6? Are VTK prepared
> to deal with all the changes?

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.

Also, we need to finally pick a standard for naming directory variables.
Some places use "PATH" while others use "DIR".  One should be chosen as
the convention.  My opinion is that "DIR" should be used when the name
refers to a directory, and "PATH" should be used when the name refers to a
file.

-Brad