TransPyC/includes/vqt6/README.md

vqt6 — Viper 的 Qt6 绑定包

vqt6 是 Viper 语言的 Qt6 GUI 框架绑定，是 Viper 包管理器分发的"包"（类似于 Python 的 PyQt6、Node.js 的 node-gtk）。

注意：vqt6 不是 包管理器，而是一个被包管理器管理的包（库）。 包管理器负责下载、预编译、安装；vqt6 只负责把 Qt6 C++ API 暴露给 Viper 代码。

架构

+--------------------+        +-----------------------+        +------------+
|  Viper 用户代码     |  FFI   |  vqt6 桥接层 (libvqt6) |  C++    |  Qt6 C++   |
|  (app.py)          | <----> |  - t.State 声明       | <-----> |  QtCore    |
|                    |        |  - C 桥接函数          |        |  QtGui     |
|  vqt6.QApplication |        |    (extern "C")       |        |  QtWidgets |
|  vqt6.QLabel       |        |  - 静态库 / 动态库     |        |  QtNetwork |
+--------------------+        +-----------------------+        +------------+

FFI 路径：

1. Viper 编译器把 t.State 声明的 def xxx() -> t.State: pass 解析为外部函数符号
2. 链接时通过 libvqt6_bridge.a（静态）或 vqt6_bridge.dll（动态）解析符号
3. 运行时 C 桥接层调用 Qt6 C++ API 完成实际工作

链接模式

模式	产物	优点	缺点
静态（默认）	libvqt6_bridge.a	部署简单（一个 exe），无需分发 dll	exe 体积较大
动态	vqt6_bridge.dll	共享内存，多个程序共用	需随 exe 分发 dll

vqt6 同一套 C 桥接源代码，可同时编译为两种产物。Viper 项目通过 project.vpj 切换。

目录结构

includes/vqt6/
├── README.md           # 本文件
├── __init__.py         # 公共 Pythonic API（用户使用）
├── _types.py           # 公共类型（不透明指针 typedef）
├── _qtcore.py          # QtCore 的 t.State FFI 声明
├── _qtwidgets.py       # QtWidgets 的 t.State FFI 声明
├── _qtgui.py           # QtGui 的 t.State FFI 声明
├── _qtnetwork.py       # QtNetwork 的 t.State FFI 声明
├── _bridge.h           # C 桥接层头文件
├── _bridge.cpp         # C 桥接层实现（extern "C" 包装 Qt6 C++ API）
└── CMakeLists.txt      # 构建脚本（生成 libvqt6_bridge.a）

使用示例

# App/main.py
import t
import c
import vqt6

# 1. 创建 QApplication
app: vqt6.QApplication | t.CPtr = vqt6.QApplication([])

# 2. 创建窗口
window: vqt6.QWidget | t.CPtr = vqt6.QWidget()
window.setWindowTitle("vqt6 Hello")
window.resize(400, 300)

# 3. 创建标签
label: vqt6.QLabel | t.CPtr = vqt6.QLabel("你好，Viper！", window)
label.move(50, 50)

# 4. 显示并进入事件循环
window.show()
app.exec()

设计原则

1. 不透明指针：Viper 端不直接操作 Qt6 C++ 类（QWidget*、QString* 等），所有操作通过 C 桥接函数 vqt6_xxx() 转发。
2. t.State 声明：所有 FFI 函数返回 t.State，C 桥接层函数实现负责实际操作。
3. 句柄化对象模型：Viper 端的对象是 t.CPtr（不透明指针），C 端管理生命周期（构造函数/析构函数）。
4. 跨平台：同一套 C 桥接代码可在 Windows / Linux / macOS 编译（差异在 Qt6 安装路径）。

当前状态

• 架构设计
• FFI 覆盖：QtCore / QtWidgets / QtGui / QtNetwork
• FFI 粒度：仅暴露 C 桥接函数
• FFI 声明文件编写中
• C 桥接层实现
• CMakeLists.txt 构建脚本
• Hello World 示例验证