跳到正文

Wiki

模板擴展與常見問題

約 11 分鐘閱讀

本文由簡體中文內容確定性轉換，並受版本化術語表保護。

本節整理使用這個 CMake 模板時最常見的擴展方式和問題排查。

1.添加新的源文件

當前庫目錄使用：

file(GLOB_RECURSE ${PREFIX}_SRC_LIST CONFIGURE_DEPENDS
  "${CMAKE_CURRENT_LIST_DIR}/src/*.c"
  "${CMAKE_CURRENT_LIST_DIR}/src/*.cpp"
)

所以只要把新的 .cpp 放到對應模塊的 src/ 目錄下，CMake 會自動收集。

例如：

src/lib1/src/math_utils.cpp

然後重新構建：

cmake --build --preset linux-debug

如果發現新文件沒有參與編譯，可以手動重新 configure：

cmake --preset linux-debug
cmake --build --preset linux-debug

2.添加新的頭文件

推薦路徑：

src/lib1/inc/lib1/math_utils.hpp

代碼中包含：

#include "lib1/math_utils.hpp"

不要直接放成：

src/lib1/inc/math_utils.hpp

因為多個庫可能出現同名頭文件。使用 inc/lib1/ 這種結構可以避免衝突。

3.添加新的庫模塊

假設要添加 lib3。

目錄結構：

src/lib3/
├── CMakeLists.txt
├── inc/
│   └── lib3/
│       └── example.hpp
└── src/
    └── example.cpp

src/lib3/CMakeLists.txt：

set(PREFIX "lib3")

file(GLOB_RECURSE ${PREFIX}_SRC_LIST CONFIGURE_DEPENDS
  "${CMAKE_CURRENT_LIST_DIR}/src/*.c"
  "${CMAKE_CURRENT_LIST_DIR}/src/*.cpp"
)

add_library(${PREFIX}_src_lib
  ${${PREFIX}_SRC_LIST}
)

target_include_directories(${PREFIX}_src_lib
  PUBLIC
    $<BUILD_INTERFACE:${CMAKE_CURRENT_LIST_DIR}/inc>
    $<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}>
)

target_link_libraries(${PREFIX}_src_lib
  PUBLIC
    project_options
  PRIVATE
    project_warnings
)

# ========================
# Third-party dependencies
# ========================

# =======
# Install
# =======

install(TARGETS ${PREFIX}_src_lib
  LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
  ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}
  RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
)

install(DIRECTORY "${CMAKE_CURRENT_LIST_DIR}/inc/"
  DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}
)

example.hpp 使用普通的 C++ 函數聲明：

#pragma once

namespace lib3 {
void example();
}

對應的 example.cpp 包含這個頭文件，並提供 lib3::example() 的定義。

然後在 src/CMakeLists.txt 中添加：

add_subdirectory(lib3)

並鏈接到主程序：

target_link_libraries(${PROJECT_NAME}
  PRIVATE
    lib1_src_lib
    lib2_src_lib
    lib3_src_lib
)

4.添加新的可執行文件

如果一個項目有多個程序，例如：

src/main.cpp
src/tools/calibrate_camera.cpp

可以在 src/CMakeLists.txt 裏添加：

add_executable(calibrate_camera
  ${CMAKE_CURRENT_SOURCE_DIR}/tools/calibrate_camera.cpp
)

target_link_libraries(calibrate_camera
  PRIVATE
    project_options
    project_warnings
    lib1_src_lib
    lib2_src_lib
)

set_target_properties(calibrate_camera PROPERTIES
  INSTALL_RPATH "$ORIGIN/../${CMAKE_INSTALL_LIBDIR}"
)

install(TARGETS calibrate_camera
  RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
)

安裝後：

install/linux-debug/bin/calibrate_camera

5.改項目名

頂層：

project(cmake_template VERSION 1.0.0 LANGUAGES C CXX)

改成：

project(robot_app VERSION 1.0.0 LANGUAGES C CXX)

因為主程序使用：

add_executable(${PROJECT_NAME}
  ${CMAKE_CURRENT_SOURCE_DIR}/main.cpp
)

所以可執行文件會從：

cmake_template

變成：

robot_app

README 裏的運行命令也要同步改：

./install/linux-debug/bin/robot_app

6.改 C++ 標準

當前模板默認使用 C++20：

set(CMAKE_CXX_STANDARD 20)
target_compile_features(project_options INTERFACE cxx_std_20)

如果要改 C++23：

set(CMAKE_CXX_STANDARD 23)
target_compile_features(project_options INTERFACE cxx_std_23)

如果項目使用 C++17：

set(CMAKE_CXX_STANDARD 17)
target_compile_features(project_options INTERFACE cxx_std_17)

