Configuring CMake Install Prefix: Proper Methods for Setting CMAKE_INSTALL_PREFIX from Command Line

Problem Background and Common Errors

In CMake project builds, configuring the installation prefix is a fundamental but error-prone aspect. Many developers attempting to change the installation directory from the default /usr/local to /usr find that files are still installed to the wrong path, even when following documentation instructions for setting the CMAKE_INSTALL_PREFIX variable.

Correct Command-Line Configuration Method

According to CMake official documentation and best practices, the correct syntax for setting the installation prefix via command line is:

cmake -DCMAKE_INSTALL_PREFIX=/usr ..

It's important to note that while using the :PATH type specifier may not cause errors in some cases, the standard approach is to omit type specifiers. CMake can automatically infer variable types, simplifying commands while reducing potential errors.

Configuration Verification and Debugging

After configuration, verify that the settings have taken effect by checking the CMakeCache.txt file:

grep CMAKE_INSTALL_PREFIX CMakeCache.txt

If configured correctly, you should see output like CMAKE_INSTALL_PREFIX:PATH=/usr. However, it's important to note that even if the cache file shows correct configuration, other overriding logic in the project may still cause the actual installation path to differ from expectations.

Build and Installation Execution

After confirming correct configuration, execute the standard build and installation process:

make
make install

At this point, all installation targets (such as install(TARGETS mylibrary DESTINATION lib)) will install files to the /usr/lib directory instead of the default /usr/local/lib.

Alternative Configuration Methods

In addition to command-line settings, the installation prefix can also be set directly in the CMakeLists.txt file:

SET(CMAKE_INSTALL_PREFIX /usr)

However, this method has an important limitation: it must be set before the PROJECT() command. This is because the PROJECT() command initializes many system-related variables, including the installation prefix. Setting it after PROJECT() may result in it being overwritten by default values.

Environment Variable Support

Starting from CMake version 3.29, support for setting the default installation prefix via environment variables was added. If the CMAKE_INSTALL_PREFIX environment variable is set, its value will be used as the default for this variable. This is particularly useful in continuous integration environments for unifying installation path configurations across multiple projects.

Platform Differences and Default Values

CMake has different default installation prefixes across platforms:

• Windows platforms: c:/Program Files/${PROJECT_NAME}
• UNIX platforms: /usr/local

Understanding these default values helps maintain consistent build experiences across different platforms.

DESTDIR Mechanism

For scenarios requiring relocation of the entire installation to a temporary area, CMake supports the DESTDIR mechanism. By setting the DESTDIR environment variable, you can temporarily change the installation root directory without modifying CMAKE_INSTALL_PREFIX:

make install DESTDIR=/tmp/staging

This is particularly useful for software package creation or testing installations.

Modern CMake Installation Mode

In addition to the traditional make install approach, CMake provides a direct installation command:

cmake --install . --prefix /my/install/prefix

This approach offers greater flexibility and is particularly suitable for use in scripts or automated tools.

Common Issue Troubleshooting

If the installation path remains incorrect, consider checking the following points:

1. Ensure the build directory is clean, or delete the CMakeCache.txt file before configuration
2. Check if other settings in the project are overriding CMAKE_INSTALL_PREFIX
3. Verify target path settings in install() commands
4. Confirm that the CMake version being used supports the relevant features

Best Practices Summary

To ensure reliability in installation prefix configuration, we recommend:

• Prefer using the command-line parameter -DCMAKE_INSTALL_PREFIX for settings
• Consider using environment variables or the --install mode in scripted builds
• For complex projects, use the GNUInstallDirs module to manage installation directory layouts
• Clearly document installation path requirements in project documentation