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工程模板。