Wiki

Windows开发环境搭建与测试

Updated 2023-10-05About 28 min read

Existing English translations were reused. 194 current source blocks remain in Simplified Chinese, without triggering paid translation.

In this chapter, we won't change the code first; we'll do just one very specific thing:

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

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

1.Final effect of this chapter

This chapter will proceed in the following order:

安装 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.Install basic tools

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 终端：

Then:

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.Install VSCode

First, Baidu's official website:https://code.visualstudio.com/

For the path below, it is recommended to use the default; you may also choose another location, but you need to ensure that the path is purely in English and that you have permissions for it (if you are unsure, it is recommended to use the default).

It must be checked like this

Wait for the progress bar to finish scrolling and it will be done.

5.2.配置VScode

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

Then you can configure an environment to be used exclusively for the C++ environment, avoiding conflicts with the default environment.

alt text

Just make some settings, follow my lead.

alt text

Select the CMake configuration you created

alt text

扩展主要安装：

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

If you use clangd for code suggestions, it is recommended to disable or weaken the IntelliSense of the C/C++ extension to avoid duplicate or conflicting suggestions caused by two language servers working at the same time.

alt text

6.Clone CMake template

在准备放工程的目录中打开 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.First run the template as-is

7.1.Run it via the command line

在 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.Frequently Asked Questions

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.What to learn next

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

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