Install

The install module provides library installation with full CMake package config and pkg-config integration. It also provides targets for creating source distributions and uninstalling previously installed files.

The installation layout follows the conventions established by ADR-0004 — Workspace and Component Protocol, which defines a standard filesystem hierarchy under PREFIX with bin/, lib/, include/, share/, and lib/pkgconfig/ directories.

Build targets

Target	Description
dist	Creates a source tarball with the version embedded
uninstall	Removes all installed files using the install manifest

These targets are only available for top-level projects.

dist

Creates a .tar.gz source distribution using git archive. Before packaging, the module patches the CMakeLists.txt inside the tarball to include project(VERSION ...) so that the version module becomes a no-op when building from the extracted source — the version is frozen at the time of distribution.

For prerelease versions (e.g., 1.0.0-rc1), a set(PROJECT_VERSION_PRERELEASE ...) statement is also injected after the project() call.

uninstall

Reads install_manifest.txt — generated automatically by cmake --install — and removes each installed file, then cleans up empty parent directories from deepest to shallowest.

Function reference

install_library

install_library(<target1> [<target2> ...] [NAME <name>])

Installs one or more library targets with CMake package config, export files, and pkg-config integration.

Parameter	Description
NAME	Base name for package config, namespace, and pkg-config. Defaults to the first target
targets	One or more library targets to install

The export name is derived by capitalizing the first letter of NAME. For example, sx produces SxConfig.cmake, SxConfigVersion.cmake, SxTargets.cmake, and the sx:: namespace.

The version compatibility policy is SameMajorVersion, meaning downstream projects can use any version with the same major number.

The function performs the following steps:

1. Installs library archives to ${CMAKE_INSTALL_LIBDIR}.
2. Installs public headers from each target's $<BUILD_INTERFACE:...> include directories to ${CMAKE_INSTALL_INCLUDEDIR}, excluding *.in template files.
3. Generates and installs CMake package config and version files.
4. Generates and installs a pkg-config .pc file.

Single target:

add_library(mylib src/mylib.c)
target_include_directories(mylib PUBLIC
  $<BUILD_INTERFACE:${PROJECT_SOURCE_DIR}/include>
)

install_library(mylib)

Multiple targets with a shared namespace:

install_library(mylib mylib-utils NAME mylib)
# Produces: MylibConfig.cmake, mylib::mylib, mylib::mylib-utils, mylib.pc