Wiki

Windows开发环境搭建与测试

更新于 2023-10-05约 27 分钟阅读

这一章先不改代码，只做一件很具体的事：

在 Windows 上把我准备好的 CMake 模板跑起来。

我们继续使用 GCC、CMake、Ninja 和 VSCode。准备好环境后，后面的 C++ 代码和 Linux 章节共用，不需要再学一套语法。如果你用的是 Linux，请看 Linux开发环境搭建与测试。

1.本章最终效果

这一章会按下面的顺序来：

安装 MSYS2，用它准备 GCC、CMake、Ninja、GDB 和 Eigen。
配置 Windows 的 PATH，检查这些工具能否正常运行。
下载模板，选择 windows-debug，先原样运行。
用 VSCode 构建、运行和调试模板程序。
确认以后在哪里写代码、在哪里重新构建。

本节按 Windows 10 / 11 的 64 位环境讲解。工具的安装窗口和版本号可能会变化，重点看工具名称、安装路径和命令输出。

2.为何采用 MSYS2

因为Linux安装这些环境只需要一条命令，而傻逼Windows需要下载压缩包，解压，图形化配置环境变量等巨繁琐，巨傻逼的若干操作。而MSYS2可以为Windows提供近似Linux配置环境的体验，而且MSYS2也算是比较主流的工具了，所以选择MSYS2。

3.先认识 MSYS2 和 UCRT64

MSYS2 是 Windows 上的一套开发工具和软件包管理环境。我们用它安装编译器和依赖，类似 Linux 用 apt 或 dnf 安装软件。

UCRT64 是 MSYS2 提供的一种环境，使用 GCC，面向 64 位 Windows，并采用微软的 UCRT。这里统一选择它，安装的软件包也都使用 mingw-w64-ucrt-x86_64- 前缀。

名字	本章里负责什么
MSYS2	安装、更新开发工具和库
UCRT64	本章使用的 64 位 Windows GCC 环境
`pacman`	MSYS2 的软件包管理命令
`gcc` / `g++`	编译 C / C++ 代码
CMake / Ninja	配置工程、执行构建
GDB	下断点、查看变量、单步运行

这些工具生成的是原生 Windows 可执行程序。模板本身没有写死 MSYS2 路径，也可以使用独立安装的 MinGW-w64 工具链。

环境区别见 MSYS2 官方说明，VSCode 的 Windows GCC 教程也使用这条安装路线。

4.安装基础工具

4.1.良好的网络

你需要有良好的网络能够访问中国大陆以外的服务器，不懂的私聊别人。

4.2.MSYS2

4.2.1.安装MSYS2

打开 MSYS2 官网，下载并运行安装程序。机器人队官方链接：山理工Vinci机器人队下载网站

点击后就可以下载一个exe文件打开它。

下面统一假设安装到：

C:\msys64

如果你安装到了其他位置，后面出现的路径也要对应修改。

安装完成后，从开始菜单打开 MSYS2 UCRT64 终端，先更新：

运行下面这条命令，这条命令是更新软件包的：

pacman -Syu

中间有error错误先不要慌张，等看看他会出现下图这种让你关闭所有终端的命令不？

如果更新程序提示关闭终端，就按提示关闭，再重新打开 UCRT64 终端，再运行一次更新命令。

遇到下面这种让你输入yes or no的请输入 y 并回车。

再次打开终端：

pacman -Syu

再次遇到这种error错误不要慌张，继续根据提示来就行遇到下面这种让你输入yes or no的请输入 y 并回车。

像下面这样就成功了：

可以再试一次

pacman -Syu

下图这样说明软件都是最新的，所以说明上面那个操作是成功的。

4.2.2.换源

从开始菜单打开 MSYS2 UCRT64 终端：

然后：

sed -i "s#https\?://mirror.msys2.org/#https://mirrors.tuna.tsinghua.edu.cn/msys2/#g" /etc/pacman.d/mirrorlist*

完毕

4.2.3.安装编译器、构建工具和依赖

仍然在 UCRT64 终端中执行（这就是类似Linux的安装环境的命令）：

