[CMake] Create an XXXConfig.cmake file

[Michael Wild]

On 19. Nov, 2009, at 16:24 , Michael Jackson wrote:

> So, there are a few of us quickly port the HDF5 1.8 code to CMake.  
> I'm thinking that we should put in an HDF5Config.cmake file for  
> other projects use. Simple question:
>
>  What goes in one of those? Is there a tutorial somewhere? Where  
> does the file get installed into? What does the consumer of the file  
> need to put into their cmake files?
>
>  And what version of CMake does all that apply to?
>
> Thanks
>

That depends on how complicated your stuff is. Most likely it will be  
something like this:

# Tell the user project where to find our headers and libraries
set( HDF5_INCLUDE_DIRS "@CMAKE_INSTALL_PREFIX@/include" )
set( HDF5_LIBRARIES "@CMAKE_INSTALL_PREFIX@/lib")

# Our build settings and library dependencies
include( "@CMAKE_INSTALL_PREFIX@/share/cmake/HDF5LibraryDepends.cmake" )
include( CMakeImportBuildSettings )
cmake_import_build_settings( "@CMAKE_INSTALL_PREFIX@/share/cmake/ 
HDF5MBuildSettings.cmake" )


Of course, you must create the HDF5LibraryDepends.cmake and the  
HDF5BuildSettings.cmake using install(EXPORT ...) and  
cmake_export_build_settings, respectively. For the former to work, you  
have to install the libraries using an export-set, e.g:

# install target HDF5 (supposedly the library)
install(
   TARGETS HDF5
   EXPORT HDF5LibraryDepends   # this is the name of the export-set
   LIBRARY DESTINATION lib COMPONENT shlibs
   ARCHIVE DESTINATION lib COMPONENT dev
   RUNTIME DESTINATION bin COMPONENT bin
   PUBLIC_HEADER DESTINATION include COMPONENT dev
   )

# install the export-set
install(
   EXPORT HDF5LibraryDepends # again, the name of the export-set
   DESTINATION "@CMAKE_INSTALL_PREFIX@/share/cmake"
   COMPONENT dev
   )


If you carefully read the man-page about find_package, there's a whole  
section detailing where CMake finds XXXConfig.cmake files. The path  
<prefix>/share/cmake is only one example that works on *NIX platforms.  
Probably you'll want to use something else on Windows (or Mac if  
you're building a framework). Also if your package requires the user  
to do add_definition and similar stuff, or you want to provide him  
helper-functions, you should put that stuff in a HDF5Use.cmake and in  
the HDF5Config.cmake set the variable HDF5_USE_FILE to the path of  
this file. If the user then wants to make use of these add_definitions  
and functions, he should then include ${HDF5_USE_FILE}. If you decide  
to provide a HDF5Use.cmake, the cmake_import_build_settings code  
should also be moved there.

Essentially, XXXConfig.cmake should act like a FindXXX.cmake (define  
XXX_LIBRARIES and XXX_INCLUDE_DIRS and related) plus include the  
XXXLibraryDepends.cmake file and perhaps also import the build  
settings (or define XXX_USE_FILE).

HTH

Michael