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