pacman -S --needed \
  mingw-w64-ucrt-x86_64-git \
  mingw-w64-ucrt-x86_64-gcc \
  mingw-w64-ucrt-x86_64-cmake \
  mingw-w64-ucrt-x86_64-ninja \
  mingw-w64-ucrt-x86_64-gdb \
  mingw-w64-ucrt-x86_64-eigen3

出现确认提示时，确认安装即可。遇到下面这种让你输入yes or no的请输入 y 并回车。

等待安装完毕即可

中间有这种错误先不要慌张

当看到最后是下图，说明 pacman 成功完成了全部 65 个软件包的安装。

(41/65) installing mingw-w64-ucrt-x86_64-gcc
...
(52/65) installing mingw-w64-ucrt-x86_64-cmake
...
(65/65) installing mingw-w64-ucrt-x86_64-eigen3

其中 eigen3 是模板原始示例用到的库。这里使用的是软件包名称，实际库版本以仓库当前提供的版本为准；在 CMake 中仍然使用 Eigen3::Eigen 这个目标。

注意：本节的软件包都来自 UCRT64 环境。不要把 /usr/bin 中面向 MSYS 环境的编译器当成这里的 Windows MinGW-w64 编译器。

验证：

gcc --version
g++ --version
cmake --version
ninja --version
gdb --version
git --version

像下图这样都有输出说明编译所需的软件全部安装成功了。

4.2.4.配置 PATH

安装完工具后，需要让 PowerShell 和 VSCode 能找到它们。

默认安装位置对应的工具目录是：

C:\msys64\ucrt64\bin

在 Windows 开始菜单搜索“编辑账户的环境变量”，打开后：

找到用户变量中的 Path。

点击编辑，再点击新建。

添加上面的 C:\msys64\ucrt64\bin。

保存后，关闭已经打开的 PowerShell 和 VSCode，再重新打开。

注意：是在原来的 Path 中增加一项，不是把原来的内容全部替换掉。

4.2.5.检查工具是否安装成功

下面开始，除非专门标明 UCRT64 终端，否则 Windows 命令都在 PowerShell 中执行。

右键开始菜单(微软LOGO)，点击PowerShell

git --version
cmake --version 
ninja --version
gcc --version
g++ --version
gdb --version

这些命令都能输出版本号，说明基础工具已经能被找到。 CMake 要求 3.22 或更新版本，编译器需要支持 C++20。

如果电脑上曾经安装过其他编译器，再检查实际调用的是哪一个：

where.exe gcc
where.exe g++
where.exe cmake
where.exe ninja
g++ -dumpmachine

按照本节安装时，前几项路径应指向 C:\msys64\ucrt64\bin，-dumpmachine 通常会输出：

x86_64-w64-mingw32

这里的目标名称并不表示只能生成 32 位程序，前面的 x86_64 才说明本节使用的是 64 位目标。

5.VScode

5.1.安装VScode

先百度官网：https://code.visualstudio.com/

这个下面的路径建议默认，你也可以选择其他地方，但需要保证纯英文路径和有权限的路径（如果你不懂，建议默认）。

必须像这样勾选

等待进度条滚完就结束了。

5.2.配置VScode

打开 VSCode 后，可以像 Linux 章节一样，为 C++ 单独建立一个配置文件。

然后可以配置一个环境单独给C++环境使用，避免和默认环境冲突。

alt text

进行一些设置，按我的来就可以

alt text

选中你创建的CMake配置

alt text

扩展主要安装：

CMake Tools。
C/C++，用于 GDB 调试。
C/C++ DevTools，按需要使用。
clangd，用于代码提示、跳转和诊断。

如果你使用 clangd 做代码提示，建议关闭或弱化 C/C++ 扩展的 IntelliSense，避免两个语言服务器同时工作导致提示重复或冲突。

alt text

6.clone CMake 模板

在准备放工程的目录中打开 PowerShell：这个目录尽量是纯英文的，你自己整个就行。比如C:\Users\Tung Chia-hui\UserFolder\MySource:

cd 'C:\Users\Tung Chia-hui\UserFolder\MySource'
git clone https://github.com/tungchiahui/CMake_Template.git hello_cpp
cd hello_cpp
code .

hello_cpp 是项目文件夹名，模板当前的程序名仍然是 cmake_template。

先信任一下：

后面的命令都在这个工程根目录执行。先不要修改 CMake 文件，也不要急着把示例库删掉，先确认原始工程能运行。

