张宗平
82d13516d7
按 CLAUDE.md 维护最佳实践浓缩 README/HANDOFF 中 agent 上手即需的信息： - 纠正机构名（上程数据→四川大学）、补全损坏的 wiki 根页面链接 - 强调生成器驱动：p01/p03 源码由 tools/gen_*.py 产出，勿手改（会被重生成覆盖） - 给出 Part1/Part3 构建+运行+offscreen 验证的可粘贴命令 - 目录深缩写约定、ASCII 目标名、C17/C++17 基线 - 四条红线（不改 wiki_data、必记 erratum、隔离 Qt 不碰系统 5.15、一文件一目标）
56 lines
3.2 KiB
Markdown
56 lines
3.2 KiB
Markdown
# 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`。
|
||
- 一文件一目标，不跨块合并造符号冲突。
|