[CMake] How to make a ProjectConfig.cmake

[Alexander Neundorf]

On Thursday 20 January 2011, Michael Wild wrote:
> On 01/19/2011 07:24 PM, Alexander Neundorf wrote:
> > On Thursday 30 December 2010, Michael Wild wrote:
> >> On 12/30/2010 11:33 AM, Ian Monroe wrote:
> >>> To create my QyotoConfig.cmake I need to know the full path of a
> >>> library so that I can set a variable like QYOTO_LIBRARY.
> >>>
> >>> This is pretty standard requirement right? Its what we're supposed to
> >>> do in *Config.cmake's?
> >>>
> >>> So anyways, how do I that? The only target property that hasn't
> >>> returned NOTFOUND is LOCATION, which unhelpfully returns the location
> >>> of the library in the build directory. I could parse this to get the
> >>> file name, and then append it to the library install location... but
> >>> that seems like such a hack. Feels like I'm doing something wrong if I
> >>> need to use a hack to do something standard.
> >>>
> >>> I looked at install(EXPORT which could work, but it seems to include a
> >>> lot more information then is needed. I just want to set a variable
> >>> with the full path to a library.
> >>>
> >>> Ian
> >>
> >> That's not how *Config.cmake modules work. They're NOT Find*.cmake
> >> modules. You should:
> >>
> >> - add the targets to an export-set for usage from the build tree:
> >>
> >>   export(TARGETS ...
> >>     FILE ${CMAKE_BINARY_DIR}/${PROJECT_NAME}LibraryDepends.cmake)
> >>
> >> - add the targets to an export-set for installation:
> >>
> >>   install(TARGETS ... EXPORT ${CMAKE_PROJECT_NAME}LibraryDepends ...)
> >>
> >> - export the package for usage from the build tree (enter into some
> >> global registry):
> >>
> >>   export(PACKAGE ${PROJECT_NAME})
> >>
> >> - create a *Config.cmake file for the use from the build tree:
> >>
> >>   set(QYOTO_INCLUDE_DIR ${CMAKE_SOURCE_DIR})
> >>   set(QYOTO_LIB_DIR ${CMAKE_BINARY_DIR}/lib)
> >>   set(QYOTO_CMAKE_DIR ${CMAKE_BINARY_DIR})
> >>   configure_file(${CMAKE_PROJECT_NAME}Config.cmake.in
> >>     ${CMAKE_BINARY_DIR}/${CMAKE_PROJECT_NAME}Config.cmake @ONLY)
> >>
> >> - install the export set:
> >>
> >>   install(EXPORT ${CMAKE_PROJECT_NAME}LibraryDepends DESTINATION
> >>     share/${CMAKE_PROJECT_NAME}/CMake)
> >>
> >>
> >> - create a *Config.cmake file for the use from the install tree and
> >> install it:
> >>
> >>   set(QYOTO_INCLUDE_DIR ${CMAKE_INSTALL_PREFIX}/include)
> >>   set(QYOTO_LIB_DIR ${CMAKE_INSTALL_PREFIX}/lib)
> >>   set(QYOTO_CMAKE_DIR
> >>     ${CMAKE_INSTALL_PREFIX}/share/${CMAKE_PROJECT_NAME}/CMake)
> >>   configure_file(${CMAKE_PROJECT_NAME}Config.cmake.in
> >>     ${CMAKE_BINARY_DIR}/InstallFiles/${CMAKE_PROJECT_NAME}Config.cmake
> >>     @ONLY)
> >>   install(FILES
> >>     ${CMAKE_BINARY_DIR}/InstallFiles/${CMAKE_PROJECT_NAME}Config.cmake
> >>     DESTINATION share/${CMAKE_PROJECT_NAME}/CMake)
> >>
> >> - The *Config.cmake.in could look like this:
> >>
> >> #######################################################################
> >> # Tell the user project where to find our headers and libraries
> >> set(QYOTO_INCLUDE_DIR "@QYOTO_INCLUDE_DIR@")
> >> set(QYOTO_INCLUDE_DIRS "${QYOTO_INCLUDE_DIR}")
> >> set(QYOTO_LIBRARY_DIRS "@QYOTO_LIB_DIR@")
> >>
> >> # Our library dependencies (contains definitions for IMPORTED targets)
> >> include("@QYOTO_CMAKE_DIR@/@PROJECT_NAME at LibraryDepends.cmake")
> >>
> >> # Defines (if required)
> >> set(QYOTO_DEFINITIONS "@QYOTO_COMPILE_DEFINITIONS@")
> >>
> >> # USE file (if you have one)
> >> set(QYOTO_USE_FILE
> >>   "@QYOTO_CMAKE_DIR@/@PROJECT_NAME at Use.cmake"
> >>   )
> >> #######################################################################
> >>
> >> As you can see, the QYOTO_INCLUDE_DIR, QYOTO_LIB_DIR and QYOTO_CMAKE_DIR
> >> values will differ between build and install tree, which is why you
> >> should configure it twice, once for installation and once for the use
> >> from the build tree.
> >>
> >> - If you want to get fancy, you can also provide a *ConfigVersion.cmake
> >> file. This file should set the following variables, depending on the
> >> variables PACKAGE_FIND_NAME, PACKAGE_FIND_VERSION,
> >> PACKAGE_FIND_VERSION_{MAJOR,MINOR,PATCH,TWEAK,COUNT}:
> >>
> >>   - PACKAGE_VERSION (version string)
> >>   - PACKAGE_VERSION_EXACT (TRUE or FALSE)
> >>   - PACKAGE_VERSION_COMPATIBLE (TRUE or FALSE)
> >>   - PACKAGE_VERSION_UNSUITABLE (TRUE or FALSE)
> >
> > Wow, good summary.
> >
> > Can you please put that in a wiki page on http://www.cmake.org/Wiki/CMake
> > ?
> >
> > Thanks :-)
> > Alex
>
> http://www.cmake.org/Wiki/CMake:How_to_create_a_ProjectConfig.cmake_file
>
> What do you think? Text is pretty terse, but the code should cover it...

Great :-)
I would move the link to the page to a a bit up on the main page, so it's 
easier to find.
Maybe that overview page needs some shuffling around again.

Alex