# QSTR 生成实现说明

## 概述
QSTR（Interned String）是 MicroPython 的字符串池机制，用于优化内存使用和字符串比较性能。本文档说明了在 TuyaOpen 项目中实现的 QSTR 生成系统。

## 实现架构

### 文件结构
```
src/micropython/
├── CMakeLists.txt          # 主构建文件
├── mpy_prepare.cmake       # QSTR 生成配置
├── cmake/
│   ├── extract_qstr.cmake  # 提取 QSTR 的 CMake 脚本
│   └── process_qstr.cmake  # 处理 QSTR 的 CMake 脚本
├── mpy/py/
│   ├── makeqstrdata.py     # QSTR 数据生成工具
│   ├── makeqstrdefs.py     # QSTR 定义处理工具
│   └── qstrdefs.h          # 基础 QSTR 定义
└── genhdr/                 # 生成的头文件目录
    ├── qstrdefs.collected.h
    └── qstrdefs.generated.h
```

## QSTR 生成流程

### 三步生成过程

#### 步骤 1：提取 QSTR 使用
- **输入**：`LIB_SRCS` 中的所有 C 源文件
- **处理**：`extract_qstr.cmake` 扫描所有 `MP_QSTR_*` 模式
- **输出**：`qstr_build/qstr_extracted.txt`（去重的 QSTR 名称列表）

#### 步骤 2：收集和合并
- **输入**：
  - `mpy/py/qstrdefs.h`（基础定义）
  - `qstr_extracted.txt`（提取的 QSTR）
  - `port/t5ai/qstrdefsport.h`（端口特定，可选）
- **处理**：`process_qstr.cmake` 合并所有 QSTR 定义
- **输出**：`genhdr/qstrdefs.collected.h`（Q() 宏格式）

#### 步骤 3：生成最终头文件
- **输入**：`qstrdefs.collected.h`
- **处理**：`makeqstrdata.py` 生成 C 代码
- **输出**：`genhdr/qstrdefs.generated.h`（包含枚举和数据结构）

## CMake 集成

### 1. 定义源文件列表
```cmake
# CMakeLists.txt
set(LIB_SRCS
    ${PY_CORE_SRCS}
    ${SHARED_SRCS}
    ${PORT_SRCS}
)
```

### 2. 包含 QSTR 生成配置
```cmake
# 在 LIB_SRCS 定义后
include(${CMAKE_CURRENT_SOURCE_DIR}/mpy_prepare.cmake)
```

### 3. 添加依赖关系
```cmake
add_library(${MODULE_NAME})
# ...
if(TARGET mpy_qstr_generated)
    add_dependencies(${MODULE_NAME} mpy_qstr_generated)
endif()
```

## 关键实现细节

### 依赖管理
- 使用 CMake 的 `add_custom_command` 建立文件依赖
- 当任何源文件修改时，自动重新生成 QSTR
- `DEPENDS ${LIB_SRCS}` 确保正确的依赖关系

### 跨平台支持
- 使用 CMake 命令而非 shell 脚本
- Python3 作为唯一外部依赖
- 路径处理使用 CMake 变量

### 增量构建
- CMake 自动检查文件时间戳
- 只在必要时重新生成
- 中间文件存放在 `build/qstr_build/`

## 生成的文件示例

### qstrdefs.collected.h
```c
// Configuration
QCFG(BYTES_IN_LEN, 1)
QCFG(BYTES_IN_HASH, 2)

// Base QSTRs
Q(__build_class__)
Q(__class__)
Q(__init__)
// ...
```

### qstrdefs.generated.h
```c
// This file was automatically generated by makeqstrdata.py
QDEF0(MP_QSTRnull, 0, 0, "")
QDEF0(MP_QSTR_, 5381, 0, "")
QDEF0(MP_QSTR___init__, 42335, 8, "__init__")
// ...
```

## 优势

1. **自动化**：完全集成到 CMake 构建流程
2. **增量构建**：智能依赖管理，提高构建效率
3. **可维护**：清晰的三步流程，易于调试
4. **可扩展**：便于添加新的源文件或端口特定 QSTR

## 注意事项

1. Python3 必须可用（不做检查，假设存在）
2. 生成的文件不应提交到版本控制
3. 端口特定的 QSTR 定义在 `port/t5ai/qstrdefsport.h`（可选）
4. 修改源文件会自动触发 QSTR 重新生成

## 下一步工作

- [ ] 添加其他预编译头文件生成（mpversion.h, moduledefs.h 等）
- [ ] 优化 QSTR 提取性能（并行处理）
- [ ] 添加 QSTR 统计和分析工具