How to configure CMakeLists.txt to install public headers of a shared library?

Question

I want to use cmake to install my library edv but when I execute:

cmake --build . --target install

It installs but it only creates the bin/edv.dll and lib/ < empty >. How can I make cmake to install the EDV_PUBLIC_INCLUDE_DIRECTORIES inside an include/... ?

Here's my CMakeLists.txt:

cmake_minimum_required(VERSION 3.12)

project(edv)

# include PUBLIC directories
set(EDV_PUBLIC_INCLUDE_DIRECTORIES      include/ )

set(EDV_PRIVATE_INCLUDE_DIRECTORIES     src/   )

# Edv source files list
file(GLOB_RECURSE EDV_SOURCE_FILES "src/*.cpp" "src/*.hpp*")


# build the library
add_library(${PROJECT_NAME} SHARED ${EDV_SOURCE_FILES} )

target_include_directories(${PROJECT_NAME} PUBLIC ${EDV_PUBLIC_INCLUDE_DIRECTORIES})
target_include_directories(${PROJECT_NAME} PRIVATE ${EDV_PRIVATE_INCLUDE_DIRECTORIES})

install (TARGETS ${PROJECT_NAME}
    RUNTIME DESTINATION bin
    LIBRARY DESTINATION lib
    ARCHIVE DESTINATION lib
    PUBLIC_HEADER DESTINATION include
)

