# qml02

**Repository Path**: weekend/qml02

## Basic Information

- **Project Name**: qml02
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-20
- **Last Updated**: 2026-08-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# qml02

基于 Qt 6 + QML 的示例项目集合。顶层 CMake 自动聚合 `src/` 下的所有子项目，每个子项目自包含。

现有子项目：

- `qml_hello` — 纯 QML Hello World
- `qml_triangle_opengl` — QML + OpenGL 三角形（QQuickFramebufferObject）
- `qml_triangle_vulkan` — QML + Vulkan 三角形（QQuickRhiItem + QRhi）
- `widget_triangle_opengl` — QWidget + OpenGL 三角形（QOpenGLWidget）
- `widget_triangle_vulkan` — QWidget + Vulkan 三角形（QVulkanWindow + createWindowContainer）


## 子项目约定

- **target 名 = QML URI = 目录名**：每个子项目的 `CMakeLists.txt` 用
  `get_filename_component(DIR_NAME "${CMAKE_CURRENT_SOURCE_DIR}" NAME)` 取目录名，
  `project(${DIR_NAME} ...)` 后统一使用 `${PROJECT_NAME}` 定义 target 与 QML 模块。
- **新增子项目**：在 `src/` 下新建目录，复制任一子项目的 `CMakeLists.txt`（及对应源码），
  无需修改任何 target 名。`main.cpp` 中的 `loadFromModule("目录名", "Main")` 需与目录名一致。
- **target 名必须全局唯一**：即 src/ 下目录名不能重复。

## 环境要求

- Qt 6.8.3（MSVC 2022 x64 版，含 Debug 库）：`C:\Qt\6.8.3\msvc2022_64`
- Visual Studio 2022（C++ 桌面工作负载）
- CMake ≥ 3.21
- Vulkan SDK（仅 `*_triangle_vulkan` 需要）：`C:\VulkanSDK\1.4.350.0`

## 在 VSCode 中构建与运行

> 方案不修改系统环境变量，通过 VSCode 工作区配置把 Qt 的 `bin` 目录注入进程 PATH。

### 1. 安装扩展

- `ms-vscode.cpptools`（C/C++，F5 调试必需）
- `ms-vscode.cmake-tools`（CMake Tools）
- `tonka3000.qtvsctools`（Qt VS Code Tools，可选）

### 2. 配置（已提交在 .vscode/ 下）

`launch.json` 与 `settings.json` 已配好三处 Qt PATH 注入，以及 Vulkan SDK 注入：

| 配置项 | 作用 |
|---|---|
| `launch.json` 的 `environment` | F5 调试运行时生效（Qt bin） |
| `settings.json` 的 `cmake.environment` | CMake 配置 / 构建子进程生效（Qt bin + `VULKAN_SDK`） |
| `settings.json` 的 `terminal.integrated.env.windows` | VSCode 集成终端里手动跑 exe 生效（Qt bin） |

### 3. 首次打开后的操作顺序

1. `Ctrl+Shift+P` → `Developer: Reload Window`（让配置生效）
2. `Ctrl+Shift+P` → `CMake: Select a Kit` → 选 **Visual Studio 2022 ... (x64)**
3. 底部状态栏 **Build**（或 `CMake: Build`），确认编译通过
4. 状态栏 target 选择器选中 `qml_hello` 或 `qml_triangle_opengl`
5. 运行（三种方式任选）：

   | 方式 | 操作 |
   |---|---|
   | 调试运行 | 按 `F5`，选配置 `qml_hello (CMake)` / `qml_triangle_opengl (CMake)` |
   | 普通运行 | 状态栏 **▶** 按钮（`CMake: Run`） |
   | 终端运行 | `Ctrl+`` 打开终端，执行 `.\build\src\qml_hello\Debug\qml_hello.exe` |

### 4. 常见问题

- **弹窗"找不到 Qt6Qmld.dll / Qt6Core.dll"**：运行环境的 PATH 里没有 Qt bin。
  修改配置后必须 `Reload Window`；旧终端不会自动获得新 PATH。
- **F5 报"未找到匹配的调试配置"**：确认 cpptools 已装、窗口已重载、F5 选的是带 `(CMake)` 后缀的配置。
- **exe 路径不对**：`launch.json` 的 `program` 用的是 `${command:cmake.launchTargetPath}`，
  自动跟随 CMake Tools 当前选中的 target，请先确认状态栏 target 已选对。
- **qml_triangle_vulkan / widget_triangle_vulkan 窗口黑屏/空白或启动失败**：Vulkan 程序需要
  显卡/驱动支持 Vulkan。widget 版还依赖 CMake 能定位 Vulkan SDK（`cmake.environment` 的
  `VULKAN_SDK`，见上）。

### 5. 换设备 / 换 Qt 路径

- `.vscode/` 已入库：clone 仓库后按上文操作即可，**无需重新创建配置**。
- 唯一需要按设备调整的是工具链路径，全局替换 `.vscode/settings.json` 与
  `.vscode/launch.json` 中的：
  - `C:/Qt/6.8.3/msvc2022_64`（Qt，出现于 `CMAKE_PREFIX_PATH` 与三处 PATH 注入，共 4 处）
  - `C:/VulkanSDK/1.4.350.0`（Vulkan SDK，出现于 `cmake.environment` 的 `VULKAN_SDK`）
- 未安装 Vulkan SDK 的设备可跳过 `widget_triangle_vulkan`（构建会报 find_package(Vulkan) 失败）。

## 命令行构建（可选）

```bat
:: 配置（首次）
cmake -S . -B build -G Ninja -DCMAKE_PREFIX_PATH=C:/Qt/6.8.3/msvc2022_64 -DCMAKE_BUILD_TYPE=Debug
:: 构建
cmake --build build
:: 运行（需先运行 vcvars64.bat 或把 Qt bin 加入 PATH）
build\src\qml_hello\Debug\qml_hello.exe
```