添加运行说明

2026-04-23 20:21:48 +08:00
parent 2fb4cdd4b7
commit a5046d9ddd
2 changed files with 298 additions and 9 deletions
@@ -0,0 +1,150 @@
+# Dev-C++ 运行说明
+
+## 1. 适用环境
+
+本说明适用于 Windows 下的 Dev-C++ + MinGW 环境。
+
+如果 Dev-C++ 自带的是较旧版本 MinGW，也可以尝试使用，但更建议使用支持 C++17 和 `windres` 的 MinGW。
+
+## 2. 当前工程结构
+
+项目已按工程方式整理：
+
+```text
+src/
+├─ include/      头文件
+├─ source/       源文件
+└─ resources/    Windows 资源脚本
+
+assets/
+├─ icons/        图标资源
+├─ images/       图片资源
+└─ audio/        音频资源
+```
+
+## 3. 建议的工程类型
+
+在 Dev-C++ 中新建工程时，建议选择：
+
+```text
+Windows Application
+```
+
+不要选控制台程序，否则窗口程序的入口和链接方式会不匹配。
+
+## 4. 需要加入工程的文件
+
+### 源文件
+
+把以下文件加入工程：
+
+- `src/source/stdafx.cpp`
+- `src/source/Tetris.cpp`
+- `src/source/TetrisLogic.cpp`
+- `src/source/TetrisRender.cpp`
+
+### 头文件
+
+头文件通常不需要全部加入编译列表，但建议加入工程树便于查看：
+
+- `src/include/stdafx.h`
+- `src/include/Tetris.h`
+- `src/include/targetver.h`
+- `src/include/resource.h`
+
+### 资源文件
+
+如果 Dev-C++ 当前环境支持资源编译，再把下面文件加入工程：
+
+- `src/resources/Tetris.rc`
+
+## 5. 需要配置的选项
+
+### 头文件搜索路径
+
+把下面目录加入 include path：
+
+```text
+src/include
+```
+
+### 链接库
+
+确保工程链接以下 Windows 库：
+
+- `winmm`
+- `gdi32`
+- `user32`
+
+### 编译标准
+
+建议使用：
+
+```text
+C++17
+```
+
+### 预处理宏
+
+建议定义：
+
+- `UNICODE`
+- `_UNICODE`
+- `_WINDOWS`
+
+### 工程类型相关参数
+
+如果需要手动补参数，建议与当前脚本保持一致：
+
+- `-mwindows`
+- `-municode`
+
+## 6. 关于资源文件
+
+这里是 Dev-C++ 环境下最可能出问题的地方。
+
+`src/resources/Tetris.rc` 原始编码是 UTF-16，而有些 MinGW / Dev-C++ 组合下的 `windres` 不能直接编译它。
+
+同时，资源脚本中引用的图标名是：
+
+- `Tetris.ico`
+- `small.ico`
+
+而实际文件位于：
+
+- `assets/icons/Tetris.ico`
+- `assets/icons/small.ico`
+
+## 7. 推荐做法
+
+### 做法一：先不编资源文件
+
+最省事的方式是先不要把 `Tetris.rc` 加入 Dev-C++ 工程，只编译 C++ 源文件。
+
+这样：
+
+- 程序主体通常可以编译运行
+- 但图标、菜单、关于框资源可能缺失
+
+### 做法二：单独处理资源文件后再加入工程
+
+如果你希望在 Dev-C++ 中也带资源运行，建议先做这两步：
+
+1. 将 `Tetris.rc` 另存为 UTF-8 或 ANSI
+2. 把资源中的图标路径改成实际可访问路径
+
+例如改为：
+
+```text
+"assets/icons/Tetris.ico"
+"assets/icons/small.ico"
+```
+
+这样更容易在 Dev-C++ 中直接通过资源编译。
+
+## 8. 运行结果
+
+如果配置正确，编译后应该能得到一个 Windows 图形界面的 `exe`，并正常弹出游戏窗口。
+
+如果只是为了开发和调试，建议优先使用本项目现成的 VS Code 配置，因为当前目录结构、构建脚本和资源处理逻辑已经和 VS Code 对齐。 Dev-C++ 更适合作为兼容运行方案。
+
@@ -1,13 +1,152 @@
 # VS Code 运行说明

-1. 用 VS Code 打开项目根目录。
-2. 安装 VS Code 扩展: `C/C++`，发布者是 `Microsoft`
-3. 按 `Ctrl+Shift+B` 编译
-4. 按 `F5` 调试运行，或在命令面板执行 `Tasks: Run Task` -> `run Tetris MinGW`
+## 1. 适用环境