修改 cmake/ProjectOptions.cmake 中已有的這兩行，並確認編譯器支持對應標準模式；具體語法和標準庫功能還取決於編譯器及其標準庫版本。本模板的 CMake 最低版本仍為 3.22。

7.改動態庫為靜態庫

如果某個模塊顯式指定動態庫：

add_library(${PREFIX}_src_lib SHARED
  ${${PREFIX}_SRC_LIST}
)

改成靜態庫：

add_library(${PREFIX}_src_lib STATIC
  ${${PREFIX}_SRC_LIST}
)

動態庫和靜態庫對比：

類型 優點 缺點
SHARED 可執行文件較小，庫可獨立更新 Linux 運行時要能找到相應 .so
STATIC 部署簡單，很多代碼打進可執行文件 可執行文件更大，更新庫要重新鏈接

本模板採用下一節的配置方式：Linux 預設使用動態庫，Windows 預設使用靜態庫。兩種方式都保留同樣的頭文件聲明和調用代碼。

8.用 BUILD_SHARED_LIBS 控制庫類型

當前模板不寫死庫類型：

add_library(${PREFIX}_src_lib
  ${${PREFIX}_SRC_LIST}
)

然後在 preset 中控制：

"BUILD_SHARED_LIBS": "ON"

或：

"BUILD_SHARED_LIBS": "OFF"

ON 選擇動態庫，OFF 選擇靜態庫。當前 Linux 預設為 ON，Windows 預設為 OFF，Release 繼承對應設置。不要在模塊中再寫死 SHARED，否則會繞開這個開關。

9.添加宏定義

給某個 target 添加宏：

target_compile_definitions(${PREFIX}_src_lib
  PRIVATE
    LIB1_ENABLE_LOG
)

C++ 中使用：

#ifdef LIB1_ENABLE_LOG
// log code
#endif

帶值宏：

target_compile_definitions(${PREFIX}_src_lib
  PRIVATE
    LIB1_VERSION="1.0.0"
)

可見性選擇：

關鍵字 場景
PRIVATE 隻影響本庫源碼
PUBLIC 本庫源碼和使用者都需要這個宏
INTERFACE 本 target 自己不用，只傳給使用者

10.添加編譯選項

給某個庫單獨加選項：

target_compile_options(${PREFIX}_src_lib
  PRIVATE
    -Wshadow
)

不建議用全局：

add_compile_options(-Wshadow)

因為全局選項會影響所有 target，不利於排查。

11.添加 include 路徑

推薦：

target_include_directories(${PREFIX}_src_lib
  PRIVATE
    ${CMAKE_CURRENT_LIST_DIR}/some_private_include
)

不推薦：

include_directories(some_private_include)

原因：

  1. include_directories 是目錄級影響，範圍更大。
  2. target_include_directories 能明確説明哪個 target 需要這個路徑。

12.添加測試目錄

如果以後要加測試，可以新增：

test/
└── CMakeLists.txt

頂層添加：

include(CTest)

if(BUILD_TESTING)
  add_subdirectory(test)
endif()

preset 中可以控制：

"BUILD_TESTING": "ON"

不過當前模板要求不新增 examples，測試目錄是否添加要看項目需求。

13.模板已有的運行測試

原始模板已經通過 include(CTest) 啓用測試。構建後可以執行 ctest --preset linux-debug 或 ctest --preset windows-debug。

eigen_example 檢查原始 Eigen 輸出。把 main.cpp 換成 Hello World 或其他練習以後，這個測試的輸出斷言也要調整；測試失敗不等於新程序無法編譯。添加真實業務後，應為新行為編寫對應測試。

14.清理構建和安裝目錄

因為模板已經有 .gitignore 忽略：

build/
install/
log/

所以這些目錄都是生成物。

清理 Debug：

rm -rf build/linux-debug install/linux-debug

清理 Release：

rm -rf build/linux-release install/linux-release

重新構建：

cmake --preset linux-debug
cmake --build --preset linux-debug
cmake --install build/linux-debug

Windows 的 PowerShell 中，先確認對應目錄存在，再清理：

Remove-Item -Recurse -Force build/windows-debug
Remove-Item -Recurse -Force install/windows-debug
cmake --preset windows-debug

清理前檢查當前工作目錄和要刪除的路徑。不同編譯器、不同平台使用各自的 preset 目錄，不共用同一份 CMake 緩存。

15.為什麼安裝目錄裏可能是 lib64

本模板使用：

include(GNUInstallDirs)

庫安裝時使用：

LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}

在某些 Linux 發行版上：

CMAKE_INSTALL_LIBDIR = lib64

所以安裝結果是：

install/linux-debug/lib64/

