Skip to content

Commit c9eb80a

Browse files
quink-blackquink-black
committed
feat(windows): add comprehensive Windows build support
- Add Windows batch build script (build_windows.bat) - Add vcpkg.json manifest for dependency management - Add CLion configuration guide (CLION_WINDOWS_SETUP.md) - Add Windows quick start guide (WINDOWS_BUILD_QUICKSTART.md) - Update CMakeLists.txt to support vcpkg manifest mode - Fix SDL2main linking logic for both pkg-config and find_package modes - Improve pkg-config SDL2_LIBRARIES setup These changes provide complete Windows development environment setup with MSYS2 + MSVC + vcpkg + CLion support.
1 parent ecdfba6 commit c9eb80a

File tree

7 files changed

+429
-2
lines changed

7 files changed

+429
-2
lines changed

‎.github/workflows/ci.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -72,7 +72,7 @@ jobs:
7272
vcpkgGitCommitId: '23dc124705fcac41cf35c33dd9541f5094a9c19f'
7373

7474
- name: Install dependencies via vcpkg
75-
run: vcpkg install "ffmpeg[core,avformat,avcodec,swresample,swscale,avfilter]:x64-windows" "sdl2:x64-windows"
75+
run: vcpkg install
7676

7777
- name: Configure
7878
run: >

‎.github/workflows/release.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -66,7 +66,7 @@ jobs:
6666
vcpkgGitCommitId: '23dc124705fcac41cf35c33dd9541f5094a9c19f'
6767

6868
- name: Install dependencies via vcpkg
69-
run: vcpkg install "ffmpeg[core,avformat,avcodec,swresample,swscale,avfilter]:x64-windows" "sdl2:x64-windows"
69+
run: vcpkg install
7070

7171
- name: Configure
7272
run: >

