Matx 是一个面向教学与实验的语言编译器和运行时，目标是实现一种可以静态分析的类 Python 语言。目前已经打通一条完整链路：读取带类型标注的 Python 函数，将 Python AST 转换成 Matx IR，生成 C++，编译为动态库，再从 Python 中加载和调用本地函数。
Python 函数
↓ inspect + ast.parse
Python AST
↓ SimpleParser
Matx IR
↓ Visitor / SourceRewriter
C++ 源码
↓ C++ 编译器
动态库
↓ Runtime / FFI
Python 可调用对象
Matx 不是完整的 Python 实现，也不打算复刻 CPython 的全部对象模型。它选择一个规模可控的语言子集，用来观察语法、类型、对象、代码生成与动态执行怎样组成一个编译系统。
Matx 是一套 C++ 语言模型技术栈中的语言层。长期设想是让用户通过类 Python 语言组织文本处理、Tensor、模型和训练过程，而底层数据结构与执行系统主要由 C++ 实现。
在这套设想中：
- Text 提供 Tokenizer 等文本处理组件；
- Zero 提供 Tensor、Autograd、Module 与 Optimizer；
- Matx 处理语言语法、对象、容器、控制流和模块调用；
- Tensor 编译器将 Tensor IR 降低为 CPU、CUDA 或其他硬件上的 Kernel。
类 Python 脚本语言
│
▼
Matx 语言编译器
│
┌────────────┴────────────┐
▼ ▼
Text 文本处理 Zero 训练框架
│ │
└────────────┬────────────┘
▼
Tensor Operator
│
▼
Tensor 编译器
│
┌───────────┼───────────┐
▼ ▼ ▼
CPU CUDA 其他硬件
当前仓库只实现其中的语言编译器、Runtime 和动态模块边界。Text、Zero 的接入以及 Tensor 编译器仍属于后续方向。
以一个最小函数为例：
def add(a: int, b: int) -> int:
return a + bPython Frontend 会把它转换成由 PrimFunc、PrimVar、PrimAdd 和 ReturnStmt 组成的 Matx IR。Rewriter 随后生成真正执行计算的 C++ 函数：
int64_t add(int64_t a, int64_t b) {
return (a + b);
}生成文件还包含一个 C ABI 包装函数。它检查并拆出 Value 参数，调用 add，再包装返回结果。模块注册表则记录函数名称与包装函数之间的关系，使 Runtime 可以在加载动态库后通过 "add" 找到它。
Python 参数
↓
Value[]
↓
add__c_api
↓
C++ add
↓
Value 返回值
↓
Python 值
整个实现由几层结构配合完成：
- Runtime：对象所有权、动态值、类型索引和标量数据类型。
- Container：AST 使用的类型容器，以及动态的
List、Dict、Set和Tuple。 - Function：类型擦除调用、参数转换和全局函数注册表。
- AST：表达式、语句、类型、函数与模块的内部表示。
- Visitor：节点分派、可读打印和 C++ 代码生成。
- Python Frontend：源码获取、作用域管理、类型检查与语法降低。
- FFI：Python 对象转换、C ABI、动态库加载与函数发现。
Python Frontend 目前支持一个受限子集：
- 带类型标注的函数参数和返回值；
int、float、bool、str、None和运行时 Handle；- 算术、比较、布尔、单目和条件表达式；
- 带类型兼容检查的局部赋值；
if、while和for ... in range(...)；list、dict、set字面量、索引、赋值和部分方法；- 受限的类构造、字段和实例方法。
遇到不支持的 Python 语法时，Frontend 会在编译阶段报错。完整 Python 兼容、继承、闭包、关键字参数、切片和任意函数调用不属于当前范围。详细边界见 python/CLASS_SUBSET.md。
Matx 需要支持 C++17 的编译器、CMake 3.24 以上版本、Python 开发头文件，以及 Unix 风格的动态库加载环境。
首先构建 C++ Runtime：
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build然后构建 Python 扩展：
g++ -shared -fPIC case_ext.cc \
$(python3-config --includes) \
-I. -Lbuild -lcase \
-o case_ext.so运行 Python 程序前，需要让动态加载器找到 libcase.so：
export LD_LIBRARY_PATH="$PWD/build:${LD_LIBRARY_PATH:-}"
export PYTHONPATH="$PWD/python:${PYTHONPATH:-}"可以创建一个 demo.py：
from ffi_system import module_loader, simple_compile
def add(a: int, b: int) -> int:
return a + b
assert simple_compile(add, "add.so")
module = module_loader("./add.so")
native_add = module.get_function("add")
print(native_add(10, 20))运行后应输出 30：
python3 demo.py仓库中的 python/run_*_test.py 用于覆盖不同语法与运行时路径。项目仍处于实验阶段，接口、语言范围和部分回归用例会随实现调整。
.
├── src/ # Runtime、AST、Visitor、代码生成、C API 与模块加载
├── python/ # Python Frontend、绑定、编译入口与回归用例
├── apps/ # C++ 测试和开发程序
├── docs/ # 当前语法与实现文档
├── Book/ # 较早的 Runtime 和编译器设计笔记
└── case_ext.cc
Matx 目前更适合作为教学项目：它不以完整语言兼容为目标，而是希望用一条可以运行的编译链路，展示类 Python 语言怎样从源码、AST 和 Runtime 走到 C++ 与本地执行。