TermiNexus
35de6321f6
DeclarationGenerator：tuple[...] 分支逐字保留（仅 CReturnTypes 机械改名 MultiRetTypes），装饰器分支改为 SyntaxError，报文含函数名与“请改用 -> tuple[ty1, ty2, ...]”提示 HandlesAssign（a, b = f() 解包路径）：删除装饰器收集分支并改为报错；tuple[...] 恢复与逐个解包逻辑逐字不变 HandlesFunctions：新增 _CRETURN_REMOVED_HINT 与 _RejectCReturnDecorator，在函数定义入口（_GetFunctionSignatureLlvm / _EmitFunctionLlvm）fail-fast——即使只有装饰器、没有 -> 注解，也不会让返回类型静默退化成 i32 HandlesImports：外部函数声明处同样报错，并删除下游已失效的 CReturnTypes 参数拼接死代码 HandlesReturn / HandlesFor / BaseTranslator：CurrentCReturnTypes 等机械改名（读写端一致，无行为变化） includes/c.py：保留 CReturn 名字作墓碑（删掉会让 @c.CReturn 变成未知属性、可能被静默忽略），docstring 写明已移除并指路 -> tuple[...]；README 措辞同步
77 lines
4.5 KiB
Markdown
77 lines
4.5 KiB
Markdown
# TransPyC
|
||
|
||
**TransPyC** 是一种基于 Python 语法的系统级编程语言编译器，将 Python 子集（通过 `t`/`c` 模块类型注解赋予 LLVM 语义）编译为原生机器码。它不是 Python 的子集，也不是 C 的语法糖——它拥有独立的类型系统、两阶段编译模型和 SHA1 命名空间机制，适用于操作系统内核、嵌入式系统、驱动程序等底层开发场景。
|
||
|
||
## 能力证明
|
||
|
||
TransPyC 已用自身实现以下组件，证明其作为系统级语言的成熟度：
|
||
|
||
- **ViperOS** —— 真实操作系统内核（[ViperOS/](ViperOS/)），含 gdt/idt/isr/mm/sched，可在 QEMU 启动
|
||
- **自研 Python 解析器** —— [includes/ast/](includes/ast/)（4,176 LOC），用 TransPyC 自己写的词法+语法+AST，覆盖 CPython 几乎全部语法
|
||
- **自研 LLVM IR 生成库** —— [includes/llvmlite/](includes/llvmlite/)（~1,500 LOC），用 TransPyC 自己写的 IR 文本生成器，18/18 测试通过
|
||
- **zlib 移植** —— [Test/ZlibTest/](Test/ZlibTest/)，完整 deflate/inflate/huffman/checksum（~1,900 LOC）
|
||
- **Win32 FFI 绑定** —— [includes/w32/](includes/w32/)，file/memory/process/sync/console 全覆盖
|
||
- **泛型容器** —— [includes/linkedlist.vp](includes/linkedlist.vp)，`@t.NoVTable` + PEP 695 递归泛型继承 `class GNode(GSListNode[GNode])`
|
||
|
||
## 核心设计理念
|
||
|
||
- **Python 语法，LLVM 语义**：源文件是合法的 Python 语法，但通过 `t` 模块类型注解赋予 LLVM 级别的语义
|
||
- **类型注解即编译指令**：类型注解决定 LLVM IR 的生成，不是可选的提示
|
||
- **两阶段编译**：先提取声明接口（`.vpi` + `.stub.ll`），再翻译源文件为含代码的 `.ll`
|
||
- **SHA1 命名空间**：每个源文件按内容 SHA1 哈希命名，自动消除跨模块符号冲突
|
||
- **零运行时开销**：编译为原生代码，无 GC、无解释器、无虚拟机
|
||
|
||
## 自举进展
|
||
|
||
TransPyC 正在追求**完全自举**——用 TransPyC 重写 TransPyC 编译器自身。当前状态：
|
||
|
||
- ✅ **前端**：`includes/ast/` 已替代 Python `ast` 模块依赖
|
||
- ✅ **后端**：`includes/llvmlite/` 已替代 Python `llvmlite` 依赖
|
||
- ⏳ **中间层**：`lib/core`（~20K LOC）待用 TransPyC 重写
|
||
|
||
详见 [wiki/13-bootstrapping.md](wiki/13-bootstrapping.md)。
|
||
|
||
## 模块总览
|
||
|
||
Viper 语言通过两个核心模块提供类型和操作支持：
|
||
|
||
| 模块 | 用途 | 导入方式 |
|
||
|------|------|----------|
|
||
| `t` | 类型定义系统 | `import t` |
|
||
| `c` | C 语言操作指令 | `import c` |
|
||
|
||
## 快速上手
|
||
|
||
1. **环境**：Python 3.12+、LLVM（llc/clang）、Windows（当前主平台）
|
||
2. **构建项目**：在项目目录运行 `python ../Projectrans.py build`（详见 [wiki/12-project.md](wiki/12-project.md)）
|
||
3. **示例**：参考 [Test/](Test/) 下 30+ 测试项目（AstTest/ZlibTest/NoVTableTest/LLvmLiteTest 等）
|
||
4. **写第一个程序**：
|
||
|
||
```python
|
||
import t, c
|
||
from stdint import *
|
||
import stdio
|
||
|
||
def main() -> CInt | CExport:
|
||
stdio.printf("Hello, Viper!\n")
|
||
return 0
|
||
```
|
||
|
||
## 文档索引
|
||
|
||
| 文件 | 内容 |
|
||
|------|------|
|
||
| [01-overview.md](wiki/01-overview.md) | 语言概述、两阶段编译流程、SHA1 命名空间、`t.CDefine`/`t.CExport`/`t.CInline` 深度解析 |
|
||
| [02-type-system.md](wiki/02-type-system.md) | 类型系统（基本类型、指针、数组、结构体、联合体、枚举、typedef、`__attribute__`） |
|
||
| [03-variables.md](wiki/03-variables.md) | 变量声明与赋值（含 `t.CDefine` 常量） |
|
||
| [04-functions.md](wiki/04-functions.md) | 函数定义与调用（含 `t.CExport`、`t.CInline`、`t.CDefine` 函数、`-> tuple[...]` 多返回值） |
|
||
| [05-classes.md](wiki/05-classes.md) | 类与数据布局（结构体、联合体、枚举、typedef、位域） |
|
||
| [06-oop.md](wiki/06-oop.md) | 面向对象与运算符重载（`@t.Object`、`@t.CVTable`、`@t.NoVTable`、继承、dunder 方法） |
|
||
| [07-control-flow.md](wiki/07-control-flow.md) | 控制流（条件、循环、match） |
|
||
| [08-c-operations.md](wiki/08-c-operations.md) | C 语言操作（指针、内联汇编、FFI 外部函数声明、LLVM IR 内联） |
|
||
| [09-exceptions.md](wiki/09-exceptions.md) | 异常处理 |
|
||
| [10-imports.md](wiki/10-imports.md) | 模块与导入系统（存根生成、SHA1 命名空间与导入） |
|
||
| [11-builtins.md](wiki/11-builtins.md) | 内置函数与运算符 |
|
||
| [12-project.md](wiki/12-project.md) | 项目配置与构建（增量编译、SHA1 映射） |
|
||
| [13-bootstrapping.md](wiki/13-bootstrapping.md) | 自举可行性分析（当前进展、剩余工作、路径规划） |
|