‎CLION_WINDOWS_SETUP.md‎

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
# CLion Windows 开发环境配置指南
2+
3+
## 前置要求
4+
5+
### 1. 安装必要软件
6+
- **MSYS2**: https://www.msys2.org/
7+
- **Visual Studio Build Tools** 或 **Visual Studio Community**
8+
- **vcpkg**: Microsoft C++ 包管理器
9+
- **CMake**: 3.16+
10+
11+
### 2. 环境变量设置
12+
设置以下环境变量（在Windows系统环境变量中设置）：
13+
14+
```bash
15+
# MSYS2 路径
16+
MSYS2_ROOT=C:\msys64
17+
18+
# vcpkg 路径
19+
VCPKG_ROOT=C:\vcpkg
20+
21+
# 添加到 PATH
22+
PATH=%MSYS2_ROOT%\usr\bin;%VCPKG_ROOT%;%PATH%
23+
```
24+
25+
## CLion 配置步骤
26+
27+
### 1. 工具链配置
28+
29+
1. 打开 CLion → File → Settings → Build, Execution, Deployment → Toolchains
30+
2. 添加新的工具链，配置如下：
31+
32+
```
33+
Name: Windows MSYS2 + MSVC
34+
Environment: MSYS2
35+
CMake: %MSYS2_ROOT%/usr/bin/cmake.exe
36+
C Compiler: %MSYS2_ROOT%/usr/bin/gcc.exe
37+
C++ Compiler: %MSYS2_ROOT%/usr/bin/g++.exe
38+
Debugger: %MSYS2_ROOT%/usr/bin/gdb.exe
39+
Make: %MSYS2_ROOT%/usr/bin/make.exe
40+
```
41+
42+
### 2. CMake 配置
43+
44+
在 CLion 的 CMake 配置中设置以下参数：
45+
46+
```cmake
47+
-DCMAKE_TOOLCHAIN_FILE=%VCPKG_ROOT%/scripts/buildsystems/vcpkg.cmake
48+
-DCMAKE_BUILD_TYPE=Release
49+
-DAVSYNC_ENABLE_SYNCNET=ON
50+
-DAVSYNC_ENABLE_GUI=ON
51+
-DAVSYNC_ENABLE_TESTS=ON
52+
```
53+
54+
**在 CLion 中设置方法：**
55+
1. 打开 CLion → File → Settings → Build, Execution, Deployment → CMake
56+
2. 在 "CMake options" 字段中添加上述参数
57+
3. 确保 "Build directory" 设置为项目根目录下的 `build` 或类似目录
58+
59+
### 3. vcpkg 依赖安装
60+
61+
在 MSYS2 终端中执行以下命令安装依赖：
62+
63+
```bash
64+
# 进入项目目录
65+
cd /c/path/to/av-auto-sync
66+
67+
# 使用 vcpkg 安装依赖
68+
vcpkg install \
69+
ffmpeg \
70+
opencv[imgproc,objdetect] \
71+
sdl2 \
72+
nlohmann-json \
73+
onnxruntime
74+
```
75+
76+
### 4. 解决常见问题
77+
78+
#### 问题1: SDL2main 链接错误
79+
**症状**: `unresolved external symbol WinMain`
80+
**解决方案**: 确保 CMakeLists.txt 中正确链接 SDL2main
81+
82+
#### 问题2: FFmpeg 库找不到
83+
**症状**: `cannot find -lavcodec` 等链接错误
84+
**解决方案**: 检查 vcpkg 是否正确安装 FFmpeg，确保 `vcpkg.cmake` 工具链文件被正确引用
85+
86+
#### 问题3: OpenCV 头文件找不到
87+
**症状**: `fatal error: opencv2/core.hpp: No such file or directory`
88+
**解决方案**: 确保 OpenCV 组件正确安装，CMake 配置中包含 OpenCV 路径
89+
90+
## 手动构建（备用方案）
91+
92+
如果 CLion 配置有问题，可以使用提供的批处理脚本：
93+
94+
```bash
95+
# 在 MSYS2 终端中执行
96+
./build_windows.bat
97+
```
98+
99+
## 调试配置
100+
101+
### 1. 调试器配置
102+
在 CLion 中配置调试器：
103+
1. Run → Edit Configurations
104+
2. 添加 CMake Application 配置
105+
3. 选择要调试的可执行文件（avsync 或 avsync_gui）
106+
4. 设置程序参数和工作目录
107+
108+
### 2. 调试技巧
109+
- 使用 CLion 的内置调试器设置断点
110+
- 查看变量值和调用栈
111+
- 使用条件断点进行复杂调试
112+
113+
## 性能优化
114+
115+
### 1. 编译优化
116+
- 使用 Release 模式进行最终构建
117+
- 启用并行编译：`-j8`（根据 CPU 核心数调整）
118+
119+
### 2. 内存优化
120+
- 关闭不必要的调试符号
121+
- 使用预编译头文件（如果支持）
122+
123+
## 故障排除
124+
125+
### 常见错误及解决方案
126+
127+
1. **CMake 配置失败**
128+
- 检查 vcpkg 工具链文件路径是否正确
129+
- 确认所有依赖包已安装
130+
131+
2. **链接错误**
132+
- 检查库文件路径
133+
- 确认库文件版本匹配
134+
135+
3. **运行时错误**
136+
- 检查 DLL 文件是否在 PATH 中
137+
- 确认依赖库的运行时版本
138+
139+
### 获取帮助
140+
- 查看项目 README.md
141+
- 检查 GitHub Issues
142+
- 查看构建日志中的详细错误信息
143+
144+
## 注意事项
145+
146+
1. **路径分隔符**: Windows 使用反斜杠 `\`，但在 MSYS2 环境中使用正斜杠 `/`
147+
2. **环境变量**: 确保在 CLion 启动前设置好所有必要的环境变量
148+
3. **权限**: 以管理员身份运行 MSYS2 和 CLion 可能解决某些权限问题
149+
4. **版本兼容**: 确保所有工具和库的版本兼容
150+
151+
通过以上配置，你应该能够在 Windows 上使用 CLion 成功构建和调试 av-auto-sync 项目。

‎CMakeLists.txt‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,11 @@ option(AVSYNC_ENABLE_GUI "Build GUI application (requires SDL2)" ON)
1717

1818
# ---------- Dependencies ----------
1919

20+
# vcpkg manifest mode (preferred)
21+
if(EXISTS "${CMAKE_SOURCE_DIR}/vcpkg.json")
22+
message(STATUS "Using vcpkg manifest mode")
23+
endif()
24+
2025
# FFmpeg (required)
2126
find_package(PkgConfig REQUIRED)
2227
pkg_check_modules(FFMPEG REQUIRED

‎WINDOWS_BUILD_QUICKSTART.md‎

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
# Windows 快速开始指南
2+
3+
## 1. 环境准备
4+
5+
### 安装必要软件
6+
```bash
7+
# 1. 安装 MSYS2
8+
# 下载: https://www.msys2.org/
9+
# 安装到: C:\msys64
10+
11+
# 2. 安装 vcpkg
12+
cd C:\
13+
git clone https://github.com/Microsoft/vcpkg.git
14+
cd vcpkg
15+
.\bootstrap-vcpkg.bat
16+
17+
# 3. 设置环境变量
18+
setx VCPKG_ROOT "C:\vcpkg"
19+
setx MSYS2_ROOT "C:\msys64"
20+
# 将 %MSYS2_ROOT%\usr\bin 和 %VCPKG_ROOT% 添加到 PATH
21+
```
22+
23+
## 2. 构建项目
24+
25+
### 方法一：使用Bash脚本（推荐）
26+
```bash
27+
# 在 MSYS2 终端中执行
28+
./build_windows.sh
29+
```
30+
31+
### 方法二：使用批处理脚本
32+
```bash
33+
# 在 MSYS2 终端中执行
34+
./build_windows.bat
35+
```
36+
37+
### 方法三：手动构建
38+
```bash
39+
# 在 MSYS2 终端中执行
40+
cd /c/path/to/av-auto-sync
41+
42+
# 安装依赖
43+
vcpkg install --triplet x64-windows
44+
45+
# 配置构建
46+
mkdir build_windows && cd build_windows
47+
cmake .. \
48+
-DCMAKE_BUILD_TYPE=Release \
49+
-DCMAKE_TOOLCHAIN_FILE=%VCPKG_ROOT%/scripts/buildsystems/vcpkg.cmake \
50+
-DAVSYNC_ENABLE_SYNCNET=ON \
51+
-DAVSYNC_ENABLE_GUI=ON \
52+
-DAVSYNC_ENABLE_TESTS=ON
53+
54+
# 构建
55+
cmake --build . --config Release --parallel
56+
```
57+
58+
## 3. CLion 配置（可选）
59+
60+
### 工具链设置
61+
1. File → Settings → Build, Execution, Deployment → Toolchains
62+
2. 添加工具链：Windows MSYS2 + MSVC
63+
3. 设置编译器路径为 MSYS2 下的 gcc/g++
64+
65+
### CMake 配置
66+
在 CMake options 中添加：
67+
```
68+
-DCMAKE_TOOLCHAIN_FILE=%VCPKG_ROOT%/scripts/buildsystems/vcpkg.cmake
69+
-DCMAKE_BUILD_TYPE=Release
70+
-DAVSYNC_ENABLE_SYNCNET=ON
71+
-DAVSYNC_ENABLE_GUI=ON
72+
```
73+
74+
## 4. 运行程序
75+
76+
### CLI 版本
77+
```bash
78+
./build_windows/bin/avsync.exe --help
79+
```
80+
81+
### GUI 版本
82+
```bash
83+
./build_windows/bin/avsync_gui.exe
84+
```
85+
86+
## 5. 故障排除
87+
88+
### 常见问题
89+
90+
**Q: 构建失败，提示找不到库文件**
91+
A: 检查 vcpkg 是否正确安装依赖，重新运行 `vcpkg install --triplet x64-windows`
92+
93+
**Q: CLion 找不到头文件**
94+
A: 确保 CMake 配置中包含 vcpkg 工具链文件路径
95+
96+
**Q: 运行时缺少 DLL**
97+
A: 将 vcpkg 的 installed\x64-windows\bin 目录添加到 PATH
98+
99+
### 调试技巧
100+
- 使用 CLion 内置调试器设置断点
101+
- 查看构建日志中的详细错误信息
102+
- 检查 vcpkg 安装状态：`vcpkg list`
103+
104+
## 6. 文件说明
105+
106+
- `build_windows.bat` - Windows 自动构建脚本
107+
- `vcpkg.json` - 项目依赖清单文件
108+
- `CLION_WINDOWS_SETUP.md` - 详细 CLion 配置指南
109+
110+
## 7. 联系方式
111+
112+
如有问题，请查看：
113+
- 项目 README.md
114+
- GitHub Issues
115+
- 构建日志文件
116+
117+
---
118+
**提示**: 首次构建可能需要较长时间，因为 vcpkg 需要下载和编译所有依赖库。

0 commit comments

Comments
 (0)