# QT C++ 方向实训

## Brief
四川大学 C++/LinuxC 课程「02. Qt 方向」课程代码核验及教案准备工作区。

把川大 wiki（需登录）的 Qt 方向课程代码整理成 CMake 管理的可编译项目：每个示例 = 一个独立
`add_executable` 目标。Part1（`p01/`）为 C/C++ 强化控制台程序（144 目标），Part3（`p03/`）
为 Qt 桌面应用（29 目标，需隔离 Qt 5.14.2）。

- 课程目录根页面：https://wiki.suncaper.net/pages/viewpage.action?pageId=58954499
  （登录凭据见 `.env` 的 `USERNAME`/`PASSWORD`；`.env` 已 gitignore，勿提交）
- 完整说明见 `README.md`；跨会话续接状态见 `HANDOFF.md`。

## 行为风格
1. 使用 karpathy guideline 指引工作（`/karpathy-guidelines`：外科手术式改动、不过度设计、
   显式暴露假设、定义可验证的成功标准）。
2. 使用电脑操作能力对所有生成/修改的程序进行端到端交互验证（构建 + 实跑，不只是看编译通过）。

## 项目工作流（生成器驱动 —— 最关键）
`p01/`、`p03/` 下的源码全部由 `tools/gen_part1.py` / `tools/gen_part3.py` 从
`tools/wiki_data/` 抓取数据**生成**。**不要手改生成产物**——下次重生成会覆盖。
要修正示例代码：
1. 改生成器里的 `common_fix` / `exact_fix`；
2. 每处对 wiki 原始代码的修正都要调 `record_erratum()`，自动落进 `docs/ERRATA*.md`（透明可审计）；
3. 重新生成（幂等）：`rm -rf p01 p03 build && python3 tools/gen_part1.py && python3 tools/gen_part3.py`。

共享引擎在 `tools/gen_sources.py`；(pageId, section)→英文文件名映射在 `tools/file_name_map.py`。

## 构建与运行
```bash
# Part1（host gcc/g++，无需 Qt）
cmake -S . -B build -G Ninja -DBUILD_QT_PART=OFF -DCMAKE_BUILD_TYPE=Debug
cmake --build build                         # 144 目标全绿
tools/run.sh <target>                       # 例：tools/run.sh p1c04_03_01

# Part3（需先装隔离 Qt 5.14.2 到 .qt514/：tools/install_qt_host.sh）
cmake -S . -B build -G Ninja -DBUILD_QT_PART=ON \
      -DCMAKE_PREFIX_PATH=$PWD/.qt514/5.14.2/gcc_64 -DCMAKE_BUILD_TYPE=Debug
cmake --build build                         # 144 + 29 = 173 目标全绿
tools/run_qt.sh <target>                    # Qt 走 LD_LIBRARY_PATH 隔离
QT_QPA_PLATFORM=offscreen tools/run_qt.sh <target>   # 无 X 离屏验证（目标会 200ms 自动退出）
```

## 约定
- 目录深缩写：`pNN/chNN/sNN/`（如 `p01/ch04/s03/`）；pageId→章节完整映射见 `docs/SOURCE_PAGES.md`。
- 源文件名英文蛇形；CMake 目标名必须 ASCII（CMake 禁非 ASCII 目标名）。
- 标准基线 C17 / C++17，严格、不允许编译器扩展（顶层 `CMakeLists.txt`）。
- 版本相关概念用 `tools/std_probe.py` + `tools/demo_versions/` 跨版本演示，结论汇总于 `docs/VERSION_NOTES.md`。

## 红线
- **不修改** `tools/wiki_data/` 的原始抓取数据（生成器只读输入，保持原貌）。
- 每处 wiki 代码修正必须 `record_erratum()` 进 `docs/ERRATA*.md`。
- 隔离 Qt：构建/运行一律走 `.qt514/`，**不碰系统 Qt 5.15**；顶层 `CMakeLists.txt` 有版本断言，
  误连系统 5.15 会 `FATAL_ERROR`。
- 一文件一目标，不跨块合并造符号冲突。
