Skip to content

example.find_package.config

Ruslan Baratov edited this page May 18, 2015 · 5 revisions

MODULE vs. CONFIG

Usually package can be added to project using one of the Find<Package>.cmake standard CMake modules, e.g. Boost:

set(Boost_USE_STATIC_LIBS ON)
find_package(Boost REQUIRED)
if(WIN32)
  add_definitions(-DBOOST_ALL_NO_LIB=1)
  add_definitions(${Boost_LIB_DIAGNOSTIC_DEFINITIONS})
endif()

include_directories(${Boost_INCLUDE_DIRS})
add_executable(foo foo.cpp)

Using CONFIG-mode of find_package command all this code can be substituded with literally two lines (see Boost):

find_package(Boost CONFIG REQUIRED)
target_link_libraries(... Boost::boost)
    # include dirs (Boost_INCLUDE_DIRS) added automatically
    # definition BOOST_ALL_NO_LIB=1 added automatically too

effectively this will add new interface imported target Boost::boost to your project.

Relocation challenge

Note that when your dependency is found by Find<Package>.cmake and then installed with CMake config, public libraries linked with hardcoded paths. For instance:

# CMakeLists.txt
find_package(Boost REQUIRED)
target_include_directories(foo PUBLIC ${Boost_INCLUDE_DIRS})
> cmake --build _builds --target install
Install the project...
-- Install configuration: "Release"
...
-- Installing: /<install-prefix>/lib/cmake/<package>/<package>Targets.cmake
-- Installing: /<install-prefix>/lib/cmake/<package>/<package>Targets-release.cmake
> grep -i interface_include /<install-prefix>/lib/cmake/<package>/<package>Targets.cmake
  INTERFACE_INCLUDE_DIRECTORIES "/<install-prefix>/include"

The bad thing about this is that when you pack your code and try to use it on another machine there will be no such directory like /<install-prefix>/include/. Solution to this problem is to use config-mode imported targets:

# CMakeLists.txt
find_package(Boost CONFIG REQUIRED)
target_link_libraries(... PUBLIC Boost::boost)
# <package>Config.cmake.in
# template file that will be installed with your library
# i.e. user don't need to call find_package(Boost CONFIG) explicitly
find_dependency(Boost CONFIG)
...
> cmake --build _builds --target install
> grep -i boost /<install-prefix>/lib/cmake/<package>/<package>Targets.cmake
  INTERFACE_LINK_LIBRARIES "Boost::boost"

As you can see now hardcoded path go away and find_dependency command will find new location with new paths when package will be moved to machine with different <install-prefix>. Target Boost::boost will be linked automatically on find_package:

# User's CMakeLists.txt
find_package(<package> CONFIG REQUIRED)

# find_package(Boost CONFIG REQUIRED) # not needed!
# target_link_libraries(... Boost::boost) # not needed!

target_link_libraries(... <package>::<imported-target>)
# add Boost::boost automatically with new <prefix-path>

Note that Hunter do downloads transitively too:

hunter_add_package(<package>)
# hunter_add_package(Boost) # not needed!

find_package(<package> CONFIG REQUIRED)
target_link_libraries(... <package>::<imported-target>)

CMake

There are quite a lot of boilerplate code you need to add, but the core of feature is this two lines (Foo is the project, boo is the target):

install(TARGETS boo EXPORT FooTargets ...) # FooTarget.cmake now know about boo
install(EXPORT FooTargets ...) # install FooTarget.cmake

Next see real examples to run and documenation:

Clone this wiki locally