构建即自由：一份为创造者设计的 Windows C++ 自动化构建指南

写给那些既追求系统确定性，又渴望流畅创造的开发者。

技术细节一丝不苟，只为让你少一次报错，多一次心流。

---

引言：为什么 cmake .. 值得被认真对待？

表面上，它只是一个命令。

实际上，它是你从想法到可执行程序的关键跃迁点。

但太多人卡在这一步：

• 'cmake' 不是内部或外部命令...
• 脚本中文乱码如天书
• 架构选错，程序编译成功却无法运行

这些问题看似琐碎，却足以打断创造的节奏。

本文的目标很朴素：用最可靠的配置，打通从代码到运行的完整通路 。

所有建议均经过验证，可直接复制使用。

---

一、架构选择：x86、x64、ARM64 ------ 别让名字迷惑你

✅ 核心事实

• x86_64 = x64 ，两者完全等价，都是 64 位架构
• 你下载的 cmake-3.31.11-windows-x86_64.msi 是 64 位安装包，适用于所有现代 Windows 电脑
• x86（32 位）已基本淘汰，除非维护老旧系统，否则无需考虑
• ARM64 仅用于 Surface Pro X 等 ARM 设备，普通 PC 请忽略

🛠 如何确认你的系统？

按 Win + R → 输入 msinfo32 → 查看 "系统类型"：

• x64-based PC → 用 x64
• ARM-based PC → 用 ARM64

对绝大多数人而言，答案只有一个：-A x64

---

二、CMake GUI 与命令行：你其实都拥有

很多人以为："我只装了 CMake GUI，所以不能用命令行"。

这是误解。

🔑 关键真相：

• 从 cmake.org 下载的 Windows Installer (.msi)
  同时包含 cmake.exe（命令行）和 CMake-GUI.exe（图形界面）
• 你不需要二选一------你天然拥有两者

❌ 为什么 CMD 找不到 cmake？

因为安装时未勾选 "Add to PATH"。

✅ 正确做法：

1. 重新运行安装程序（或首次安装）

2. 务必勾选 ： ✅ "Add CMake to the system PATH for all users"

3. 关闭并重新打开 CMD（环境变量需刷新）

4. 验证：

   cmake --version

   应输出：

   cmake version 3.31.11

这一步只需做一次，却能省下未来无数个"命令未找到"的深夜。

---

三、.bat 脚本乱码：一个被忽视的编码陷阱

🐞 问题现象

[+] 褰撳墠椤圭洰鐩綍: C:\...

🔍 根本原因

• Windows CMD 默认使用 GBK 编码（代码页 936）
• 若 .bat 文件保存为 UTF-8，CMD 会错误解析字节 → 乱码
• 乱码还可能导致路径识别失败（尤其含中文时）

✅ 解决方案（任选其一）

方案 A：保存为 ANSI 编码（推荐）

• 记事本 ：另存为 → 编码选 ANSI
• VS Code ：右下角点击 "UTF-8" → "Save with Encoding" → GBK

方案 B：使用全英文脚本（零风险）

@echo off
setlocal
set "ROOT=%~dp0"
cd /d "%ROOT%"

echo [+] Project root: %ROOT%
if not exist "build" mkdir build
cd build

cmake .. -G "Visual Studio 17 2022" -A x64
if errorlevel 1 (
    echo [-] CMake failed!
    pause
    exit /b 1
)

cmake --build . --config Debug
bin\Debug\test_base16.exe
pause

全英文不仅是兼容性保障，更是对协作世界的温柔------让任何人在任何系统上都能读懂你的意图。

---

四、终极构建脚本：稳定、清晰、可复用

@echo off
setlocal

:: 获取项目根目录（安全处理含空格/中文路径）
set "ROOT_DIR=%~dp0"
cd /d "%ROOT_DIR%"

echo [+] Project root: %ROOT_DIR%
echo [+] Creating build directory...

if not exist "build" mkdir build
cd build

:: 配置 CMake（x64，主流选择）
cmake .. -G "Visual Studio 17 2022" -A x64
if errorlevel 1 (
    echo [-] CMake configure failed! Ensure CMake is in PATH.
    echo     Tip: Reinstall and check 'Add to PATH'.
    pause
    exit /b 1
)

:: 编译 Debug 版本
cmake --build . --config Debug

:: 运行测试（需顶层 CMakeLists.txt 设置统一输出）
if exist "bin\Debug\test_base16.exe" (
    echo [+] Running test_base16...
    bin\Debug\test_base16.exe
) else (
    echo [-] Executable not found. Expected: bin\Debug\test_base16.exe
    echo     Did you set CMAKE_RUNTIME_OUTPUT_DIRECTORY?
)

echo [+] Build journey complete.
pause

📌 配套顶层 CMakeLists.txt

cmake_minimum_required(VERSION 3.15)
project(MyProject)

# 统一输出目录：所有 .exe 放入 build/bin/
set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/bin)

add_subdirectory(base16)
add_subdirectory(flash_tool)

这样，test_base16.exe 和 flash_tool.exe 都会出现在 build/bin/Debug/，路径清晰，脚本易写。

---

结语：让工具隐形，让创造显现

我们花时间配置构建系统，不是为了成为工具的专家，

而是为了让工具彻底消失在背景中 ------

当你写下一行代码，按下回车，

程序就该如你所愿地运行。

这份指南，就是为此而写。

愿你的下一次 cmake --build，

安静、顺利、毫无阻碍。

---