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:
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.