C++ 项目约定：目录结构、依赖管理、构建与 Git

所谓「约定」= 一套项目结构规范 + 依赖管理规范：以后不管做什么项目，都按这个套路来，不用每次重新想。

适用背景：Windows（VS2022）只做 Boost + OpenCV，不做 Qt；Qt 开发放在 Linux（Ubuntu 虚拟机/服务器）。

文中 <OpenCV安装目录>、<Boost根目录>、<项目根目录> 为占位符，替换成本机实际目录即可。

一、总体原则

三句话：

CMake 是唯一的构建系统，不碰 qmake、不碰手动 .vcxproj。
依赖一律走环境变量 + find_package，不在 CMakeLists.txt 里硬编码路径。
Windows 端 IDE 是 VS2022 + CMake 项目模式；Linux 端用 Qt Creator 或 VS Code。

二、目录结构约定（Windows 端）

每个项目固定长这样：

<项目根目录>\<项目名>\
├── CMakeLists.txt
├── CMakePresets.json
├── CMakeUserPresets.json       # 本地预设（不提交 Git）
├── .gitignore
├── README.md
├── src\                        # 源码
│   ├── main.cpp
│   ├── core\                   # Boost 业务逻辑
│   │   ├── Service.h
│   │   └── Service.cpp
│   └── vision\                 # OpenCV 图像处理
│       ├── ImageProcessor.h
│       └── ImageProcessor.cpp
├── include\                    # 对外头文件（可选）
├── resources\                  # 静态资源、图片（可选）
├── tests\                      # 测试代码（可选）
├── third_party\                # 第三方源码（可选，一般不用）
└── out\                        # 构建输出（不提交 Git）
    └── build\
        ├── debug\
        └── release\

关键点：

src\ 按职责分目录：core、vision，一眼看出哪块用什么库。
out\ 是构建输出，永远不提交 Git。
不用 build\ 用 out\build\，和 VS2022 CMake 项目默认一致。

三、环境变量约定（Windows 端）

每台机器一次性配置，所有项目通用：

变量	指向	作用
`OpenCV_DIR`	`<OpenCV安装目录>\build\x64\vc16\lib`	OpenCV 的 CMake 配置目录
`BOOST_ROOT`	`<Boost根目录>`	Boost 根目录
`PATH` 追加	`<OpenCV安装目录>\build\x64\vc16\bin`	运行时找 OpenCV 的 dll

注意：

Boost 不用加 PATH，静态库，运行时不需要 dll。
OpenCV 的 dll 要加 PATH，动态库。
改完环境变量重启 VS。
Linux 端不需要环境变量，apt 装的 Qt 在标准路径，CMake 自动找到。

四、`CMakeLists.txt` 约定（Windows 端）

每个项目的 CMakeLists.txt 按这个模板来：

cmake_minimum_required(VERSION 3.20)
project(MyApp LANGUAGES CXX)
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
# ---------- Boost ----------
set(Boost_NO_SYSTEM_PATHS ON)
set(Boost_USE_STATIC_LIBS ON)
set(Boost_USE_MULTITHREADED ON)
find_package(Boost 1.81 REQUIRED COMPONENTS filesystem system thread)
# ---------- OpenCV ----------
find_package(OpenCV REQUIRED)
set(SOURCES
    src/main.cpp
    src/core/Service.cpp
    src/core/Service.h
    src/vision/ImageProcessor.cpp
    src/vision/ImageProcessor.h
)
add_executable(${PROJECT_NAME} ${SOURCES})
target_include_directories(${PROJECT_NAME} PRIVATE
    ${CMAKE_CURRENT_SOURCE_DIR}/src
    ${OpenCV_INCLUDE_DIRS}
)
target_link_libraries(${PROJECT_NAME} PRIVATE
    Boost::filesystem
    Boost::system
    Boost::thread
    ${OpenCV_LIBS}
)

关键点：

Boost 用 Target 写法（Boost::filesystem 等）。
OpenCV 走 ${OpenCV_LIBS}。
源码用变量集中管理，加文件时改一处。

五、`CMakePresets.json` 约定（Windows 端）

项目根目录的 CMakePresets.json（可提交 Git）：

{
  "version": 3,
  "configurePresets": [
    {
      "name": "debug",
      "generator": "Ninja",
      "binaryDir": "${sourceDir}/out/build/${presetName}",
      "cacheVariables": {
        "CMAKE_BUILD_TYPE": "Debug",
        "OpenCV_DIR": "$env{OpenCV_DIR}",
        "BOOST_ROOT": "$env{BOOST_ROOT}",
        "Boost_NO_SYSTEM_PATHS": "ON",
        "Boost_USE_STATIC_LIBS": "ON",
        "Boost_USE_MULTITHREADED": "ON"
      }
    },
    {
      "name": "release",
      "inherits": "debug",
      "cacheVariables": {
        "CMAKE_BUILD_TYPE": "Release"
      }
    }
  ]
}

