Proper Methods for Specifying GCC Compiler Path in CMake: A Comprehensive Guide

Problem Context and Challenges

In Linux systems like CentOS, the default installed GCC compiler version is often outdated, while many modern projects require newer compiler features. When users install newer GCC versions in custom paths (e.g., /usr/local/bin/gcc), the CMake build system may continue using the system's default older compiler path (e.g., /usr/bin/gcc). This configuration mismatch can lead to compilation errors or failure to leverage new compiler optimizations.

Environment Variable Configuration Method

The recommended approach is to set CC and CXX environment variables before running CMake:

export CC=/usr/local/bin/gcc
export CXX=/usr/local/bin/g++
cmake /path/to/your/project
make

This method offers significant advantages: environment variable settings only need to be executed once during initial project configuration, and CMake automatically reads these values from cache in subsequent builds. More importantly, this approach doesn't interfere with CMake's compiler detection and toolchain configuration processes.

Limitations of CMake Variable Settings

Many developers prefer using set commands directly in CMakeLists.txt to specify compiler paths, but this approach has serious drawbacks. CMake provides three variable setting methods:

Non-Cache Setting

set(CMAKE_C_COMPILER /usr/bin/clang)
set(CMAKE_CXX_COMPILER /usr/bin/clang++)

This approach creates normal variables that hide cache variables of the same name. The result is hardcoding compiler paths in build scripts, eliminating CMake's cross-environment configuration flexibility.

Cache Setting

set(CMAKE_C_COMPILER /usr/bin/clang CACHE PATH "")
set(CMAKE_CXX_COMPILER /usr/bin/clang++ CACHE PATH "")

Since CMAKE_C(XX)_COMPILER variables already exist in cache, this setting effectively doesn't work unless forced.

Force Cache Setting

set(CMAKE_C_COMPILER /usr/bin/clang CACHE PATH "" FORCE)
set(CMAKE_CXX_COMPILER /usr/bin/clang++ CACHE PATH "" FORCE)

While this method writes values to cache, any user customizations will be overwritten by the set command, essentially equivalent to hardcoding.

Compiler Detection Mechanism Analysis

CMake performs critical compiler detection tasks during early configuration stages: verifying compiler functionality, executable generation capability, and detecting related toolchain components (like ar and ranlib). When overriding compiler variables in CMake scripts, these important detection steps have already completed, leading to incorrect toolchain configuration.

Specific cases demonstrate: on systems defaulting to GCC, when switching to /usr/bin/clang via set commands, the ar tool remains set to /usr/bin/gcc-ar-7. However, when using environment variable configuration, ar correctly configures to /usr/lib/llvm-3.8/bin/llvm-ar, ensuring entire toolchain consistency.

Practical Cases and Troubleshooting

The referenced case study demonstrates potential issues when using -DCMAKE_C_COMPILER parameters to directly specify compiler paths. When GCC 6.2.0 was installed in a custom path, CMake reported the compiler as non-functional, with error messages indicating shared library libmpc.so.2 couldn't be loaded.

The root cause of such issues lies in incomplete runtime environment configuration for compiler dependencies. Newly installed GCC might lack necessary shared library path configurations, requiring supplementation through LD_LIBRARY_PATH environment variable:

export LD_LIBRARY_PATH=/home/wzp/workspace/software/gcc_620_wzp/lib64:$LD_LIBRARY_PATH
export CC=/home/wzp/workspace/software/gcc_620_wzp/bin/gcc
export CXX=/home/wzp/workspace/software/gcc_620_wzp/bin/g++
cmake ..

Complete Best Practices Workflow

To ensure custom GCC compilers work properly in CMake, follow this comprehensive workflow:

1. Environment Preparation: Verify complete paths for newly installed GCC compiler and its dependency libraries
2. Environment Variable Configuration: Set CC, CXX, and necessary library path variables
3. Cache Cleanup: Delete existing CMake cache files before initial configuration
4. Configuration Verification: Check if CMake output correctly identifies the compiler
5. Toolchain Verification: Confirm related tools (like ar, ranlib) also come from the correct toolchain

Through this systematic approach, developers can ensure CMake projects correctly use custom GCC compilers while maintaining build system flexibility and maintainability.