[CMake] FindXXX.cmake specification inconsistency

[r.koebler at yahoo.de]

hi,

currently, I know 3 different specifications, how FindXXX.cmake files
should look like:
- the shipped modules in /usr/share/cmake-2.4/Modules/
- the readme.txt in      /usr/share/cmake-2.4/Modules/
- CMake_HowToFindInstalledSoftware.html in the wiki

unfortunately, these specifications are inconsistent! and the
sentence "We would like all FindXXX.cmake files to produce consistent
variable names." in the readme.txt is currently really ridiculous...

so please tell me which is the "right" way to write FindXXX.cmake files.
after this, the documentation should be corrected.


here are the details:


_INCLUDE_DIR/_INCLUDE_DIRS/_INCLUDES and _LIBRARY/_LIBRARIES
=============================================================

which variable names should be used for the include-directory and
libraries by FindXXX.cmake?

- CMake_HowToFindInstalledSoftware.html says:

    <name>_INCLUDE_DIR (or <name>_INCLUDES)
    <name>_LIBRARY (or <name>_LIBRARIES)

    and in the PNG_ example, PNG_LIBRARY and PNG_LIBRARIES are mixed.

- readme.txt says:
    
    Please use the following consistent variable names for general use.

    XXX_INCLUDE_DIRS    The final set of include directories listed in
                        one variable for use by client code.
                        This should not be a cache entry.
    XXX_LIBRARIES       The libraries to link against to use XXX. These
                        should include full paths.
                        This should not be a cache entry. 

    If XXX is a library, then XXX_LIBRARIES, should also be defined,
    and XXX_INCLUDE_DIRS should usually be defined


    The following names should not usually be used in CMakeLists.txt
    files, but they may be usefully modified in users'  CMake Caches
    to control stuff.

    XXX_LIBRARY         Name of XXX Library. A User may set this and
                        XXX_INCLUDE_DIR to ignore to force non-use of XXX.
    XXX_YY_LIBRARY      Name of YY library that is part of the XXX system.
                        It may or may not be required to use XXX.
    XXX_INCLUDE_DIR     Where to find xxx.h, etc.  (XXX_INCLUDE_PATH was
                        considered bad because a path includes an actual
                        filename.)
    XXX_YY_INCLUDE_DIR  Where to find xxx_yy.h, etc.

- shipped modules:
    
    they use all variants. all of _INCLUDE_DIR, _INCLUDE_DIRS,
    _INCLUDES, _LIBRARY and _LIBRARIES are used.


I suggest to define exactly 1 variant which should be used.
so, which is the "right"/"better" one ?
- <name>_INCLUDE_DIRS and <name>_LIBRARIES
or
- <name>_INCLUDE_DIR and <name>_LIBRARY

this one then should be used *everywhere*.


additional question:
readme.txt mentions both XXX_LIBRARIES and XXX_LIBRARY, and bot
XXX_INCLUDE_DIRS and XXX_INCLUDE_DIR. but how is that meant to be?
how should this be handled, since the user-configurable
XXX_INCLUDE_DIR and XXX_LIBRARY are not in FindXXX.cmake??


and I rally think that a *complete example* (or template) for a
FindXXX.cmake file is necessary to show how the documentation
is meant...


QUIET
=====

readme.txt is wrong here. It says:

    If the QUIET option is given to the command it will set the variable
    XXX_FIND_QUIETLY to true before loading the FindXXX.cmake module. If
    this variable is set the module should not complain about not being
    able to find the package and should never issue a FATAL_ERROR.
                                        ^^^^^^^^^^^^^^^^^^^^^^^^^

This would mean that FIND_PACKAGE(... QUIET REQUIRED ...) would
*never* issue a FATAL_ERROR, not even if the package is not found!

I don't think that this is a sensible behaviour. And the shipped modules
of course raise a FATAL_ERROR in these cases.


Cache entries
=============

readme.txt says:

    XXX_INCLUDE_DIRS    ... This should not be a cache entry.
    XXX_LIBRARIES       ... This should not be a cache entry. 

But as far as I know, *NO* module does it this way. FIND_LIBRARY and
FIND_PATH automatically add the variables to the cache, and no module
removes them again. (besides, removing them even isn't possible, so
you would have to use FIND_LIBRARY etc. with a temporary variable,
hide this variable, and set XXX_LIBRARIES to the value of this
hidden cache variable...)

So, should these variables be in the cache or not?


additionally:

  For tidiness's sake, try to keep as many options as possible out of the
  cache, leaving at least one option which can be used to disable use of
  the module, or locate a not-found library (e.g. XXX_ROOT_DIR).

the shipped modules also don't stick to this.



regards,
Roland