版本待核实：预设文件 "version": 3 与模板 CMakeLists.txt 里 cmake_minimum_required(VERSION 3.20) 的版本要求是否匹配（version 3 预设需较新的 CMake），首次配置前请确认本机 / VS2022 自带 CMake 的实际版本。

关键点：

所有路径走环境变量，预设文件本身不绑定具体机器。
binaryDir 统一在 out/build/。
Debug 和 Release 两个 preset，VS 里能直接切。

六、`.gitignore` 约定

每个项目根目录放这个：

.vs/
out/
CMakeUserPresets.json
*.user
*.suo
*.pdb
*.ilk

提交到 Git 的：

CMakeLists.txt
CMakePresets.json
src/、resources/、include/
.gitignore
README.md

不提交的：

.vs/：VS 本地状态
out/：构建产物
CMakeUserPresets.json：本地路径

七、两库协作的职责划分（Windows 端）

层	库	职责	放在
业务层	Boost	文件系统、线程、网络、日志	`src/core/`
视觉层	OpenCV	图像处理、特征检测、视频分析	`src/vision/`

交互流向：

Boost 业务逻辑  →  调用  →  OpenCV 视觉处理
   ↑                    ↓
   └──── 回调/结果回传 ────┘

约定：

业务层和视觉层各管各的，通过接口解耦，不互相直接依赖。
每一层有独立的头文件，接口清晰。

八、Linux 端（Qt 开发）

Qt 在 Ubuntu 里：

apt 装：qtbase5-dev qtcreator。
Qt 版本：Qt 5.15.13，装完在标准路径 /usr/lib/x86_64-linux-gnu/cmake/Qt5。
不需要环境变量，CMake 自动找到。
开发工具：Qt Creator 或 VS Code。

Linux 端的 CMakeLists.txt：

cmake_minimum_required(VERSION 3.20)
project(MyQtApp LANGUAGES CXX)
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_AUTOMOC ON)
set(CMAKE_AUTORCC ON)
set(CMAKE_AUTOUIC ON)
find_package(Qt5 REQUIRED COMPONENTS Core Widgets Gui)
add_executable(${PROJECT_NAME}
    src/main.cpp
    src/MainWindow.cpp
    src/MainWindow.h
    src/MainWindow.ui
)
target_link_libraries(${PROJECT_NAME} PRIVATE
    Qt5::Core
    Qt5::Widgets
    Qt5::Gui
)

九、两个环境，两套工具

	Windows（VS2022）	Linux（Ubuntu）
开发	Boost + OpenCV	Qt
构建	CMake + Ninja + MSVC	CMake + GCC
环境变量	`BOOST_ROOT`、`OpenCV_DIR`	无（apt 路径标准）
CMake	`find_package(Boost)`、`find_package(OpenCV)`	`find_package(Qt5)`

十、新建项目的标准流程

以后新建项目，按这个顺序：

建目录：<项目根目录>\<项目名>\，纯英文无特殊字符。
建 src\core、src\vision 两个子目录。
写 CMakeLists.txt，用上面的模板。
写 CMakePresets.json，用上面的模板。
写 .gitignore。
VS2022 打开文件夹，它会自动识别 CMake 项目。
选 preset：VS 工具栏选 debug 或 release。
F5 构建运行。

十一、检查清单

新建项目时，对照这几条：

环境变量 OpenCV_DIR、BOOST_ROOT 都设了
PATH 里有 OpenCV 的 bin
CMakeLists.txt 里 find_package Boost、OpenCV 都有
CMakePresets.json 里路径走环境变量
.gitignore 忽略了 .vs/ 和 out/
源码按 core/、vision/ 分目录
项目路径纯英文，无空格、无 ++
Linux 端 Qt 项目：find_package(Qt5)，不设环境变量

十二、总结

Windows 端：只用 Boost + OpenCV，不配 Qt（不需要 QTDIR 环境变量，CMake 中不含 Qt 部分）。Linux 端：只用 Qt，apt 安装，CMake find_package(Qt5)，不需要环境变量。两个环境，两套工具，各管各的。

这套约定落地成了两个可复制的模板工程：BoostTemplate 与 OpenCVTemplate。

一、总体原则#

二、目录结构约定（Windows 端）#

三、环境变量约定（Windows 端）#

四、CMakeLists.txt 约定（Windows 端）#

五、CMakePresets.json 约定（Windows 端）#

六、.gitignore 约定#

七、两库协作的职责划分（Windows 端）#

八、Linux 端（Qt 开发）#

九、两个环境，两套工具#

十、新建项目的标准流程#

十一、检查清单#

十二、总结#

一、总体原则

二、目录结构约定（Windows 端）

三、环境变量约定（Windows 端）

四、`CMakeLists.txt` 约定（Windows 端）

五、`CMakePresets.json` 约定（Windows 端）

六、`.gitignore` 约定

七、两库协作的职责划分（Windows 端）

八、Linux 端（Qt 开发）

九、两个环境，两套工具

十、新建项目的标准流程

十一、检查清单

十二、总结