這不是錯誤，而是系統慣例。

不要手寫：

LIBRARY DESTINATION lib

否則會繞開 CMake 對系統目錄的判斷。

16.Linux 運行時報找不到 .so

錯誤類似：

error while loading shared libraries: liblib1_src_lib.so: cannot open shared object file

常見原因：

  1. 沒有執行 cmake --install ...。
  2. 可執行文件不是從安裝目錄運行的。
  3. 主程序或其依賴庫的 INSTALL_RPATH 沒設置對。
  4. 手動移動了 bin/ 或 lib64/ 的相對位置。

本模板在 src/CMakeLists.txt 中為主程序設置：

set_target_properties(${PROJECT_NAME} PROPERTIES
  INSTALL_RPATH "$ORIGIN/../${CMAKE_INSTALL_LIBDIR}"
)

還在 src/lib1/CMakeLists.txt 中為 lib1 設置：

set_target_properties(${PREFIX}_src_lib PROPERTIES
  INSTALL_RPATH "$ORIGIN"
)

前者從主程序的 bin/ 目錄找到庫目錄，後者讓 lib1 找到同目錄的 lib2。如果報錯提到 liblib2_src_lib.so，即使主程序已經設置了搜索路徑，也應檢查 lib1 的配置。修改後重新 Configure、Build 和 Install，再運行安裝後的程序。

以庫目錄為 lib64 的系統為例，保持這種結構即可：

install/linux-debug/
├── bin/
│   └── cmake_template
└── lib64/
    ├── liblib1_src_lib.so
    └── liblib2_src_lib.so

17.Windows 程序啓動失敗

先確認運行的是 build/windows-debug/bin/cmake_template.exe，並且所用 GCC 的 bin/ 在 PATH 中。默認 MSYS2 安裝位置對應 C:/msys64/ucrt64/bin。

驗證安裝結果時，重新執行：

cmake --install build/windows-debug
./install/windows-debug/bin/cmake_template.exe

安裝後保持整個目錄結構再移動、運行。新增第三方依賴時，按相應庫的安裝要求檢查運行環境。

18.CMake 找不到 Eigen 或 OpenCV

先確認安裝開發包。

Eigen：

sudo apt install libeigen3-dev
sudo dnf install eigen3-devel

OpenCV：

sudo apt install libopencv-dev
sudo dnf install opencv-devel

再重新 configure：

cmake --preset linux-debug

如果庫安裝在非標準路徑，添加：

cmake --preset linux-debug -DCMAKE_PREFIX_PATH=/opt/my_library

或者寫入 preset：

"CMAKE_PREFIX_PATH": "/opt/my_library"

19.ccache 導致 configure 失敗

有些環境中，gcc、g++ 可能指向 ccache 包裝器。如果 ccache 目錄不可寫，CMake 檢查編譯器時可能失敗。

臨時解決：

rm -rf build/linux-debug
CC=/usr/bin/gcc CXX=/usr/bin/g++ cmake --preset linux-debug

這只是驗證或特殊環境下的處理，不建議寫死到模板中。

如果你確實想在 preset 裏指定編譯器，可以加：

"cacheVariables": {
  "CMAKE_C_COMPILER": "/usr/bin/gcc",
  "CMAKE_CXX_COMPILER": "/usr/bin/g++"
}

但這會降低模板通用性，所以默認不寫。

20.clangd 找不到項目頭文件或第三方庫

如果工程能夠正常編譯，但 VSCode 仍然提示找不到項目頭文件、Eigen 或 OpenCV，通常不是 target_include_directories 寫錯了，而是 clangd 沒有讀取 CMake 生成的編譯數據庫。

先確認 Debug 編譯數據庫存在：

cmake --preset linux-debug
test -f build/linux-debug/compile_commands.json && echo "找到了编译数据库"

然後在項目根目錄創建 .clangd：

CompileFlags:
  CompilationDatabase: build/linux-debug

在 VSCode 命令面板執行：

clangd: Restart language server

再到 查看 -> 输出 -> clangd 檢查日誌。正常日誌應包含：

Loaded compilation database from .../build/linux-debug/compile_commands.json

如果日誌出現：

Failed to find compilation database
command clangd fallback

説明 clangd 還在使用 fallback 參數，項目的 include 路徑、第三方庫 路徑和 C++ 標準都可能識別錯誤。

關於 compile_commands.json、.clangd、Debug/Release 數據庫切換和 命令行驗證的完整説明，見 CMakePresets與構建安裝。

Windows 下先確認 .clangd 的 CompilationDatabase 指向 build/windows-debug，並使用正確的 clangd.exe。如果能編譯卻找不到標準庫頭文件，可按 Windows 環境搭建 配置 --query-driver。