-说明:
+本项目适用于 Windows + VS Code + MinGW 环境。
+
+建议已安装：
+
+- VS Code
+- C/C++ 扩展（Microsoft）
+- PowerShell
+- MinGW，且可用 `g++.exe`、`gdb.exe`、`windres.exe`
+
+脚本会优先使用系统 `PATH` 中的工具；如果未加入 `PATH`，也兼容 `C:\mingw64\bin\` 下的 MinGW。
+
+## 2. 项目结构
+
+当前工程目录结构如下：
+
+```text
+src/
+├─ include/      头文件
+├─ source/       源文件
+└─ resources/    Windows 资源脚本
+
+assets/
+├─ icons/        图标资源
+├─ images/       图片资源
+└─ audio/        音频资源
+```
+
+其中：
+
+- 头文件检索路径为 `src/include`
+- 编译的源文件位于 `src/source`
+- 资源脚本为 `src/resources/Tetris.rc`
+- 图标资源为 `assets/icons/Tetris.ico` 和 `assets/icons/small.ico`
+
+## 3. 打开方式
+
+用 VS Code 打开项目根目录，也就是包含以下文件的目录：
+
+- `build-mingw.ps1`
+- `.vscode/`
+- `src/`
+- `assets/`
+
+不要只打开 `src/` 子目录，否则任务和调试配置会失效。
+
+## 4. 构建方式
+
+### 方法一：快捷键构建
+
+按 `Ctrl+Shift+B`，默认会执行：
+
+```text
+build Tetris MinGW
+```
+
+它会调用：
+
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File .\build-mingw.ps1
+```
+
+### 方法二：命令面板运行任务
+
+在命令面板中执行：
+
+```text
+Tasks: Run Task
+```
+
+然后选择：
+
+- `build Tetris MinGW`
+- `run Tetris MinGW`
+
+## 5. 调试方式
+
+按 `F5`，选择：
+
+```text
+Debug Tetris MinGW
+```
+
+调试配置会先执行构建任务，然后启动：
+
+```text
+.vscode-build\mingw\Tetris.exe
+```
+
+当前工作目录为项目根目录。
+
+## 6. 构建输出
+
+成功构建后，输出文件位于：
+
+```text
+.vscode-build\mingw\Tetris.exe
+```
+
+同时在资源编译阶段，脚本还会临时生成：
+
+- `.vscode-build\mingw\Tetris.utf8.rc`
+- `.vscode-build\mingw\Tetris.res.o`
+
+这些都属于中间产物，不需要手动维护。
+
+## 7. 资源文件说明
+
+原始 `Tetris.rc` 是 UTF-16 编码，MinGW 的 `windres` 不能直接稳定编译该文件。
+
+当前脚本的处理方式是：
+
+1. 读取 `src/resources/Tetris.rc`
+2. 临时转换为 UTF-8
+3. 将图标路径替换为 `assets/icons/` 下的实际文件
+4. 使用 `windres` 编译资源
+5. 将资源对象与 C++ 源文件一起链接
+
+因此在 VS Code 环境下，图标和菜单资源是会参与构建的。
+
+## 8. 常见问题
+
+### 找不到 `g++.exe`
+
+说明 MinGW 没加入系统 `PATH`，或者未安装在 `C:\mingw64\bin\`。  
+处理方式：
+
+- 把 MinGW 的 `bin` 目录加入 `PATH`
+- 或安装到 `C:\mingw64\bin\`
+
+### 找不到 `gdb.exe`
+
+说明调试器不可用。  
+构建通常还能继续，但 `F5` 调试会失败。
+
+### 找不到 `windres.exe`
+
+程序主体仍可能编译通过，但资源文件无法编译进最终 `exe`。
+
+### 打开的是 `src/` 而不是项目根目录
+
+会导致：
+
+- VS Code 任务不可用
+- 调试配置不可用
+- include 路径不正确
+
+应重新打开项目根目录。

- 默认配置优先使用系统 `PATH` 中的 `g++.exe` / `gdb.exe`，也兼容 `C:\mingw64\bin\g++.exe`。
- 源码目录已按工程结构整理为 `src/include`、`src/source`、`src/resources`，资源目录已整理为 `assets/icons`、`assets/images`、`assets/audio`。
- MinGW 构建输出文件在 `.vscode-build\mingw\Tetris.exe`。
- `Tetris.rc` 位于 `src/resources`，构建脚本会在编译时临时转换编码并编译资源文件。