Code Guide

外观

4、cmake输出指令详解

约 4828 字大约 16 分钟

2025-03-03

编写者：bugcode

本文已完成并校对，部分内容引用自 计算机自学指南

CMake 命令输出内容详解

当执行 CMake 命令时，会输出大量信息。理解这些输出对于调试和优化构建过程至关重要。本指南详细解释 CMake 输出的各个部分。

目录

  1. CMake 输出概述
  2. 配置阶段输出
  3. 构建阶段输出
  4. 不同命令的输出详解
  5. 输出级别控制
  6. 常见输出信息解读
  7. 错误信息解读
  8. 警告信息解读
  9. 调试输出
  10. 实际案例解析

1. CMake 输出概述

1.1 输出格式

CMake 的输出通常包含以下部分：

[时间戳] [级别] [上下文] 消息内容

例如：

-- The CXX compiler identification is GNU 9.4.0
-- Detecting CXX compiler ABI info
-- Detecting CXX compiler ABI info - done
CMake Warning at CMakeLists.txt:10 (message):
  This is a warning message

1.2 输出级别前缀

前缀含义颜色说明
--STATUS绿色普通状态信息
CMake WarningWARNING黄色警告信息
CMake ErrorERROR红色错误信息
CMake Deprecation WarningDEPRECATION黄色弃用警告
-- Checking for...CHECK绿色检查操作
-- Configuring doneCONFIGURE绿色配置完成
-- Generating doneGENERATE绿色生成完成
无前缀MESSAGE默认普通消息
CMake Debug LogDEBUG蓝色调试信息

2. 配置阶段输出

2.1 基础配置命令输出

$ cmake ..

输出示例及解释：

2.2 详细配置输出

$ cmake --debug-output ..

额外输出：

3. 构建阶段输出

3.1 基本构建命令输出

$ cmake --build .

输出示例及解释：

3.2 详细构建输出

$ cmake --build . --verbose

详细输出：

3.3 并行构建输出

$ cmake --build . -j 4

并行构建输出：

[1/5] Building CXX object CMakeFiles/myapp.dir/main.cpp.o
[2/5] Building CXX object CMakeFiles/myapp.dir/utils.cpp.o
[3/5] Building CXX object CMakeFiles/myapp.dir/network.cpp.o
[4/5] Building CXX object CMakeFiles/myapp.dir/database.cpp.o
[5/5] Linking CXX executable myapp
# 注意：多个文件同时编译，最后统一链接

4. 不同命令的输出详解

4.1 cmake --help

$ cmake --help

输出解释：

4.2 cmake --system-information

$ cmake --system-information

部分输出示例：

4.3 cmake -LA

$ cmake -LA

输出解释：

5. 输出级别控制

5.1 日志级别

5.2 不同级别的输出对比

STATUS 级别：

-- The CXX compiler identification is GNU 9.4.0
-- Configuring done
-- Generating done

VERBOSE 级别（额外信息）：

-- The CXX compiler identification is GNU 9.4.0
-- Detecting CXX compiler ABI info
-- Detecting CXX compiler ABI info - done
-- Check for working CXX compiler: /usr/bin/c++
-- Check for working CXX compiler: /usr/bin/c++ - works
-- Configuring done
-- Generating done

DEBUG 级别（更详细信息）：

-- The CXX compiler identification is GNU 9.4.0
-- Detecting CXX compiler ABI info
   /usr/bin/c++ CMakeFiles/CMakeTmp/CMakeCXXCompilerABI.cpp -o CMakeFiles/CMakeTmp/cmTC_abcd
-- Detecting CXX compiler ABI info - done
-- Check for working CXX compiler: /usr/bin/c++
   /usr/bin/c++ CMakeFiles/CMakeTmp/testCXXCompiler.cxx -o CMakeFiles/CMakeTmp/cmTC_abcd
-- Check for working CXX compiler: /usr/bin/c++ - works
-- Configuring done
-- Generating done

5.3 静默模式

# 最小输出
$ cmake --quiet ..

# 或
$ cmake .. > /dev/null 2>&1

6. 常见输出信息解读

6.1 编译器检测信息

-- The CXX compiler identification is GNU 9.4.0

含义：检测到的 C++ 编译器是 GNU 9.4.0

-- The C compiler identification is Clang 12.0.0

含义：检测到的 C 编译器是 Clang 12.0.0

-- Check for working CXX compiler: /usr/bin/c++
-- Check for working CXX compiler: /usr/bin/c++ - works

含义：验证 C++ 编译器可以正常工作

-- Detecting CXX compiler ABI info
-- Detecting CXX compiler ABI info - done

含义：检测编译器的 ABI 信息，用于确定二进制兼容性

6.2 查找包信息

-- Found OpenCV: /usr/lib/x86_64-linux-gnu/libopencv_core.so (found version "4.5.1")

