添加完善说明
This commit is contained in:
+74
-78
@@ -1,71 +1,45 @@
|
||||
# VS Code 运行说明
|
||||
|
||||
## 1. 适用环境
|
||||
本说明适用于 `Windows + VS Code + MinGW-w64` 环境。
|
||||
|
||||
本项目适用于 Windows + VS Code + MinGW 环境。
|
||||
## 1. 推荐环境
|
||||
|
||||
建议已安装：
|
||||
|
||||
- VS Code
|
||||
- C/C++ 扩展（Microsoft）
|
||||
- Microsoft C/C++ 扩展
|
||||
- PowerShell
|
||||
- MinGW，且可用 `g++.exe`、`gdb.exe`、`windres.exe`
|
||||
- MinGW-w64
|
||||
- `g++.exe`
|
||||
- `gdb.exe`
|
||||
- `windres.exe`
|
||||
|
||||
脚本会优先使用系统 `PATH` 中的工具；如果未加入 `PATH`，也兼容 `C:\mingw64\bin\` 下的 MinGW。
|
||||
## 2. 正确打开方式
|
||||
|
||||
## 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 打开项目根目录，也就是包含以下文件的目录：
|
||||
请直接用 VS Code 打开项目根目录，也就是包含以下内容的目录：
|
||||
|
||||
- `build-mingw.ps1`
|
||||
- `.vscode/`
|
||||
- `src/`
|
||||
- `assets/`
|
||||
|
||||
不要只打开 `src/` 子目录，否则任务和调试配置会失效。
|
||||
不要只打开 `src/` 子目录，否则：
|
||||
|
||||
## 4. 构建方式
|
||||
- 构建任务不可用
|
||||
- 调试配置不可用
|
||||
- 路径和资源引用可能失效
|
||||
|
||||
### 方法一：快捷键构建
|
||||
## 3. 构建方法
|
||||
|
||||
按 `Ctrl+Shift+B`，默认会执行：
|
||||
### 方法一：快捷键
|
||||
|
||||
```text
|
||||
build Tetris MinGW
|
||||
```
|
||||
按 `Ctrl + Shift + B`
|
||||
|
||||
它会调用：
|
||||
默认会执行项目中的 MinGW 构建任务。
|
||||
|
||||
```powershell
|
||||
powershell -NoProfile -ExecutionPolicy Bypass -File .\build-mingw.ps1
|
||||
```
|
||||
### 方法二：运行任务
|
||||
|
||||
### 方法二：命令面板运行任务
|
||||
|
||||
在命令面板中执行：
|
||||
打开命令面板，执行：
|
||||
|
||||
```text
|
||||
Tasks: Run Task
|
||||
@@ -76,7 +50,7 @@ Tasks: Run Task
|
||||
- `build Tetris MinGW`
|
||||
- `run Tetris MinGW`
|
||||
|
||||
## 5. 调试方式
|
||||
## 4. 调试方法
|
||||
|
||||
按 `F5`，选择：
|
||||
|
||||
@@ -84,69 +58,91 @@ Tasks: Run Task
|
||||
Debug Tetris MinGW
|
||||
```
|
||||
|
||||
调试配置会先执行构建任务，然后启动：
|
||||
该配置会先构建，再启动：
|
||||
|
||||
```text
|
||||
.vscode-build\mingw\Tetris.exe
|
||||
```
|
||||
|
||||
当前工作目录为项目根目录。
|
||||
## 5. 输出位置
|
||||
|
||||
## 6. 构建输出
|
||||
|
||||
成功构建后，输出文件位于：
|
||||
构建成功后，程序位于：
|
||||
|
||||
```text
|
||||
.vscode-build\mingw\Tetris.exe
|
||||
```
|
||||
|
||||
同时在资源编译阶段，脚本还会临时生成：
|
||||
中间产物位于同一目录下，例如：
|
||||
|
||||
- `.vscode-build\mingw\Tetris.utf8.rc`
|
||||
- `.vscode-build\mingw\Tetris.res.o`
|
||||
- `Tetris.utf8.rc`
|
||||
- `Tetris.res.o`
|
||||
|
||||
这些都属于中间产物，不需要手动维护。
|
||||
## 6. 推荐命令
|
||||
|
||||
## 7. 资源文件说明
|
||||
在 VS Code 终端中，也可以直接执行：
|
||||
|
||||
原始 `Tetris.rc` 是 UTF-16 编码，MinGW 的 `windres` 不能直接稳定编译该文件。
|
||||
```powershell
|
||||
powershell -NoProfile -ExecutionPolicy Bypass -File .\build-mingw.ps1
|
||||
```
|
||||
|
||||
当前脚本的处理方式是：
|
||||
如果构建后要立即运行：
|
||||
|
||||
1. 读取 `src/resources/Tetris.rc`
|
||||
2. 临时转换为 UTF-8
|
||||
3. 将图标路径替换为 `assets/icons/` 下的实际文件
|
||||
4. 使用 `windres` 编译资源
|
||||
5. 将资源对象与 C++ 源文件一起链接
|
||||
```powershell
|
||||
powershell -NoProfile -ExecutionPolicy Bypass -File .\build-mingw.ps1 -Run
|
||||
```
|
||||
|
||||
因此在 VS Code 环境下，图标和菜单资源是会参与构建的。
|
||||
## 7. 常见问题
|
||||
|
||||
## 8. 常见问题
|
||||
### 1）提示找不到 `g++.exe`
|
||||
|
||||
### 找不到 `g++.exe`
|
||||
说明 MinGW 没有正确安装，或者没有加入系统 `PATH`。
|
||||
|
||||
说明 MinGW 没加入系统 `PATH`，或者未安装在 `C:\mingw64\bin\`。
|
||||
处理方式：
|
||||
|
||||
- 把 MinGW 的 `bin` 目录加入 `PATH`
|
||||
- 或安装到 `C:\mingw64\bin\`
|
||||
|
||||
### 找不到 `gdb.exe`
|
||||
### 2）提示找不到 `windres.exe`
|
||||
|
||||
说明调试器不可用。
|
||||
构建通常还能继续，但 `F5` 调试会失败。
|
||||
说明资源文件无法编译进程序。
|
||||
|
||||
### 找不到 `windres.exe`
|
||||
结果通常是：
|
||||
|
||||
程序主体仍可能编译通过，但资源文件无法编译进最终 `exe`。
|
||||
- 主体代码可能还能编译
|
||||
- 但图标、菜单等资源会出问题
|
||||
|
||||
### 打开的是 `src/` 而不是项目根目录
|
||||
### 3）提示 `Tetris.exe: Permission denied`
|
||||
|
||||
会导致：
|
||||
通常是因为游戏程序还在运行，导致链接器无法覆盖旧的 `exe`。
|
||||
|
||||
- VS Code 任务不可用
|
||||
- 调试配置不可用
|
||||
- include 路径不正确
|
||||
处理方式：
|
||||
|
||||
应重新打开项目根目录。
|
||||
- 先关闭正在运行的游戏窗口
|
||||
- 再重新执行构建
|
||||
|
||||
### 4）按 `F5` 无法调试
|
||||
|
||||
一般是因为：
|
||||
|
||||
- 没安装 `gdb.exe`
|
||||
- 打开的不是项目根目录
|
||||
- VS Code 没有加载 `.vscode` 配置
|
||||
|
||||
## 8. 资源说明
|
||||
|
||||
项目运行依赖以下资源目录：
|
||||
|
||||
- `assets/icons/`
|
||||
- `assets/images/`
|
||||
- `assets/audio/`
|
||||
- `assets/video/`
|
||||
|
||||
如果只是拷贝 `exe` 而不带资源目录，部分功能会缺失，例如：
|
||||
|
||||
- 背景图
|
||||
- 背景音乐
|
||||
- 复活视频
|
||||
|
||||
## 9. 适用场景
|
||||
|
||||
如果你主要在本机开发、调试和演示，VS Code 是本项目最推荐的运行方式。当前任务配置、构建脚本和资源处理流程都已经围绕 VS Code 配好。
|
||||
|
||||
Reference in New Issue
Block a user