You have to use `set_target_properties` to set `PUBLIC_HEADER` property. See the documentation for the [install command](https://cmake.org/cmake/help/latest/command/install.html#targets) — Christian Rapp, Nov 19 '19 at 16:03

ComicSansMS · Accepted Answer · 2022-02-09T17:59:44.067

CMake cannot deduce the set of header files to be installed from the target. This makes sense, as the target may contain both private and public header files, but CMake does not differentiate between those. As a consequence, you have to list the header files explicitly in an INSTALL(FILES ...) command:

install(FILES ${MY_HEADER_FILES} DESTINATION include)

Update for CMake 3.23 and later:

CMake version 3.23 introduced File Sets, which allow handling header files in a more elegant way. This way header files only need to be listed once in the CMakeLists.txt to get both integrated in the IDE and also installed correctly:

cmake_minimum_required(VERSION 3.23)

# example library with sources and headers located at ${MY_LIB_SOURCE_DIR}
add_library(my_lib)
target_include_directories(my_lib PUBLIC ${MY_LIB_SOURCE_DIR})

# source files get added as before
target_sources(my_lib PUBLIC ${MY_LIB_SOURCE_DIR}/my_lib/my_lib.cpp)

# header files get added via FILE_SET
# BASE_DIR should point to the same directory that is used as the 
# target_include_directory, otherwise the install paths may be off.
target_sources(my_lib PUBLIC FILE_SET HEADERS
  BASE_DIRS ${MY_LIB_SOURCE_DIR}
  FILES ${MY_LIB_SOURCE_DIR}/my_lib/my_lib.hpp)

# install command needs to reference the file set again
install(TARGETS my_lib FILE_SET HEADERS)

End of 3.23 update

The PUBLIC_HEADER field that you stumbled upon is related to the OSX framework mechanism, which is its very own can of worms. I suggest you stay clear of it, unless you actually want to deploy your library as a .framework on OSX.

Take special note of the INCLUDES DESTINATION option to the INSTALL(TARGET ...) command. While this does not actually copy any files itself, it allows the include directory to be added to the imported target provided by the config package script automatically. If you intend to provide a package config script to your users (which you probably should, at least if you expect your users to also use CMake), you probably want to set this option.

Since the install mechanism is quite complicated overall, I have a small github project of mine where you can observe all the elements in action.

The `PUBLIC_HEADER` field is the recommended way to install header files. It is in no way exclusive to Apple frameworks. See the documentation: "Any PUBLIC_HEADER files associated with a library are installed in the destination specified by the PUBLIC_HEADER argument on non-Apple platforms" — Christian Rapp, Nov 19 '19 at 15:58
The above suggestion is wrong. There is no need to list header files explicitly in `INSTALL(FILES ...)` or even to use `INSTALL(FILES ....)` at all. All it takes is to set `PUBLIC_HEADERS` argument in `INSTALL(target ....)` and then set the `PUBLIC_HEADER` target property with all the header files. — RAM, Dec 09 '19 at 22:10
`PUBLIC_HEADER` is the proper way only in very simple cases. As soon as you have multiple subdirectories for the headers it does no longer work, as CMake flattens the hierarchy and puts all headers into the same directory. — Corristo, Dec 09 '19 at 22:23
@ChristianRapp The first line on the relevant page of the docs says 'Specify public header files in a FRAMEWORK shared library target,' implying that this is intended only for frameworks. Can you share where its use is recommended to install headers? — jezza, Jan 26 '21 at 08:27
If you can afford the usage of a version >= 3.23 of CMake, clearly, CMake File Sets is the solution ! Thanks for pointing it out in this answer and thanks for the example ! — mscherer, Jun 21 '23 at 13:11

score 9 · Answer 2 · edited Mar 31 '21 at 14:00

To install all headers present in the ./include folder, all you need to do is:

set a list with all the header files you want to install (i.e. define EDV_INCLUDE_FILES),
set the target property PUBLIC_HEADER with all those header files,
set the PUBLIC_HEADER argument in install(TARGETS ...) with the installation directory.

This method is also the basis for CMake's support of macOS frameworks.

I've updated the example above with the settings to install the project's public headers in ./include in the project's target output directory. Caveat: I haven't personally tested the project definition, thus it may require some minor tweaks to work.

cmake_minimum_required(VERSION 3.12)

project(edv)

# include PUBLIC directories
set(EDV_PUBLIC_INCLUDE_DIRECTORIES      include/ )

set(EDV_PRIVATE_INCLUDE_DIRECTORIES     src/   )

# Edv source files list
file(GLOB_RECURSE EDV_SOURCE_FILES "src/*.cpp" "src/*.hpp*")

file(GLOB_RECURSE EDV_INCLUDE_FILES "include/*.hpp*")

# build the library
add_library(${PROJECT_NAME} SHARED ${EDV_INCLUDE_FILES} ${EDV_SOURCE_FILES} )

target_include_directories(${PROJECT_NAME} PUBLIC ${EDV_PUBLIC_INCLUDE_DIRECTORIES})
target_include_directories(${PROJECT_NAME} PRIVATE ${EDV_PRIVATE_INCLUDE_DIRECTORIES})

set_target_properties(${PROJECT_NAME}
    PROPERTIES
    PUBLIC_HEADER "${EDV_INCLUDE_FILES}"
)

install (TARGETS ${PROJECT_NAME}
    RUNTIME DESTINATION bin
    LIBRARY DESTINATION lib
    ARCHIVE DESTINATION lib
    PUBLIC_HEADER DESTINATION include
)

score 2 · Answer 3 · answered Oct 06 '21 at 22:13

The Cmake install documentation has almost the same proposal as ComicSansMS.

The following example shows how to follow this advice (mentioned earlier in the documentation) while installing headers to a project-specific subdirectory:

include(GNUInstallDirs)
install(FILES mylib.h
        DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/myproj
)

In this solution, the destination is not hard coded, but uses variable defined by the GNUInstallDirs Cmake module (and adds the subdirectory after a slash). Using variables make things more flexible for package maintainers and the default value of the variable may be system specific. (May not specific for CMAKE_INSTALL_INCLUDEDIR but definitely system specific for CMAKE_INSTALL_LIBDIR.) Here is a good explanation from Craig Scott from CPPCon 2019 - Deep CMake for Library Authors

Or even better, if one has a sub-folder within include, then that whole directory can be installed as well:

include(GNUInstallDirs)
install(DIRECTORY include/myproj
        DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}
)

How to configure CMakeLists.txt to install public headers of a shared library?

3 Answers3

Linked