CMake and Setting CMAKE_INSTALL_PREFIX

1. Introduction

Especially when it comes to specific environments or building from source, we might often want to change the destination directory during compilation or installation.

In this tutorial, we explore CMake and ways to set the path prefix. First, we briefly define one of the base components of the suite. Next, we provide a simple CMake configuration. After that, we turn to install path modification. Finally, we check several options to mutate the install path with a standard variable and the command line.

We tested the code in this tutorial on Debian 11 (Bullseye) with GNU Bash 5.1.4. It should work in most POSIX-compliant environments.

2. make

Before delving into CMake, let’s briefly refresh our knowledge about a tool that it relies on. The make utility uses a Makefile to build, test, package, and install software.

Similar to Docker and its Dockerfile, a set of instructions in the Makefile dictate what actions make performs:

CC=gcc

xtarget: obj1.o obj2.o
  $(CC) -o main obj1.o obj2.o

Without getting into details, the language of make is very rudimentary:

• only string variables
• no user-defined types
• no warning on undefined variable references
• arguments to functions are in global variables

Because of these and other shortcomings, another tool aims to enrich not only the language but also the overall functionality of make.

3. CMake

Similar to make, the high-level CMake suite and cmake tool can automate many software tasks:

• building
• test
• packaging
• installing

In a way, CMake is a build generator since it can employ make, ninja, and similar tools for its purposes. However, it goes above and beyond the features of either.

Moreover, the syntax of the CMakeLists.txt project file is usually simpler to implement and support for third-party tools:

cmake_minimum_required(VERSION 3.12...3.25)

project(
  xCMakeProject
  VERSION 1.0
  LANGUAGES CXX)

add_library(xlib xlib.c xlib.h)

add_executable(xe xe.cpp)

target_link_libraries(xe PRIVATE xlib)

In addition, CMake preserves build recipes as CMakeCache.txt files and requires dependencies when unavailable. On top of that, it manages whole directories for builds.

4. CMake Install Path

Similar to the classic make, which cmake can and often does employ, we have the option to change the installation directory. To do so, we have two main options.

Generally, we can set the standard DESTDIR environment variable to the top-level directory path:

$ export DESTDIR=/path/to/top/dir

If we do the above from the process or shell that calls cmake or make, its effects propagate throughout the scripts.

In addition, we can add the DESTINATION parameter in the install() command as a relative or absolute path:

install(TARGETS xe DESTINATION current/bin)

In this case, we populate the CMakeLists.txt project file with the bottom-level directory path in DESTINATION. Moreover, we can employ another modifier.

5. Set CMake Install Prefix

The CMAKE_INSTALL_PREFIX (default /usr/local) parameter is a suffix of DESTDIR and a prefix for the install() DESTINATION path when the latter is relative.

In particular, we can change the value of CMAKE_INSTALL_PREFIX in several ways.

5.1. Using set() in CMakeLists.txt

The set() command provides a way to assign values to three categories of CMake variables:

• normal
• cache
• environment and reserved

In essence, we can use set() with CMAKE_INSTALL_PREFIX:

set(CMAKE_INSTALL_PREFIX "/path/to/subdir")

Alternatively, we can FORCE the value directly in the CACHE:

set(CMAKE_INSTALL_PREFIX "/path/to/subdir" CACHE PATH "install prefix" FORCE)

In this case, we specify the variable type as PATH, but the documentation string (here, “install prefix”) can be anything.

However, the best practice is to perform a check for the default value of CMAKE_INSTALL_PREFIX before setting it:

IF(CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT)
  SET(CMAKE_INSTALL_PREFIX "/path/to/subdir" CACHE PATH "install prefix" FORCE)
ENDIF(CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT)

While set() is a standard way to change variable values, we may prefer less intrusive methods to do so.

5.2. Command-line Switch

On top of CMakeLists.txt changes, we can configure CMake cache entries like CMAKE_INSTALL_PREFIX with the -D switch of cmake:

$ cmake -DCMAKE_INSTALL_PREFIX=/path/to/subdir

Short of changing CMakeCache.txt directly, this way is usually best for particular environments during installation as opposed to reconfiguring the build files.

5.3. Using the –prefix Option of cmake

Recent versions of cmake support the –prefix option to the –install mode:

$ cmake --install . --prefix /path/to/subdir

If provided, the –prefix switch of cmake overrides CMAKE_INSTALL_PREFIX.

In all cases, settings are stored in CMakeCache.txt and remain there until forced out. So, if the changes don’t get reflected, removing or renaming CMakeCache.txt can help.

6. Summary

In this article, we briefly explored CMake, make, and their relation, so we can understand how to change options like the installation destination path.

In conclusion, while there are many ways to change some CMake parameters, our choice usually depends on the way we want to configure the build.