含义：成功找到 OpenCV 库，版本 4.5.1，路径为 /usr/lib/...

-- Could NOT find Boost (missing: Boost_INCLUDE_DIR)

含义：未找到 Boost 库，缺少 Boost_INCLUDE_DIR 变量

-- Found PkgConfig: /usr/bin/pkg-config (found version "0.29.2")

含义：找到 pkg-config 工具

-- Checking for module 'libcurl'
--   Found libcurl, version 7.68.0

含义：通过 pkg-config 找到 libcurl 模块

6.3 特性检测

-- Performing Test HAVE_CXX_ATOMICS
-- Performing Test HAVE_CXX_ATOMICS - Success

含义：测试 C++ 原子操作支持，成功

-- Looking for pthread.h
-- Looking for pthread.h - found

含义：查找 pthread.h 头文件，已找到

-- Looking for sin in m
-- Looking for sin in m - found

含义：在数学库中查找 sin 函数，已找到

6.4 配置进度

-- Configuring project: MyProject, version 1.0.0

含义：开始配置项目 MyProject，版本 1.0.0

-- Configuring done

含义：配置阶段完成，所有检查已完成

-- Generating done

含义：生成构建文件完成

-- Build files have been written to: /home/user/build

含义：构建文件已生成到指定目录

7. 错误信息解读

7.1 常见 CMake 错误

CMake Error: The source directory "/home/user/nonexistent" does not exist.

原因：指定的源码目录不存在 解决：检查路径是否正确

CMake Error: CMake was unable to find a build program corresponding to "Ninja".

原因：找不到指定的生成器（Ninja） 解决：安装 Ninja 或使用其他生成器

CMake Error at CMakeLists.txt:3 (add_executable):
  add_executable called with incorrect number of arguments

原因：CMakeLists.txt 语法错误 解决：检查命令参数数量

CMake Error: The following variables are used in this project, but they are set to NOTFOUND.

原因：某些必需的库或文件未找到 解决：安装缺失的依赖或设置正确的路径

7.2 编译器错误

CMake Error: Compiler /usr/bin/c++ does not support C++17.

原因：编译器不支持 C++17 解决：升级编译器或降低 C++ 标准要求

CMake Error in CMakeLists.txt:
  Target "myapp" links to target "OpenCV::OpenCV" but the target was not found.

原因：链接的目标不存在 解决：确保 find_package 成功或目标名称正确

CMake Error: Failed to create test executable

原因：无法创建测试可执行文件 解决：检查测试代码和链接库

7.3 详细错误示例

CMake Error at /usr/share/cmake-3.22/Modules/FindPackageHandleStandardArgs.cmake:230 (message):
  Could NOT find OpenCV (missing: OpenCV_INCLUDE_DIRS OpenCV_LIBS)
Call Stack (most recent call first):
  /usr/share/cmake-3.22/Modules/FindPackageHandleStandardArgs.cmake:594 (_FPHSA_FAILURE_MESSAGE)
  /usr/share/cmake-3.22/Modules/FindOpenCV.cmake:217 (find_package_handle_standard_args)
  CMakeLists.txt:15 (find_package)

分析：

  • 错误位置：FindPackageHandleStandardArgs.cmake 第230行
  • 错误原因：找不到 OpenCV，缺少 OpenCV_INCLUDE_DIRS 和 OpenCV_LIBS
  • 调用栈：从 CMakeLists.txt 第15行的 find_package 调用引发

8. 警告信息解读

8.1 常见警告

CMake Warning (dev) at CMakeLists.txt:5 (add_executable):
  Policy CMP0042 is not set: MACOSX_RPATH is enabled by default.

含义：CMake 策略警告，建议显式设置策略 解决：添加 cmake_policy(SET CMP0042 NEW)

CMake Deprecation Warning at CMakeLists.txt:2 (cmake_minimum_required):
  Compatibility with CMake < 2.8 will be removed from a future version.

含义：使用了过时的 CMake 版本兼容性 解决：更新 cmake_minimum_required 到更高版本

CMake Warning: Manually-specified variables were not used by the project:
  UNUSED_VARIABLE

含义：命令行指定的变量未被项目使用 解决：检查变量名是否正确，或删除未使用的变量

CMake Warning: Cannot generate a safe linker search path for target myapp

含义：无法生成安全的链接器搜索路径 解决：检查库依赖和 RPATH 设置

8.2 编译器警告

CMake Warning:
  The compiler path "/usr/bin/c++" does not exist.  The compiler may not be set correctly.

含义：指定的编译器路径不存在 解决：安装编译器或修正路径

CMake Warning: ignoring export of component 'Extra' because target 'extra_lib' not found.

含义：导出组件时找不到目标 解决：确保所有导出目标都已定义

9. 调试输出

9.1 启用调试模式

9.2 调试输出示例

$ cmake --trace ..

输出示例：

