# Rust 库 API

<cite>
**本文档引用的文件**
- [src/lib.rs](file://src/lib.rs)
- [src/main.rs](file://src/main.rs)
- [Cargo.toml](file://Cargo.toml)
- [src/codegen.rs](file://src/codegen.rs)
- [src/project.rs](file://src/project.rs)
- [src/dep_graph.rs](file://src/dep_graph.rs)
- [src/project_compiler.rs](file://src/project_compiler.rs)
- [src/coff.rs](file://src/coff.rs)
- [src/swc_transform.rs](file://src/swc_transform.rs)
- [src/tsn_ffi.rs](file://src/tsn_ffi.rs)
- [src/standalone_gen.rs](file://src/standalone_gen.rs)
- [src/standalone_loader.rs](file://src/standalone_loader.rs)
- [src/native_linker.rs](file://src/native_linker.rs)
- [loader/src/main.rs](file://loader/src/main.rs)
- [runtime/src/lib.rs](file://runtime/src/lib.rs)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构概览](#架构概览)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考虑](#性能考虑)
8. [故障排除指南](#故障排除指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介

ts-native 是一个将 TypeScript 直接编译为本地机器码的 Rust 库。该项目提供了完整的 TypeScript 到原生代码的编译链路，支持单文件编译、多模块项目编译以及独立可执行文件生成。

该库的核心特性包括：
- TypeScript 语法解析和转换
- CRANELIFT JIT 编译器后端
- COFF 对象文件格式支持
- 依赖图构建和模块管理
- 独立可执行文件生成
- 运行时插件系统

## 项目结构

项目采用模块化设计，主要分为以下核心模块：

```mermaid
graph TB
subgraph "核心库模块"
A[src/lib.rs] --> B[codegen.rs]
A --> C[project.rs]
A --> D[dep_graph.rs]
A --> E[project_compiler.rs]
A --> F[coff.rs]
A --> G[swc_transform.rs]
A --> H[tsn_ffi.rs]
A --> I[standalone_gen.rs]
A --> J[standalone_loader.rs]
A --> K[native_linker.rs]
end
subgraph "工具模块"
L[src/main.rs] --> B
L --> G
M[loader/src/main.rs] --> H
M --> J
end
subgraph "运行时模块"
N[runtime/src/lib.rs]
end
B --> N
H --> N
J --> N
```

**图表来源**
- [src/lib.rs:1-17](file://src/lib.rs#L1-L17)
- [src/main.rs:1-79](file://src/main.rs#L1-L79)
- [loader/src/main.rs:1-127](file://loader/src/main.rs#L1-L127)

**章节来源**
- [src/lib.rs:1-17](file://src/lib.rs#L1-L17)
- [Cargo.toml:1-57](file://Cargo.toml#L1-L57)

## 核心组件

### 代码生成器 (CodeGen)

代码生成器是整个编译系统的核心组件，负责将 TypeScript 抽象语法树转换为机器码。

**主要功能**：
- CRANELIFT JIT 编译器集成
- 机器码生成和优化
- 符号表管理和重定位处理
- 源码映射生成

**关键数据结构**：
- `HirExpr`: TypeScript 语法树表达式
- `RawModuleData`: 原始模块数据结构
- `CompileStats`: 编译性能统计

**章节来源**
- [src/codegen.rs:254-604](file://src/codegen.rs#L254-L604)
- [src/codegen.rs:80-196](file://src/codegen.rs#L80-L196)

### 项目管理器 (Project)

项目管理器负责扫描和管理 TypeScript 项目结构。

**主要功能**：
- 项目结构发现和解析
- 模块文件识别和组织
- 入口文件自动识别
- 模块路径解析

**关键数据结构**：
- `ProjectConfig`: 项目配置
- `SourceFile`: 源文件信息
- `Project`: 项目整体结构

**章节来源**
- [src/project.rs:44-153](file://src/project.rs#L44-L153)

### 依赖图构建器 (DepGraph)

依赖图构建器分析模块间的依赖关系，支持拓扑排序和闭包计算。

**主要功能**：
- 模块依赖关系分析
- 拓扑排序算法实现
- 依赖闭包计算
- 编译顺序确定

**章节来源**
- [src/dep_graph.rs:32-132](file://src/dep_graph.rs#L32-L132)

### 项目编译器 (ProjectCompiler)

项目编译器协调多模块项目的完整编译流程。

**主要功能**：
- 多模块并行编译
- 独立可执行文件生成
- 编译报告生成
- 性能统计和监控

**章节来源**
- [src/project_compiler.rs:189-332](file://src/project_compiler.rs#L189-L332)

### COFF 解析器 (CoffObject)

COFF 对象文件解析器支持标准 COFF 格式的解析和处理。

**主要功能**：
- COFF 文件头解析
- 节区信息提取
- 符号表解析
- 重定位信息处理

**章节来源**
- [src/coff.rs:55-231](file://src/coff.rs#L55-L231)

### TypeScript 转换器 (swc_transform)

TypeScript 转换器基于 SWC 解析器进行语法分析和转换。

**主要功能**：
- TypeScript 语法解析
- AST 转换为内部表示
- 语义分析和验证
- 代码生成准备

**章节来源**
- [src/swc_transform.rs:10-176](file://src/swc_transform.rs#L10-L176)

### FFI 接口 (tsn_ffi)

FFI 接口提供 C 可调用的编译器 API。

**主要功能**：
- DLL 导出函数
- 编译结果封装
- 内存管理
- 错误处理

**章节来源**
- [src/tsn_ffi.rs:27-106](file://src/tsn_ffi.rs#L27-L106)

### 独立生成器 (standalone_gen)

独立生成器负责生成独立可执行文件。

**主要功能**：
- 模块数据序列化
- 可执行文件生成
- 运行时集成
- 符号和重定位处理

**章节来源**
- [src/standalone_gen.rs:11-637](file://src/standalone_gen.rs#L11-L637)

### 独立加载器 (standalone_loader)

独立加载器提供预编译可执行文件的运行时支持。

**主要功能**：
- .tsnobj 文件加载
- 内存分配和重定位
- 运行时函数调用
- 错误处理和清理

**章节来源**
- [src/standalone_loader.rs:45-339](file://src/standalone_loader.rs#L45-L339)

### 原生链接器 (native_linker)

原生链接器提供不依赖外部工具的链接功能。

**主要功能**：
- 多对象文件合并
- 符号解析和重定位
- PE 文件生成
- 导入表处理

**章节来源**
- [src/native_linker.rs:133-382](file://src/native_linker.rs#L133-L382)

## 架构概览

ts-native 采用分层架构设计，各组件职责明确，通过清晰的接口进行交互。

```mermaid
graph TB
subgraph "输入层"
TS[TypeScript 源码]
end
subgraph "解析层"
SWC[SWC 解析器]
AST[AST 表达式]
end
subgraph "编译层"
CG[CodeGen]
IR[CRANELIFT IR]
OBJ[COFF 对象]
end
subgraph "链接层"
NL[Native Linker]
EXE[PE 可执行文件]
end
subgraph "运行时层"
RT[Runtime Plugin]
EXEC[执行引擎]
end
TS --> SWC
SWC --> AST
AST --> CG
CG --> IR
IR --> OBJ
OBJ --> NL
NL --> EXE
EXE --> RT
RT --> EXEC
```

**图表来源**
- [src/swc_transform.rs:10-34](file://src/swc_transform.rs#L10-L34)
- [src/codegen.rs:521-604](file://src/codegen.rs#L521-L604)
- [src/native_linker.rs:309-382](file://src/native_linker.rs#L309-L382)

## 详细组件分析

### 代码生成器详细分析

代码生成器实现了完整的编译流程，从 TypeScript AST 到机器码的转换。

```mermaid
sequenceDiagram
participant TS as TypeScript 源码
participant SWC as SWC 解析器
participant CG as CodeGen
participant CL as CRANELIFT
participant OBJ as COFF 对象
TS->>SWC : 解析 TypeScript
SWC->>CG : 生成 AST
CG->>CL : 创建 IR
CL->>CG : 生成机器码
CG->>OBJ : 输出 COFF
OBJ-->>CG : 编译结果
```

**图表来源**
- [src/swc_transform.rs:10-34](file://src/swc_transform.rs#L10-L34)
- [src/codegen.rs:521-604](file://src/codegen.rs#L521-L604)

**核心 API 功能**：
- `compile_coff()`: 编译为标准 COFF 格式
- `compile_to_raw_data()`: 编译为原始模块数据
- `set_module_symbols()`: 设置模块符号表
- `stats()`: 获取编译统计信息

**章节来源**
- [src/codegen.rs:521-707](file://src/codegen.rs#L521-L707)

### 项目编译器详细分析

项目编译器协调多模块项目的完整编译流程。

```mermaid
flowchart TD
Start([开始编译]) --> Scan[扫描项目结构]
Scan --> BuildGraph[构建依赖图]
BuildGraph --> Sort[拓扑排序]
Sort --> CompileModules[编译模块]
CompileModules --> Merge[Merge 模块数据]
Merge --> Generate[生成可执行文件]
Generate --> Report[生成编译报告]
Report --> End([编译完成])
CompileModules --> Error{编译错误?}
Error --> |是| HandleError[处理错误]
Error --> |否| CompileModules
HandleError --> End
```

**图表来源**
- [src/project_compiler.rs:249-332](file://src/project_compiler.rs#L249-L332)

**核心 API 功能**：
- `from_dir()`: 从目录创建编译器
- `compile_project()`: 编译整个项目
- `compile_module()`: 编译单个模块
- `build_standalone_executable()`: 生成独立可执行文件

**章节来源**
- [src/project_compiler.rs:205-727](file://src/project_compiler.rs#L205-L727)

### FFI 接口详细分析

FFI 接口提供了 C 可调用的编译器 API。

```mermaid
classDiagram
class TsnCompileResult {
+code_ptr : *mut u8
+code_len : u32
+data_ptr : *mut u8
+data_len : u32
+rdata_ptr : *mut u8
+rdata_len : u32
+symbols : *mut TsnSymbol
+symbol_count : u32
+relocations : *mut TsnRelocation
+reloc_count : u32
+error_msg : *mut c_char
+error_line : u32
+error_col : u32
+error_context : *mut c_char
+_context : *mut c_void
}
class TsnSymbol {
+section : u8
+offset : u32
+name : [u8; 64]
}
class TsnRelocation {
+section : u8
+offset : u32
+type_ : u8
+_padding : u8
+target_name : [u8; 64]
}
class TsnCompiler {
+compile(source : &str) CompiledModule
+compile_coff(source : &str) Vec<u8>
+load(path : &Path) Result
}
TsnCompileResult --> TsnSymbol
TsnCompileResult --> TsnRelocation
TsnCompiler --> TsnCompileResult
```

**图表来源**
- [src/tsn_ffi.rs:27-44](file://src/tsn_ffi.rs#L27-L44)
- [loader/src/main.rs:234-502](file://loader/src/main.rs#L234-L502)

**核心 API 功能**：
- `tsn_compile()`: 编译 TypeScript 源码
- `tsn_free_result()`: 释放编译结果
- `tsn_compile_coff()`: 编译为 COFF 格式
- `tsn_free_coff()`: 释放 COFF 数据

**章节来源**
- [src/tsn_ffi.rs:60-170](file://src/tsn_ffi.rs#L60-L170)
- [loader/src/main.rs:337-502](file://loader/src/main.rs#L337-L502)

### 运行时插件详细分析

运行时插件提供了 JavaScript 运行时函数支持。

**核心运行时函数**：
- `js_print()`: 控制台输出
- `js_add()`, `js_sub()`, `js_mul()`, `js_div()`: 基础算术运算
- `js_array_new()`: 数组创建
- `js_object_new()`: 对象创建
- `js_fs_*()`: 文件系统操作
- `js_math_*()`: 数学函数

**章节来源**
- [runtime/src/lib.rs:137-800](file://runtime/src/lib.rs#L137-L800)

## 依赖分析

项目采用模块化依赖管理，各模块间依赖关系清晰。

```mermaid
graph TB
subgraph "核心依赖"
SWC[swc_common/swc_ecma_parser]
CRANELIFT[cranelift-frontend/cranelift-object]
OBJECT[object crate]
end
subgraph "项目模块"
CODEGEN[codegen.rs]
PROJECT[project.rs]
DEPGRAPH[dep_graph.rs]
COMPILER[project_compiler.rs]
COFF[coff.rs]
TRANSFORM[swc_transform.rs]
FFI[tsn_ffi.rs]
STANDALONE[standalone_gen.rs]
LOADER[standalone_loader.rs]
LINKER[native_linker.rs]
end
SWC --> TRANSFORM
CRANELIFT --> CODEGEN
OBJECT --> COFF
TRANSFORM --> CODEGEN
CODEGEN --> COMPILER
PROJECT --> COMPILER
DEPGRAPH --> COMPILER
COMPILER --> STANDALONE
FFI --> LOADER
STANDALONE --> LOADER
COFF --> LINKER
```

**图表来源**
- [Cargo.toml:22-47](file://Cargo.toml#L22-L47)

**依赖特点**：
- **解析层**: SWC 依赖提供 TypeScript 解析能力
- **编译层**: CRANELIFT 依赖提供 JIT 编译能力  
- **格式层**: object crate 依赖提供 COFF 格式支持
- **工具层**: clap 依赖提供命令行解析

**章节来源**
- [Cargo.toml:22-57](file://Cargo.toml#L22-L57)

## 性能考虑

### 编译性能优化

1. **并行编译**: 项目编译器支持多模块并行编译
2. **内存管理**: 使用 RAII 和智能指针管理内存
3. **缓存策略**: 符号表和依赖图的缓存复用
4. **增量编译**: 支持部分文件的增量编译

### 运行时性能优化

1. **NaN-tagging**: 使用 IEEE 754 NaN 位来编码 JavaScript 值
2. **池化技术**: 字符串、数组、对象的内存池管理
3. **内联优化**: 关键函数的编译器内联
4. **JIT 优化**: CRANELIFT 的即时编译优化

## 故障排除指南

### 常见编译错误

**错误类型**: 语法解析错误
**解决方案**: 检查 TypeScript 语法，确保符合 ES2020 标准

**错误类型**: 依赖解析错误  
**解决方案**: 检查模块导入路径，确保相对路径正确

**错误类型**: 编译器错误
**解决方案**: 查看编译器输出的详细错误信息

### 运行时错误

**错误类型**: 符号未解析
**解决方案**: 确保运行时插件正确加载，检查符号名称

**错误类型**: 内存访问错误
**解决方案**: 检查数组边界和对象属性访问

**错误类型**: 重定位失败
**解决方案**: 验证 .tsnobj 文件完整性

**章节来源**
- [src/tsn_ffi.rs:294-341](file://src/tsn_ffi.rs#L294-L341)
- [loader/src/main.rs:537-743](file://loader/src/main.rs#L537-L743)

## 结论

ts-native 提供了一个完整的 TypeScript 到原生代码的编译解决方案。其模块化设计使得各个组件职责明确，易于维护和扩展。通过 CRANELIFT JIT 编译器和运行时插件系统，该库能够在保证性能的同时提供丰富的 JavaScript 运行时功能。

主要优势：
- **高性能**: 直接编译为机器码，无解释器开销
- **模块化**: 清晰的模块分离和接口设计
- **可扩展**: 支持插件系统和自定义运行时函数
- **跨平台**: 基于 Rust 的跨平台编译能力

## 附录

### API 使用示例

**基本编译示例**：
```rust
use tsnative::codegen::CodeGen;
use tsnative::swc_transform;

let source = std::fs::read_to_string("example.ts")?;
let hir = swc_transform::parse(&source)?;
let mut codegen = CodeGen::new();
let binary = codegen.compile_coff(&hir)?;
std::fs::write("output.obj", &binary)?;
```

**项目编译示例**：
```rust
use tsnative::project_compiler::ProjectCompiler;

let mut compiler = ProjectCompiler::from_dir(&std::path::Path::new("."))?;
let report = compiler.compile_project()?;
println!("{:?}", report);
```

**章节来源**
- [src/main.rs:57-78](file://src/main.rs#L57-L78)
- [src/project_compiler.rs:249-332](file://src/project_compiler.rs#L249-L332)

### 配置选项

**编译器配置**：
- `entry_point`: 入口函数名称
- `image_base`: PE 文件基地址
- `stack_reserve`: 栈预留大小
- `heap_reserve`: 堆预留大小

**运行时配置**：
- `auto_inject_runtime`: 自动注入运行时
- `runtime_objects`: 运行时对象文件列表

**章节来源**
- [src/native_linker.rs:18-35](file://src/native_linker.rs#L18-L35)
- [src/project_compiler.rs:205-246](file://src/project_compiler.rs#L205-L246)