How to use CMake to find and link to a library using install-export and find_package?

Question

You have a CMake-enabled library project. You need to use it in another library or executable. How to use CMake to find and link to the library? You may have the following preferences:

• write the least possible amount of boiler-plate code
• decouple the internal details of the linked library from the consuming target

Ideally, the usage of the library should look like this:

add_executable(myexe ...)
target_link_libraries(myexe mylib::mylib)

Answer 1

Let me demonstrate a possible solution on a concrete example:

The myapp project

We have an executable target myapp. We're linking it with mylib, which is built in its own build tree. In the CMakeLists.txt of myapp we find and specify mylib as a dependency of myexe:

find_package(mylib REQUIRED)
...
add_executable(myexe ...)
target_link_libraries(myexe mylib::mylib)

Let's see how to set up mylib and the build of myexe to make this work.

The mylib project

The directory layout of mylib:

mylib
- CMakeLists.txt
- mylib.c
+ include
  - mylib.h # single public header

In the CMakeLists.txt of mylib we need to create the target and specify its source files:

add_library(mylib mylib.c include/mylib.h)

The public header mylib.h will be included as #include "mylib.h" both by mylib and the clients of mylib:

• mylib itself and other targets built in mylib's CMake project (for example tests) need to find include/mylib.h from the mylib source tree
• clients of mylib built in their own projects (like myexe) need to find include/mylib.h at its installed location

CMake allows us to specify both include paths for mylib:

target_include_directories(mylib PUBLIC
    $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
    $<INSTALL_INTERFACE:include>)

We're using the PUBLIC option here since this header is needed on the public interface of mylib. Use PRIVATE for include paths internal to mylib.

The INSTALL_INTERFACE specifies a path relative to the install root, that is, CMAKE_INSTALL_PREFIX. To actually install the public header:

    set_target_properties(mylib PROPERTIES PUBLIC_HEADER  include/mylib.h")

We also need to install the library itself and the so-called config-module and related files. The config-module is the file which will be used by consuming projects, like myapp to find mylib and get all the parameters needed to link with it. It is similar to the pkg-config's .pc files.

We need two, related install commands. The first one:

install(TARGETS mylib
    EXPORT mylib-targets
    PUBLIC_HEADER DESTINATION include
    ARCHIVE DESTINATION lib
    LIBRARY DESTINATION lib
    RUNTIME DESTINATION bin)

The list of destinations needed to cover all the standard install locations of static libraries, dll's and so's. If you're sure your library will be built exclusively as a static lib, a single DESTINATION lib would make it.

The interesting part is the EXPORT option. It assigns the list of targets (currently, it's only mylib) to the identifier mylib-targets. This identifier will be used in the next command to generate and install some special files which make find_package(mylib) work in the consuming projects:

install(EXPORT mylib-targets
    NAMESPACE mylib::
    FILE mylib-config.cmake
    DESTINATION lib/cmake/mylib)

This command generates multiple files:

• one file for each build configuration (Debug, Release, etc..) which describes the library file and configuration-dependent parameters
• a file which describes the configuration-agnostic parameters and also includes all the config-dependent files. Since this file can also be used as a config-module on its own we simply rename it as mylib-config.cmake

The files will be installed into ${CMAKE_INSTALL_PREFIX}/lib/cmake/mylib which is one of the many standard locations the find_package(mylib) command will search for mylib-config.cmake.

Building mylib

We need to specify an install location in the variable CMAKE_INSTALL_PREFIX:

mkdir build
cd build
cmake -DCMAKE_INSTALL_PREFIX=$PWD/../out ../mylib

and build and install the library:

cmake --build . --target install

Building myexe

myexe needs to know where to look for mylib. The variable CMAKE_PREFIX_PATH can be a list of paths. We need to specify the previous install location:

mkdir build
cd build
cmake -DCMAKE_PREFIX_PATH=$PWD/../out ../myexe
cmake --build .

A note on building multiple configurations

Usually we need to build multiple configurations (Debug, Release). A critical issue is to specify configuration-dependent filenames or install locations. For example, you can set the default value of the DEBUG_POSTFIX property for the library project:

set(CMAKE_DEBUG_POSTFIX d)

The debug version of the mylib library file will be named libmylibd.lib (or mylibd.lib on Windows). The generated EXPORT files will contain the modified filenames.

If you're using makefile-style CMake generators you can control the build configuration by setting the CMAKE_BUILD_TYPE variable:

cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=$PWD/../out ../mylib
cmake --build . --target install

You may need seperate build directories for each configuration or you can re-use the same build dir. In that case, to play it safe it's best to explicitly clean before build:

cmake --build . --target install --clean-first

If you're using a multiconfig IDE generator, like Xcode or Visual Studio, you need to specify the configuration in build time:

cmake -DCMAKE_INSTALL_PREFIX=$PWD/../out ../mylib
cmake --build . --target install --config Release

References

You can clone and build this repository which contains the mylib and myexe projects (tested on Windows and Linux).

Check out the CMake documentation. The most important related commands are:

• add_library
• target_link_libraries
• find_package
• install
• target_include_directories
• target_compile_definitions

and two detailed articles:

• Build System
• Packages