In CMake, what do install(TARGETS) rules and GNUInstallDirs do, and how does cmake --install place a library and its headers?
answer
- rules recorded now, run later
- ARCHIVE, LIBRARY, RUNTIME
- lib, lib64 or a multiarch dir
- relative destinations under a prefix
- trailing slash on a directory
basics
~20 sinstall() rules record what to copy where, relative to an install prefix; cmake --install build executes them. GNUInstallDirs supplies standard relative destinations such as CMAKE_INSTALL_LIBDIR and CMAKE_INSTALL_INCLUDEDIR, and headers need their own install(DIRECTORY), install(FILES) or file-set rule.
solid answer
~40 s`install()` does nothing while building; it records rules, and `cmake --install build` (optionally `--prefix /some/dir`, and `--config Release` for multi-config generators) runs them later. `install(TARGETS geom ...)` sorts each target's files into **artifact kinds**: `ARCHIVE` (static libraries, Windows import libraries), `LIBRARY` (shared libraries on most platforms), `RUNTIME` (executables and DLLs). `include(GNUInstallDirs)` defines relative destinations such as `CMAKE_INSTALL_BINDIR`, `CMAKE_INSTALL_LIBDIR` (`lib`, `lib64` or a Debian multiarch directory) and `CMAKE_INSTALL_INCLUDEDIR`, which `install(TARGETS)` also uses as defaults. Plain headers are not part of a target's files, so `install(DIRECTORY include/ DESTINATION ${CMAKE_INSTALL_INCLUDEDIR})` or a header file set installs them. Keep destinations relative: they resolve under the prefix, and CPack ignores files installed to absolute destinations.
code
cmake · 12 linesinclude(GNUInstallDirs)
add_library(geom STATIC geom.cpp)
install(TARGETS geom
ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}
LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR})
install(DIRECTORY include/ DESTINATION ${CMAKE_INSTALL_INCLUDEDIR})
set(CPACK_PACKAGE_NAME geom)
include(CPack)go deeper
Recall that install() only records rules, that cmake --install runs them under a prefix, and that headers need their own rule.
Explain ARCHIVE, LIBRARY and RUNTIME, how GNUInstallDirs picks lib, lib64 or a multiarch directory, and why destinations stay relative.
Make install trees work for staging, distribution packagers and CPack alike: no absolute destinations, overridable directories, and headers installed with the target.
Decide what a library team ships and supports as its installed layout, since every other team's build will hard-wire against it.
## Rules now, copying later `install()` is a configure-time command that **records** installation rules; nothing is copied when the project builds. The rules run in a separate step: ```console cmake --build build cmake --install build --prefix /tmp/geom-stage ``` - `--prefix` temporarily replaces `CMAKE_INSTALL_PREFIX` for that run, so the same build tree can be installed into a staging area without reconfiguring. - `--config Release` picks the configuration for multi-config generators. - `--component` installs only the files tagged with a `COMPONENT`. Without `--prefix`, the prefix is `CMAKE_INSTALL_PREFIX`, which defaults to `/usr/local` on UNIX platforms and `c:/Program Files/${PROJECT_NAME}` on Windows. ## Artifact kinds in install(TARGETS) A target can produce more than one file, and the right place depends on the kind of file. `install(TARGETS)` therefore takes a destination per **artifact kind**: | Artifact kind | Typical files | Default destination | |---|---|---| | `ARCHIVE` | static libraries, Windows import libraries (`.lib`) | `${CMAKE_INSTALL_LIBDIR}`, else `lib` | | `LIBRARY` | shared libraries on non-DLL platforms (`.so`, `.dylib`) | `${CMAKE_INSTALL_LIBDIR}`, else `lib` | | `RUNTIME` | executables, and DLLs on Windows | `${CMAKE_INSTALL_BINDIR}`, else `bin` | | `PUBLIC_HEADER`, `FILE_SET HEADERS` | headers attached to the target | `${CMAKE_INSTALL_INCLUDEDIR}`, else `include` | The defaults apply when `DESTINATION` is omitted for executables and static or shared libraries; module libraries, Apple bundles and frameworks always need an explicit destination. ## GNUInstallDirs `include(GNUInstallDirs)` defines cache variables for the standard GNU directory names, such as `CMAKE_INSTALL_BINDIR`, `CMAKE_INSTALL_LIBDIR`, `CMAKE_INSTALL_INCLUDEDIR` and `CMAKE_INSTALL_DATADIR`, each a path **relative** to the prefix, plus `CMAKE_INSTALL_FULL_<dir>` absolute versions. The value that varies most is `LIBDIR`: `lib` on many systems, `lib64` on Linux distributions that use it for 64-bit libraries, and possibly `lib/<multiarch-tuple>` on Debian when the prefix is `/usr`; when cross-compiling, the default is `lib`. Using the variables instead of literal `lib` makes the same project install correctly for distribution packagers, who can override them with `-D`. ## Headers are separate A library's public headers are not files that `add_library` produces, so `install(TARGETS geom ...)` alone installs only `libgeom.a`. Options: 1. `install(DIRECTORY include/ DESTINATION ${CMAKE_INSTALL_INCLUDEDIR})` copies the tree. The **trailing slash** matters: `include/` copies the directory's contents, while `include` would create `include/include/...` under the destination. 2. `install(FILES include/geom/geom.hpp DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/geom)` lists files explicitly. 3. A header **file set** (`target_sources(geom PUBLIC FILE_SET HEADERS ...)`, CMake 3.23+) installed with `install(TARGETS geom FILE_SET HEADERS)` ties the headers to the target and keeps their directory structure. The install documentation suggests considering file sets for headers, because they associate the headers with the target and install as part of it. ## What a run looks like For the `geom` project in a CMake 4.4.4 run on macOS, `cmake --install b` with the prefix set to a staging directory printed, among other lines: ```plaintext -- Installing: <stage>/lib/libgeom.a -- Installing: <stage>/include/geom/geom.hpp -- Installing: <stage>/lib/cmake/geom/geomTargets.cmake ``` ## CPack reuses the same rules `include(CPack)` at the end of the top-level `CMakeLists.txt` generates a `CPackConfig.cmake`, and running `cpack -G TGZ` in the build tree produced `geom-2.3.1-Darwin.tar.gz` holding exactly what `install()` would install. Two consequences: - every file a package should ship must have an `install()` rule; - destinations must be relative, since CPack ignores files installed to an absolute `DESTINATION`. ## Staging with DESTDIR `--prefix` and the `DESTDIR` environment variable solve different problems. `--prefix` changes the prefix the rules resolve against. `DESTDIR`, on UNIX only, keeps the prefix and *prepends* a staging directory: running the install with `DESTDIR=/package/stage` and the prefix `/usr/local` writes into `/package/stage/usr/local`. Distribution packagers use it to collect files exactly as they will be laid out on the target system, then build a package from the staging directory. It cannot be used on Windows, where a prefix such as `C:/Program Files` starts with a drive letter that nothing can be prepended to. ## Checking an install - Install into an empty temporary prefix and list it; every file a consumer needs should be there, and nothing from the source or build tree. - Search the installed text files for the build directory's path; a hit means an absolute path leaked. - Run the packaging step (`cpack`) in CI so a missing rule shows up before a release does. ## Common mistakes - Writing `DESTINATION /usr/lib`, which ignores the prefix and breaks staging and CPack. - Forgetting the headers, so consumers get a library they cannot compile against. - Copying files with `file(COPY)` at configure time instead of installing them.
- Why does a shared library on Windows need both RUNTIME and ARCHIVE destinations?A Windows DLL comes with an import library: the `.dll` is a `RUNTIME` artifact that belongs next to executables, while the `.lib` import library is an `ARCHIVE` artifact consumers link against. If only one of the two destinations is given, CMake installs only that component; with neither, both go to their defaults.
- What is the difference between cmake --install build --prefix /x and setting CMAKE_INSTALL_PREFIX at configure time?`--prefix` overrides the prefix only for that install run, so one configured build tree can be installed to several places, such as a staging directory for packaging. `CMAKE_INSTALL_PREFIX` is the configured default. Values computed from it at configure time, such as `CMAKE_INSTALL_FULL_LIBDIR`, do not follow `--prefix`.
- install() copies files during the normal build
- install(TARGETS) also installs the library's public headers automatically
- Hard-coding DESTINATION lib is as portable as CMAKE_INSTALL_LIBDIR
- Absolute DESTINATION paths are fine for CPack packages
- install(DIRECTORY include ...) and include/ do the same thing