CMake构建学习笔记32-CMake版本切换

1. 引言

在使用 CMake 构建 C/C++ 程序的时候，会遇到 CMake 版本兼容性问题。比如笔者构建 gflags 的时候提示：

bash 复制代码

Running: cmake "../Source/gflags-2.2.2" -B"./gflags-2.2.2" -G"Unix Makefiles" -DCMAKE_BUILD_TYPE=RelWithDebInfo -DCMAKE_PREFIX_PATH="/home/ubuntu/GISBasic/" -DCMAKE_INSTALL_PREFIX="/home/ubuntu/GISBasic/" -DBUILD_SHARED_LIBS=ON
CMake Error at CMakeLists.txt:73 (cmake_minimum_required):
  Compatibility with CMake < 3.5 has been removed from CMake.

  Update the VERSION argument <min> value.  Or, use the <min>...<max> syntax
  to tell CMake that the project requires at least <min> but has been updated
  to work with policies introduced by <max> or earlier.

  Or, add -DCMAKE_POLICY_VERSION_MINIMUM=3.5 to try configuring anyway.


-- Configuring incomplete, errors occurred!
Error: could not find CMAKE_PROJECT_NAME in Cache
Error: could not find CMAKE_PROJECT_NAME in Cache
/home/ubuntu/projects/charlee-blog
ubuntu@VM-0-7-ubuntu:~/projects/charlee-blog$ cmake --version
cmake version 4.1.2

原因是因为笔者使用的是 CMake 4.1.2，CMake 不再支持 cmake_minimum_required(VERSION x.y) 中指定低于 3.5 的版本。而构建 gflags 的要求却是 cmake_minimum_required(VERSION 2.8.12)，因此报错。因此一个比较好的解决方案就是安装多个 CMake 版本并在它们之间临时切换。

2. 解决

2.1 重新构建

首先讨论一个问题：切换 CMake 版本后，由于 CMake 的版本不一致，会不会导致已经构建好的程序需要重新构建？答案是不需要。因为 CMake 是"构建系统生成器"，它的作用是读取 CMakeLists.txt，生成 Makefile / Ninja / Visual Studio 等本地构建文件。而实际的程序编译工作是由 make、ninja、gcc、clang 等完成的。

2.2 安装版本

在 Ubuntu 环境下，一般可以通过系统包管理器（apt）或者 Kitware 官方源安装 CMake，例如笔者的情况是：

bash 复制代码

ubuntu@VM-0-7-ubuntu:~/projects/charlee-blog$ cmake --version
cmake version 4.1.2

CMake suite maintained and supported by Kitware (kitware.com/cmake).
ubuntu@VM-0-7-ubuntu:~/projects/charlee-blog$ which cmake
/usr/bin/cmake

如果当前版本的 CMake 不能正确构建 C/C++ 程序，就需要安装一个新的 CMake 版本。可以在官方 CMake 二进制包下载地址（ https://github.com/Kitware/CMake/releases ）找到以 .tar.gz 结尾的 Linux x86_64 目标版本即可，解压即用，无需安装。例如：

bash 复制代码

ubuntu@VM-0-7-ubuntu:~/tools/cmake/cmake-3.26.4-linux-x86_64/bin$ dir
ccmake  cmake  cmake-gui  cpack  ctest
ubuntu@VM-0-7-ubuntu:~/tools/cmake/cmake-3.26.4-linux-x86_64/bin$ which cmake
/usr/bin/cmake

2.3 切换配置

update-alternatives 是 Linux 系统（特别是基于 Debian/Ubuntu 的发行版）中用于管理多个版本的同名命令或程序的一个工具。它的主要作用是在系统中存在多个可执行文件提供相同功能时，方便地切换默认使用的版本。

update-alternatives 的原理很简单，就是通过创建符号链接的方式，在 /usr/bin/（或其他目录）下维护一个"通用名称"（如 gcc、cmake），并将其指向实际安装的某个具体版本（如 /usr/bin/gcc-11 或 /usr/bin/gcc-13）。这些映射关系由 update-alternatives 统一管理，存储在 /var/lib/dpkg/alternatives/ 中。

具体操作如下：

执行如下命令：

bash 复制代码

sudo update-alternatives --install /usr/local/bin/cmake cmake /usr/bin/cmake 100

sudo update-alternatives --install /usr/local/bin/cmake cmake /home/ubuntu/tools/cmake/cmake-3.26.4-linux-x86_64/bin/cmake 90

确保 /usr/local/bin 在环境变量 PATH 中（通常默认情况就在）：
bash 复制代码
```
echo $PATH
```

切换 CMake 版本：

bash 复制代码

sudo update-alternatives --config cmake

可以看到类似输出：

bash 复制代码

There are 2 choices for the alternative cmake (providing /usr/local/bin/cmake).

Selection    Path                                                                 Priority   Status
------------------------------------------------------------
* 0            /usr/bin/cmake                                                       100       auto mode
1            /usr/bin/cmake                                                       100       manual mode
2            /home/ubuntu/tools/cmake/cmake-3.26.4-linux-x86_64/bin/cmake         90        manual mode

Press <enter> to keep the current choice[*], or type selection number:

输入 2 回车表示切换到 CMake 3.26.4，输入 1 回车表示切换回 CMake 4.1.2。

进行验证:
bash 复制代码
```
cmake --version
which cmake
```
切换后，which cmake 应该显示：
bash 复制代码
```
/usr/local/bin/cmake
```
而 /usr/local/bin/cmake 是一个符号链接，指向选中的实际版本。

2.4 注意

笔者在验证的时候始终切换不成功：

bash 复制代码

ubuntu@VM-0-7-ubuntu:~$ cmake --version
CMake Error: Could not find CMAKE_ROOT !!!
CMake has most likely not been installed correctly.
Modules directory not found in
/home/ubuntu/tools/cmake/cmake-3.26.4-linux-x86_64/share/cmake-4.1
cmake version 4.1.2

原因是因为 Shell 命令哈希（hash）缓存，之前运行过 cmake 命令时，/usr/local/bin/cmake 还没生效或不在 PATH 前面，所以 bash 记住了"cmake = /usr/bin/cmake"：

bash 复制代码

$ type cmake
cmake is hashed (/usr/bin/cmake)

因此即使你现在配置好了 /usr/local/bin/cmake 并且使它在 PATH 前面，bash 仍然使用旧的缓存路径。解决方案是运行以下命令，清空所有命令路径缓存：

bash 复制代码

hash -r