[CMake] FindXXX, XXXConfig and UseXXX

[Brad King]

Fernando Cacciola wrote:
> XXXConfig.cmake should be generated by the cmake script that configures 
> the library and it should contain the settings specific to that 
> configuration (such as source and binary folders, detected third party 
> dependencies, needed flags, etc)

Correct.

> FindXXX.cmake should search a user's system for an instance of 
> XXXConfig.cmake (using XXX_DIR and defaults paths). If it finds it, it 
> should load that XXXConfig.cmake.

No, see below.

> UseXXX.cmake should set include directories, libraries, compiler and 
> linker flags, etc, based on the settings defined in a XXXConfig.cmake 
> that must has been processed already.
> 
> XXXConfig.cmake should define a XXX_USE_FILE with the full path to the 
> UseXXX.cmake file.
> 
> XXX users would load XXX in their own programs via:
> 
> 
> find_package(XXX)
> 
> if ( XXX_FOUND )
> 
>  include( ${XXX_USE_FILE} )
> 
> endif()

Correct.

> If FindXXX.cmake is found in the paths specified by CMAKE_MODULE_PATH, 
> it is loaded by find_package(XXX).

There should not be a FindXXX.cmake at all.

> If not, but the user sets XXX_DIR to some binary folder for some 
> installation of XXX, the above code works still by loading 
> XXXConfig.cmake directly (witout going through FindXXX..cmake)
> 
> Is all that correct?

Yes.

> Is so, how should FindXXX and UseXXX distributed?

UseXXX.cmake should come with the project next to XXXConfig.cmake.

The whole idea of creating a package with XXXConfig.cmake is to not have 
to have a FindXXX.cmake module at all.  The find_package command is 
supposed to find XXXConfig.cmake automatically, but it is not very good 
at finding the files as of CMake 2.4 so the user has to set XXX_DIR 
alot.  CMake 2.6 will have a much better find_package:

   http://www.cmake.org/Wiki/CMake_2.6_Notes#Packages

You should install XXXConfig.cmake and UseXXX.cmake in the XXX install 
tree under one of the locations mentioned in the find_package command 
documentation (as of CMake 2.6).  For example, a project on UNIX might 
install

   <prefix>/lib/xxx-1.2/XXXConfig.cmake

Someone using CMake 2.4 will have to set XXX_DIR to that directory by 
hand, but anyone using CMake 2.6 will have the file found automatically. 
  Versioning is also supported in the CMake 2.6 find_package.  See the 
nots above.

-Brad