198 lines
6.4 KiB
Markdown
198 lines
6.4 KiB
Markdown
# 只使用 Visual Studio 2026 运行本项目
|
||
|
||
本文说明如何只依赖 Visual Studio 2026 自带的 C++ 工具链运行本项目，不额外安装 MinGW、GCC 或其他第三方编译器。
|
||
|
||
本文档编写日期为 2026-05-08。Microsoft Learn 的发布历史显示，Visual Studio 2026 在 2026-04-28 的稳定通道版本为 18.5.2。
|
||
|
||
## 1. 结论
|
||
|
||
可以只用 Visual Studio 2026。
|
||
|
||
需要安装 Visual Studio 2026 的 `Desktop development with C++` 工作负载。该工作负载会提供本项目需要的主要工具：
|
||
|
||
- `cl.exe`：Microsoft C/C++ 编译器
|
||
- `link.exe`：Microsoft 链接器
|
||
- `rc.exe`：Windows 资源编译器
|
||
- Windows SDK：提供 Win32 API、GDI、GDI+ 等头文件和库
|
||
|
||
本项目当前没有 `.sln` 或 `.vcxproj` 工程文件，因此推荐在 Visual Studio 2026 中打开文件夹，然后在 `Developer PowerShell for VS 2026` 中执行构建命令。
|
||
|
||
## 2. 安装 Visual Studio 2026
|
||
|
||
1. 打开 Visual Studio Installer。
|
||
2. 安装 Visual Studio 2026 Community、Professional 或 Enterprise 均可。
|
||
3. 在工作负载页面选择 `Desktop development with C++`。
|
||
4. 保留默认勾选的 MSVC 工具集和 Windows SDK。
|
||
5. 完成安装后启动 Visual Studio 2026。
|
||
|
||
不要额外安装 MinGW。本文后续命令只使用 Visual Studio 2026 自带工具。
|
||
|
||
## 3. 打开项目文件夹
|
||
|
||
1. 启动 Visual Studio 2026。
|
||
2. 在开始窗口选择 `Open a local folder`。
|
||
3. 选择项目根目录：
|
||
|
||
```text
|
||
D:\VSC_program\Tereis
|
||
```
|
||
|
||
4. 打开后可以在 Solution Explorer 中看到：
|
||
|
||
```text
|
||
src
|
||
assets
|
||
build-mingw.ps1
|
||
build-vs2026.ps1
|
||
VS2026_RUN_GUIDE.md
|
||
```
|
||
|
||
说明：`build-mingw.ps1` 是旧的 MinGW 构建脚本。只使用 VS2026 时不需要运行它。
|
||
`build-vs2026.ps1` 是本项目提供的 VS2026 专用构建脚本。
|
||
|
||
## 4. 打开 VS2026 开发者终端
|
||
|
||
普通 PowerShell 通常找不到 `cl.exe` 和 `rc.exe`。要使用 VS2026 自带编译器，应打开开发者终端：
|
||
|
||
1. 在 Visual Studio 2026 顶部菜单选择 `Tools -> Command Line -> Developer PowerShell`。
|
||
2. 进入项目根目录：
|
||
|
||
```powershell
|
||
cd D:\VSC_program\Tereis
|
||
```
|
||
|
||
3. 检查工具是否可用：
|
||
|
||
```powershell
|
||
cl
|
||
rc
|
||
```
|
||
|
||
如果能看到 Microsoft C/C++ Compiler 和 Microsoft Windows Resource Compiler 的版本信息，说明 VS2026 C++ 工具链可用。
|
||
|
||
## 5. 使用 VS2026 工具链构建
|
||
|
||
在 `Developer PowerShell for VS 2026` 中执行：
|
||
|
||
```powershell
|
||
.\build-vs2026.ps1
|
||
```
|
||
|
||
构建并运行：
|
||
|
||
```powershell
|
||
.\build-vs2026.ps1 -Run
|
||
```
|
||
|
||
生成结果：
|
||
|
||
```text
|
||
.vscode-build\vs2026\Tetris.exe
|
||
```
|
||
|
||
该脚本会递归编译 `src\source` 下所有 `.cpp` 文件，包括 `render`、`app`、`logic`、`rogue`、`common`、`extensions` 等目录，避免手动建 VS 工程时漏加源文件。
|
||
|
||
如果需要手动理解脚本做了什么，核心命令如下。
|
||
|
||
先创建输出目录：
|
||
|
||
```powershell
|
||
New-Item -ItemType Directory -Force -Path .\.vscode-build\vs2026
|
||
```
|
||
|
||
编译资源文件：
|
||
|
||
```powershell
|
||
rc /nologo /i .\src\include /i .\assets\icons /fo .\.vscode-build\vs2026\Tetris.res .\src\resources\Tetris.rc
|
||
```
|
||
|
||
编译并链接 C++ 源码：
|
||
|
||
```powershell
|
||
$sources = Get-ChildItem .\src\source -Recurse -Filter *.cpp | ForEach-Object { $_.FullName }
|
||
cl /nologo /utf-8 /std:c++17 /EHsc /Zi /Od /DUNICODE /D_UNICODE /D_WINDOWS /I .\src\include $sources .\.vscode-build\vs2026\Tetris.res /Fe:.\.vscode-build\vs2026\Tetris.exe /link /SUBSYSTEM:WINDOWS winmm.lib gdiplus.lib gdi32.lib user32.lib shell32.lib
|
||
```
|
||
|
||
## 6. 运行程序
|
||
|
||
运行时建议从项目根目录启动，因为程序会读取 `assets/` 目录中的图片、音频和视频资源。
|
||
|
||
```powershell
|
||
Start-Process .\.vscode-build\vs2026\Tetris.exe -WorkingDirectory .
|
||
```
|
||
|
||
如果直接双击 exe，可能因为工作目录不对导致背景图、音乐或视频加载失败。
|
||
|
||
## 7. 常见问题
|
||
|
||
### 找不到 `cl.exe`
|
||
|
||
原因：没有在 VS2026 开发者终端中运行命令，或安装 VS2026 时没有选择 `Desktop development with C++`。
|
||
|
||
处理：
|
||
|
||
1. 打开 `Tools -> Command Line -> Developer PowerShell`。
|
||
2. 如果仍然找不到 `cl.exe`，打开 Visual Studio Installer，修改安装，勾选 `Desktop development with C++`。
|
||
|
||
### 找不到 `rc.exe`
|
||
|
||
原因：Windows SDK 没有安装，或没有进入 VS2026 开发者终端。
|
||
|
||
处理：打开 Visual Studio Installer，确认 C++ 桌面开发工作负载中的 Windows SDK 已安装。
|
||
|
||
### 资源文件编译失败，提示找不到图标
|
||
|
||
原因：`Tetris.rc` 中引用了图标文件，资源编译命令必须包含图标目录。
|
||
|
||
处理：确认资源编译命令中包含：
|
||
|
||
```powershell
|
||
/i .\assets\icons
|
||
```
|
||
|
||
### 程序运行后没有图片、音乐或视频
|
||
|
||
原因：程序没有从项目根目录启动，导致 `assets/` 相对路径无法读取。
|
||
|
||
处理：
|
||
|
||
```powershell
|
||
Start-Process .\.vscode-build\vs2026\Tetris.exe -WorkingDirectory .
|
||
```
|
||
|
||
### 程序能运行、有音乐，但窗口黑屏
|
||
|
||
原因通常是手动创建 Visual Studio 工程时没有把所有源文件加入编译，尤其是漏掉了这些目录：
|
||
|
||
```text
|
||
src\source\app
|
||
src\source\common
|
||
src\source\extensions
|
||
src\source\logic
|
||
src\source\render
|
||
src\source\rogue
|
||
```
|
||
|
||
处理：不要运行手动残缺工程生成的 exe，改用 VS2026 开发者终端运行项目脚本：
|
||
|
||
```powershell
|
||
.\build-vs2026.ps1 -Run
|
||
```
|
||
|
||
如果一定要手动建 VS 工程，必须把 `src\source` 下所有 `.cpp` 文件递归加入项目，并把工作目录设置为项目根目录 `D:\VSC_program\Tereis`。
|
||
|
||
### 直接按 F5 不能运行
|
||
|
||
原因：本项目当前没有 Visual Studio `.sln` 或 `.vcxproj` 工程文件，VS2026 不知道应该如何构建和启动。
|
||
|
||
处理：使用本文的 `Developer PowerShell for VS 2026` 构建方式。后续如果需要 F5 调试体验，可以再创建 Visual Studio C++ 工程文件。
|
||
|
||
## 8. 参考资料
|
||
|
||
- Visual Studio 2026 Release Notes: <https://learn.microsoft.com/visualstudio/releases/vs18/release-notes>
|
||
- Visual Studio 2026 Release History: <https://learn.microsoft.com/en-us/visualstudio/releases/2026/release-history>
|
||
- Visual Studio 2026 System Requirements: <https://learn.microsoft.com/en-us/visualstudio/releases/2026/vs-system-requirements>
|
||
- Install Visual Studio: <https://learn.microsoft.com/en-us/visualstudio/install/install-visual-studio>
|
||
- Use the Microsoft C++ toolset from the command line: <https://learn.microsoft.com/en-us/cpp/build/building-on-the-command-line>
|
||
- MSVC compiler command-line syntax: <https://learn.microsoft.com/en-us/cpp/build/reference/compiler-command-line-syntax>
|