21.VSCode 裏沒有識別 preset

檢查：

  1. 是否安裝 CMake Tools 擴展。
  2. 打開的目錄是否是項目根目錄。
  3. CMakePresets.json 是否在項目根目錄。
  4. JSON 是否合法。

命令行檢查：

cmake --list-presets

如果命令行能看到：

linux-debug
linux-release

説明 preset 文件本身沒問題。

Windows 的配置列表對應 windows-debug、windows-release。如果 CMake Tools 仍拿到舊工具路徑，重啓 VSCode，再用 where.exe g++、where.exe cmake 檢查；更換編譯器後清理對應構建緩存。

22.VSCode CMake Tools 不能運行或調試

CMake Tools 運行或調試需要幾件事同時正常：

  1. CMake Tools 能識別 preset。
  2. 工程已經 Configure 和 Build。
  3. CMake Tools 已經選擇可執行 target。
  4. 如果要 Debug，GDB 能正常啓動。

22.1.檢查 preset

先確認 VSCode 打開的是項目根目錄，並且能識別 CMakePresets.json。

命令行可以這樣檢查：

cmake --list-presets

如果能看到：

linux-debug
linux-release

説明 preset 文件本身沒問題。

VSCode 裏則需要選擇 Configure Preset，例如：

Linux Debug

然後執行 Configure。

22.2.檢查 target

CMake Tools 需要知道你要運行或調試哪個可執行 target。

模板裏的可執行 target 是：

cmake_template

如果運行或調試按鈕不可用，先確認 CMake Tools 已經選擇了 cmake_template。

22.3.檢查是否已經構建

CMake Tools 運行或調試的通常是 build 目錄裏的可執行文件，例如：

build/linux-debug/src/cmake_template

如果還沒有 Build，這個文件不存在，運行或調試就無法啓動。

先執行：

cmake --preset linux-debug
cmake --build --preset linux-debug

或者在 VSCode CMake Tools 中執行 Configure 和 Build。

22.4.檢查 gdb

如果只是普通運行程序，不一定需要 GDB。如果要 Debug，就需要確認 GDB 已安裝。

命令行檢查：

gdb --version

沒有安裝就執行：

sudo apt install gdb

或：

sudo dnf install gdb

22.5.運行和調試不需要每次 install

日常開發時，CMake Tools 通常運行的是 build 目錄產物：

./build/linux-debug/src/cmake_template

不是安裝目錄產物：

./install/linux-debug/bin/cmake_template

install 主要用於驗證安裝佈局、頭文件安裝、動態庫 RPATH 等是否正確。

23..gitignore 怎樣處理 VSCode 配置

這個模板不依賴額外的 VSCode 調試配置文件，因為 CMake Tools 可以直接運行或調試當前 CMake target。

如果不想把個人 VSCode 配置提交到倉庫，可以直接忽略 .vscode/：

.vscode/

也可以只忽略常見的本地配置：

.vscode/settings.json
.vscode/tasks.json

如果團隊確實想共享某些 VSCode 配置，比如推薦擴展或格式化設置，可以單獨討論哪些文件進入 Git。運行和調試本身可以交給 CMake Tools。

24.模板的核心規則

最後總結一下這個模板最重要的幾條規則：

  1. 頂層 CMakeLists.txt 只做總控。
  2. 公共編譯規則放在 cmake/ProjectOptions.cmake。
  3. 主程序由 src/CMakeLists.txt 管理。
  4. 每個庫目錄自己管理自己的源碼、頭文件、安裝和第三方依賴。
  5. 頭文件路徑帶模塊名，例如 lib1/eigen3_test.hpp。
  6. 第三方庫放在使用者自己的 Third-party dependencies 區塊。
  7. 構建參數放在 CMakePresets.json，不要寫死在頂層 CMake。
  8. 生成目錄 build/、install/、log/ 不進入 Git。
  9. VSCode 裏運行和調試交給 CMake Tools，命令行構建仍然交給 CMakePresets。

25.Windows 的運行和調試路徑

前面圖形界面操作中選擇 cmake_template target 的方法不變。Windows 使用 windows-debug，運行的程序是 build/windows-debug/bin/cmake_template.exe。

GDB 來自同一套工具鏈，默認 MSYS2 路徑為 C:/msys64/ucrt64/bin/gdb.exe。先用 CMake Tools 的 Debug 按鈕檢查；想使用 F5 時，把 CMake: Debug 綁定到 F5 即可。

如果舊版本教程中看到 cmake --fresh，注意該選項從 CMake 3.24 才加入。本模板兼容 CMake 3.22，因此這裏統一用清理構建目錄後重新 Configure 的方式處理緩存。參見 CMake 3.24 發佈説明。