9.3 调试变量值

$ cmake --trace-expand ..

展开后的输出：

CMakeLists.txt(15):  message(STATUS "Build type: Release" )
-- Build type: Release
CMakeLists.txt(18):  add_executable(myapp main.cpp utils.cpp network.cpp )
CMakeLists.txt(19):  target_link_libraries(myapp PRIVATE fmt::fmt pthread )
CMakeLists.txt(20):  target_include_directories(myapp PRIVATE include /usr/include )

10. 实际案例解析

10.1 案例：完整的配置输出

$ cmake -B build -S . -DCMAKE_BUILD_TYPE=Release

完整输出及解释：

10.2 案例：构建输出

$ cmake --build build -j 4

完整输出及解释：

10.3 案例：测试输出

$ ctest

输出及解释：

总结

理解 CMake 输出内容的关键点：

  1. 前缀识别：-- 是状态信息，CMake Error 是错误，CMake Warning 是警告
  2. 上下文理解：注意输出中的文件路径和行号，它们指向问题位置
  3. 层级关系：缩进和调用栈显示问题的传播路径
  4. 关键信息：关注 found、missing、done、failed 等关键词
  5. 调试技巧：使用 --trace 和 --debug-output 获取更详细信息
  6. 日志级别：根据需求选择合适的日志级别

掌握这些输出信息的含义，可以快速定位和解决 CMake 构建过程中的问题。

为什么要学习LaTeX

LaTeX 是一种基于 TeX 的排版系统，由图灵奖得主 Lamport 开发，而 TeX 则是由 Knuth 最初开发，这两位都是计算机界的巨擘。当然开发者强并不是我们学习 LaTeX 的理由，LaTeX 和常见的所见即所得的 Word 文档最大的区别就是用户只需要关注写作的内容，而排版则完全交给软件自动完成。这让没有任何排版经验的普通人得以写出排版非常专业的论文或文章。

Berkeley 计算机系教授 Christos Papadimitriou 曾说过一句半开玩笑的话：

Every time I read a LaTeX document, I think, wow, this must be correct!

如何学习LaTeX

推荐的学习路线

  • LaTeX 的环境配置是个比较头疼的问题。如果你本地配置 LaTeX 环境出现了问题，可以考虑使用 Overleaf 这个在线 LaTeX 编辑网站。站内不仅有各种各样的 LaTeX 模版供你选择，还免去了环境配置的难题。

  • 阅读下面三篇 Tutorial: Part-1, Part-2, Part-3。

  • 学习 LaTeX 最好的方式当然是写论文，不过从一门数学课入手用 LaTeX 写作业也是一个不错的选择。

其他值得推荐的入门学习资料

  • 一份简短的安装 LaTeX 的介绍 [GitHub] 或者 TEX Live 指南（texlive-zh-cn）[PDF] 可以帮助你完成安装和环境配置过程

  • 一份（不太）简短的 LaTeX2ε 介绍（lshort-zh-cn）[PDF] [GitHub] 是由 CTEX 开发小组翻译的，可以帮助你快速准确地入门，建议通读一遍

  • 刘海洋的《LaTeX 入门》，可以当作工具书来阅读，有问题再查找，跳过 CTEX 套装部

  • 现代 LaTeX 入门讲座

  • 一份其实很短的 LaTeX 入门文档

本地编译LaTeX

感谢国内TUGers的卓越贡献，文档已相当成熟，请参考这篇文档：

VSCode + TeX Live

详见 VSCode配置LaTeX

云端编译LaTeX

如果你不想在本地配置 LaTeX 环境，或者需要多人协作编辑 LaTeX 文档，可以考虑使用云端编译服务。以下是一些推荐的云端 LaTeX 编辑器：

Overleaf

Overleaf 在全球都有着广泛的用户基础，尤其在学术界和教育界。它提供了一个在线 LaTeX 编辑器，支持实时协作和版本控制，非常适合团队合作和学术论文写作。不过国内的用户可能会遇到访问速度较慢的问题，订阅制收费也较贵。

重医专属Overleaf，参考公共服务-Overleaf LaTeX协作平台

官方中国站点：https://cn.overleaf.com/

LoongTeX

2024年12月，国内团队开发的自主编译器 LoongTeX 发布了 1.0 版本。LoongTeX 是一个基于 TeX Live 的 LaTeX 编译器，支持多种语言和字符集，特别适合中文用户。它提供了一个在线编辑器，支持实时预览和协作功能。

官方网站：https://loongtex.com/

TeXPage

TeXPage 是一个国内开发的在线 LaTeX 编辑器，提供了类似 Overleaf 的功能。它支持实时预览、版本控制和协作编辑，适合团队合作和学术论文写作。TeXPage 的界面简洁易用，适合初学者。

官方网站：https://texpage.com/

贡献者

codingLab

Code Guide © 2020-2025