# chengnan 本地二进制依赖说明

本项目原则：**构建项目所用依赖使用二进制包放在项目目录内，不在本机编译安装依赖，不使用系统 GCC 等编译工具链参与本项目构建。**

## 已删除的非目标依赖

已删除之前为 Linux 本地尝试构建而产生的内容：

- `third_party/opencv-src/`：OpenCV 源码
- `third_party/opencv-build/`：OpenCV 编译目录
- `third_party/opencv/`：由源码编译安装出的 Linux OpenCV
- `third_party/qt-sdk/`：Linux Qt 包
- `third_party/qt`：Linux Qt 软链接
- `third_party/opengl-stub/`：Linux 构建验证用 stub
- `tools/uv/`：uv 工具
- `tools/pyenv/`：uv 创建的 Python 环境
- `tools/cmake/`：Linux CMake 二进制

## 当前保留的 Windows 二进制依赖

### Qt 6.7.3 MSVC 2019 64-bit

```text
third_party/qt-windows-msvc-sdk/6.7.3/msvc2019_64/
third_party/qt-windows-msvc -> qt-windows-msvc-sdk/6.7.3/msvc2019_64
```

关键文件：

```text
third_party/qt-windows-msvc/bin/qmake.exe
third_party/qt-windows-msvc/bin/windeployqt.exe
```

### OpenCV 4.10.0 Windows 官方预编译包

```text
third_party/opencv-windows-extract/opencv/build/
third_party/opencv-windows -> opencv-windows-extract/opencv/build
```

关键文件：

```text
third_party/opencv-windows/x64/vc16/lib/OpenCVConfig.cmake
third_party/opencv-windows/x64/vc16/lib/opencv_world4100.lib
third_party/opencv-windows/x64/vc16/bin/opencv_world4100.dll
```

### Ninja / MinGW 工具包

```text
third_party/qt-tools/
```

关键文件：

```text
third_party/qt-tools/Tools/Ninja/ninja.exe
third_party/qt-tools/Tools/mingw1120_64/bin/g++.exe
```

> 注意：项目保留 MinGW 二进制只是备用。当前推荐 MSVC，因为 OpenCV 官方 Windows 二进制是 `vc16`，不能直接给 MinGW 链接。

### Windows CMake 二进制

```text
tools/cmake-windows/cmake-3.31.6-windows-x86_64/
tools/cmake-current-windows -> cmake-windows/cmake-3.31.6-windows-x86_64
```

关键文件：

```text
tools/cmake-current-windows/bin/cmake.exe
```

### Windows Python 二进制与虚拟环境脚本

```text
tools/python-bin/
scripts/setup-python-venv-windows.ps1
```

说明：

- `tools/python-bin/` 使用 Python 官方 Windows embeddable zip 二进制包解压得到
- 不使用 uv
- 如果需要 Python 包，请在 Windows 上运行：

```powershell
powershell -ExecutionPolicy Bypass -File scripts\setup-python-venv-windows.ps1
```

该脚本会优先尝试创建：

```text
tools/python-venv/
```

如果 embeddable Python 不支持 `venv`，则会在 `tools/python-bin/` 内安装 pip/aqtinstall，仍然限制在项目目录内。

## Windows 推荐构建方式

由于当前 OpenCV 是官方 MSVC `vc16` 二进制包，推荐使用 MSVC 构建。

在 Windows 上打开：

```text
x64 Native Tools Command Prompt for VS 2019/2022
```

进入项目目录后运行：

```powershell
powershell -ExecutionPolicy Bypass -File scripts\build-windows.ps1 -Toolchain msvc -Deploy
```

脚本会使用项目内：

- `tools/cmake-current-windows/bin/cmake.exe`
- `third_party/qt-tools/Tools/Ninja/ninja.exe`
- `third_party/qt-windows-msvc/`
- `third_party/opencv-windows/`

## 关于“不使用系统工具链”

当前已经避免使用 Linux 系统 GCC 编译本项目，也删除了通过系统 GCC 编译出来的 OpenCV。

但 MSVC 编译器 `cl.exe` 通常来自 Visual Studio Build Tools。微软没有像 Qt/OpenCV 一样提供适合随项目简单解压携带的独立 MSVC 工具链包。因此：

- 如果允许使用 Windows 已安装的 Visual Studio Build Tools：可直接构建
- 如果要求连 MSVC 编译器也必须项目内携带：建议改用 MinGW，但需要额外准备 MinGW 版 OpenCV 二进制包

## 当前 Linux 服务器限制

当前服务器是 Linux，只能整理 Windows 二进制依赖和脚本，不能直接运行 Windows 的：

- `cmake.exe`
- `ninja.exe`
- `cl.exe`
- `windeployqt.exe`

因此最终 `.exe` 需要在 Windows 上执行构建脚本生成。