7.先原样跑通模板

7.1.用命令行方式运行

在 VSCode 中打开 PowerShell 终端（快捷键：Ctrl + `），（反引号键，在键盘左上角，Esc 下方）执行：

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

输出应类似：

[lib1] Vector v = 1 2 3
[lib1] Norm = 3.74166
[lib2] Matrix m =
1 2
3 4
[lib2] Determinant = -2

说明 GCC、CMake、Ninja、Eigen 和模板中的两个动态库已经能够一起工作。

Windows 中构建出的程序位于：

build/windows-debug/bin/cmake_template.exe

Windows 预设会把两个示例库静态链接到主程序中。写练习时继续使用普通函数声明，按前面的命令重新构建、运行即可。

原样模板还带有一个运行检查，可以执行：

ctest --preset windows-debug

后面的练习会修改 main.cpp，输出也会改变。这个测试检查的是原始 Eigen 示例，不是所有练习的统一判题器；开始改示例后，日常使用 Build 和 Launch 即可。

7.2.用 VSCode 图形化方式运行

打开左侧 CMake 面板，按照下面的顺序操作：

选择 Configure，然后再点击Windows GCC Debug，对应的 preset 名是 windows-debug。

一般来说会自动config，也就是终端底下冒出来一大堆东西：

这样就是成功了：

[cmake] -- Configuring done (0.3s)
[cmake] -- Generating done (0.1s)

点击 Build（下面这俩按钮都是build，点哪个都行）

点击debug选择 cmake_template 作为运行或调试的 target。

点击 Launch，观察终端中的示例输出。（下面这俩按钮都是launch，点哪个都行）

这些操作分别对应刚才的 configure、build 和运行命令。以后改完代码后，通常只需要再次 Build，再 Launch。

7.3.下断点并调试

打开 src/main.cpp，在调用 lib1::run_eigen_vector_example() 的行号旁单击，添加一个断点。

确认仍然选择 Debug 预设和 cmake_template target，然后点击 CMake Tools 的 Debug 按钮。程序停在断点处后，可以查看调用栈、变量并单步进入函数。（下面这俩按钮都是debug，点哪个都行）

能出现下面这样说明配置成功了

如果提示找不到调试器，先在 PowerShell 中确认 gdb --version 能运行。默认安装位置的 GDB 为：

C:/msys64/ucrt64/bin/gdb.exe

可以在 VSCode 的 CMake Tools 调试设置中指定：

{
  "cmake.debugConfig": {
    "MIMode": "gdb",
    "miDebuggerPath": "C:/msys64/ucrt64/bin/gdb.exe"
  }
}

想用 F5 执行同样的操作时，打开 VSCode 键盘快捷方式，搜索 CMake: Debug 并绑定 F5。这样会调试当前 CMake target，无需手写 launch.json。

8.配置 clangd

在 UCRT64 终端安装 clangd 程序：

pacman -S --needed mingw-w64-ucrt-x86_64-clang-tools-extra

有错误不要怕，出现下面这个样子肯定是安装好了

:: Processing package changes...
(1/5) installing mingw-w64-ucrt-x86_64-libxml2               [###############################] 100%
Optional dependencies for mingw-w64-ucrt-x86_64-libxml2
    mingw-w64-ucrt-x86_64-python: Python bindings [installed]
(2/5) installing mingw-w64-ucrt-x86_64-llvm-libs             [###############################] 100%
(3/5) installing mingw-w64-ucrt-x86_64-clang-libs            [###############################] 100%
(4/5) installing mingw-w64-ucrt-x86_64-clang                 [###############################] 100%
Optional dependencies for mingw-w64-ucrt-x86_64-clang
    mingw-w64-ucrt-x86_64-llvm=23.1.4
(5/5) installing mingw-w64-ucrt-x86_64-clang-tools-extra     [###############################] 100%

可以打开powershell，验证是否安装成功：

clangd --version

安装 VSCode 的 clangd 扩展后，在项目根目录把 .clangd 中的数据库路径改为：

CompileFlags:
  CompilationDatabase: build/windows-debug

先执行一次 Configure，让 build/windows-debug/compile_commands.json 生成出来。

如果扩展找不到 clangd 程序，或者标准库头文件仍然报错: 新建一个.vscode文件夹:

里面新建settings.json：

这个settings.json里填写：

{
  "clangd.path": "C:/msys64/ucrt64/bin/clangd.exe",
  "clangd.arguments": [
    "--query-driver=C:/msys64/ucrt64/bin/g++.exe,C:/msys64/ucrt64/bin/gcc.exe"
  ],
  "C_Cpp.intelliSenseEngine": "disabled"
}

--query-driver 允许 clangd 向这里指定的编译器查询标准库头文件位置。路径要对应自己安装的编译器。详细原理见 clangd 系统头文件说明。

关闭 C/C++ 的 IntelliSense 不会关闭它提供的 GDB 调试功能。

去本地设置(按ctrl shift p)并搜索 clangd: Restart language server。

这个头文件底下突然出现一条横线了，说明clangd发挥他的作用了

9.验证安装结果

进阶，可以不看，新人暂时不用学

日常写代码直接运行 build 目录里的程序。只有准备分发或检查安装布局时，再执行：

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

安装时，模板还会准备工具链中找到的常用 GCC 运行库。保持安装目录的内部结构，整体复制到其他位置后再运行。以后新增第三方库时，还要检查相应依赖的安装要求。

10.使用已经单独安装好的工具

对于你的电脑可能曾经安装过GCC，G++，CMake，Ninja，GDB，Eigen才需要看！新人请跳过

如果电脑上已经有支持 C++20 的 MinGW-w64 GCC、CMake 3.22+、Ninja 和 GDB，也可以继续使用，不必更换安装方式。

把它们各自的 bin/ 加入 PATH，再按前面的版本检查、configure 和 build 步骤执行即可。

Eigen 是头文件库，不需要分别编译 GCC 版和 MSVC 版。对于当前模板的 find_package(Eigen3 REQUIRED)，还需要安装目录提供 Eigen3Config.cmake。

例如 Eigen 安装在 C:/deps/eigen，可以临时设置安装前缀：

$env:CMAKE_PREFIX_PATH = "C:/deps/eigen"
cmake --preset windows-debug

或者直接指定配置文件所在的目录：

cmake --preset windows-debug -DEigen3_DIR="C:/deps/eigen/share/eigen3/cmake"

上面的路径要对应实际文件位置。单纯解压 Eigen 源码可以获得头文件，但不一定已经有生成好的 CMake 配置文件；使用安装包或先执行 Eigen 的 CMake 安装步骤，更适合当前模板的查找方式。参见 Eigen 官方 CMake 说明。

11.常见问题

11.1.找不到 gcc、Ninja 或 GDB

先检查对应的软件包是否装好，再用 where.exe 检查 PATH。修改系统环境变量后，需要重新打开 VSCode，它不会自动获得已经打开之后才修改的 PATH。

11.2.看不到 windows-debug

确认打开的是项目根目录，里面包含 CMakePresets.json。模板按当前系统显示 configure preset；Windows 使用 Windows 原生 CMake 执行时，应看到 Windows 两组预设。

11.3.程序启动失败

先确认运行的是 build/windows-debug/bin/cmake_template.exe，并且开发环境的 GCC 工具目录位于 PATH 中。

测试安装结果时，重新执行 install，再运行安装目录中的 EXE，不要只把 EXE 从目录中单独拿出来。

11.4.切换编译器后构建异常

一个构建目录会缓存之前选择的编译器。更换工具链后，在 PowerShell 中清理对应的构建目录，再重新配置：

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

只有目录存在时才执行删除命令，删除前确认路径是项目的构建目录。这里不要求使用 cmake --fresh，这样也兼容模板最低要求的 CMake 3.22。

11.5.中文显示乱码

先将源文件保存为 UTF-8，并使用支持 UTF-8 的终端。 PowerShell 终端中的编码设置与源文件编码是两件事；需要时可以在当前终端执行 chcp 65001 后重新运行。涉及文件内容时，文件本身的编码也要一致。

12.下一步学什么

环境跑通后，进入 C++基础初识。前期只修改 src/main.cpp，继续使用本节的 Windows 构建和运行方式。

等学到函数分文件编写、第三方库和工程组织时，再回来看 CMake工程模板。