# API 参考

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

## 更新摘要
**所做更改**
- 新增完整的 Rust 库 API 技术规范
- 更新 FFI 外部函数接口的详细技术规范
- 增加 ABI 头文件的完整接口定义
- 补充 COFF 可选导出功能的技术规范
- 完善运行时环境的完整 API 文档
- 更新项目管理和编译器模块的详细接口说明

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

## 简介

ts-native 是一个将 TypeScript 直接编译为本地机器码的编译器系统。该项目提供了完整的工具链，包括 TypeScript 解析器、中间表示生成、JIT 编译器、运行时环境和加载器。系统采用模块化设计，支持通过 DLL 接口和直接 Rust API 两种方式使用。

## 项目结构

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

```mermaid
graph TB
subgraph "核心编译器"
A[src/lib.rs] --> B[src/codegen.rs]
A --> C[src/swc_transform.rs]
A --> D[src/tsn_ffi.rs]
end
subgraph "运行时环境"
E[runtime/src/lib.rs] --> F[tsn_runtime.dll]
end
subgraph "项目管理"
G[src/project.rs] --> H[src/project_compiler.rs]
G --> I[src/standalone_gen.rs]
end
subgraph "加载器"
J[loader/src/main.rs] --> K[src/standalone_loader.rs]
end
subgraph "辅助工具"
L[src/coff.rs] --> M[Cargo.toml]
end
B --> E
H --> J
I --> K
```

**图表来源**
- [src/lib.rs:1-17](file://src/lib.rs#L1-L17)
- [src/codegen.rs:1-800](file://src/codegen.rs#L1-L800)
- [src/swc_transform.rs:1-800](file://src/swc_transform.rs#L1-L800)

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

## 核心组件

### 主要模块接口

#### 1. 编译器核心模块
- **tsn_ffi**: 提供 C API 接口，用于 DLL 导出
- **codegen**: 主要的代码生成器，负责将 AST 转换为机器码
- **swc_transform**: TypeScript 解析和转换模块

#### 2. 运行时模块
- **runtime**: 提供 JavaScript 运行时函数和基础类型支持

#### 3. 项目管理模块
- **project**: 项目结构发现和管理
- **project_compiler**: 多模块项目编译器
- **standalone_gen**: 独立可执行文件生成器

**章节来源**
- [src/lib.rs:4-16](file://src/lib.rs#L4-L16)
- [runtime/src/lib.rs:1-800](file://runtime/src/lib.rs#L1-L800)

## 架构概览

```mermaid
sequenceDiagram
participant TS as TypeScript 源码
participant Parser as SWC 解析器
participant CodeGen as 代码生成器
participant JIT as JIT 编译器
participant Runtime as 运行时环境
participant Loader as 加载器
TS->>Parser : 解析 TypeScript
Parser->>CodeGen : 生成中间表示
CodeGen->>JIT : 生成机器码
JIT->>Runtime : 提供运行时函数
Runtime->>Loader : 执行入口函数
Loader-->>TS : 返回执行结果
```

**图表来源**
- [src/swc_transform.rs:10-34](file://src/swc_transform.rs#L10-L34)
- [src/codegen.rs:520-604](file://src/codegen.rs#L520-L604)
- [loader/src/main.rs:387-502](file://loader/src/main.rs#L387-L502)

## 详细组件分析

### FFI 接口模块

#### 主要结构体定义

```mermaid
classDiagram
class TsnSymbol {
+u8 section
+u32 offset
+[u8; 64] name
}
class TsnRelocation {
+u8 section
+u32 offset
+u8 type_
+u8 _padding
+[u8; 64] target_name
}
class TsnCompileResult {
+*mut u8 code_ptr
+u32 code_len
+*mut u8 data_ptr
+u32 data_len
+*mut u8 rdata_ptr
+u32 rdata_len
+*mut TsnSymbol symbols
+u32 symbol_count
+*mut TsnRelocation relocations
+u32 reloc_count
+*mut c_char error_msg
+u32 error_line
+u32 error_col
+*mut c_char error_context
+*mut c_void _context
}
class CompileContext {
+Vec~u8~ code
+Vec~u8~ data
+Vec~u8~ rdata
+Vec~TsnSymbol~ symbols
+Vec~TsnRelocation~ relocations
+Option~CString~ error_msg
+Option~CString~ error_context
}
```

**图表来源**
- [src/tsn_ffi.rs:11-44](file://src/tsn_ffi.rs#L11-L44)
- [src/tsn_ffi.rs:48-56](file://src/tsn_ffi.rs#L48-L56)

#### 核心 API 函数

##### tsn_compile 函数
- **功能**: 编译 TypeScript 源代码为 TSN 模块
- **参数**: `source: *const c_char` - TypeScript 源代码字符串
- **返回值**: `*mut TsnCompileResult` - 编译结果指针
- **错误处理**: 返回错误信息和行号
- **内存管理**: 调用者需要使用 tsn_free_result 释放

##### tsn_free_result 函数
- **功能**: 释放编译结果内存
- **参数**: `result: *mut TsnCompileResult` - 要释放的结果指针
- **返回值**: `void`
- **内存管理**: 释放所有关联的内存，包括错误信息和上下文

##### tsn_version 函数
- **功能**: 获取版本信息
- **参数**: 无
- **返回值**: `*const c_char` - 版本字符串

##### tsn_compile_coff 函数（可选）
- **功能**: 编译为标准 COFF .obj 字节流
- **参数**: `source: *const c_char`, `out_len: *mut u32`
- **返回值**: `*mut u8` - COFF 字节流指针
- **内存管理**: 调用者需要使用 tsn_free_coff 释放
- **启用条件**: 需要启用 coff 特性

##### tsn_free_coff 函数（可选）
- **功能**: 释放 COFF 字节流
- **参数**: `ptr: *mut u8, len: u32`
- **返回值**: `void`

**章节来源**
- [src/tsn_ffi.rs:60-113](file://src/tsn_ffi.rs#L60-L113)
- [src/tsn_ffi.rs:83-106](file://src/tsn_ffi.rs#L83-L106)
- [src/tsn_ffi.rs:108-113](file://src/tsn_ffi.rs#L108-L113)
- [tsn_abi.h:62-86](file://tsn_abi.h#L62-L86)

### ABI 头文件规范

#### 结构体定义映射

| C 结构体 | Rust 结构体 | 字段映射 |
|---------|------------|----------|
| TsnSymbol | TsnSymbol | section, offset, name[64] |
| TsnRelocation | TsnRelocation | section, offset, type_, target_name[64] |
| TsnCompileResult | TsnCompileResult | 所有字段 |

#### 函数原型

```c
// 编译 TypeScript 源代码
__declspec(dllexport) TsnCompileResult* tsn_compile(const char* source);

// 编译为 COFF 对象文件
__declspec(dllexport) uint8_t* tsn_compile_coff(const char* source, uint32_t* out_len);

// 内存管理函数
__declspec(dllexport) void tsn_free_result(TsnCompileResult* result);
__declspec(dllexport) void tsn_free_coff(uint8_t* ptr, uint32_t len);

// 查询函数
__declspec(dllexport) const char* tsn_version(void);
```

**章节来源**
- [tsn_abi.h:14-92](file://tsn_abi.h#L14-L92)

### 代码生成器模块

#### 核心数据结构

```mermaid
classDiagram
class CodeGen {
-FunctionBuilderContext builder_context
-HashMap~String, FuncId~ function_ids
-HashMap~String, usize~ function_param_counts
-HashSet~String~ string_pool
-HashMap~String, String~ external_functions
-Vec~SourceMapEntry~ source_map
-String current_func
-u32 current_line
-CompileStats stats
-HashMap~String, (String, String)~ import_bindings
-HashMap~String, String~ module_symbols
}
class RawModuleData {
+HashMap~String, Vec~u8~~ functions
+HashMap~String, Vec~u8~~ data_items
+Vec~RawSymbol~ symbols
+Vec~RawRelocation~ relocations
}
class CompileStats {
+u64 parse_time_ms
+u64 codegen_time_ms
+u64 coff_time_ms
+u64 extract_time_ms
+usize function_count
+usize string_count
+usize code_size
+usize data_size
+usize rdata_size
}
```

**图表来源**
- [src/codegen.rs:254-272](file://src/codegen.rs#L254-L272)
- [src/codegen.rs:21-27](file://src/codegen.rs#L21-L27)
- [src/codegen.rs:241-252](file://src/codegen.rs#L241-L252)

#### 主要编译方法

##### compile_coff 方法
- **功能**: 编译为标准 COFF .obj 字节流
- **参数**: `exprs: &[HirExpr]` - 抽象语法树表达式
- **返回值**: `Result<Vec<u8>>` - COFF 字节流
- **特性**: 使用 Cranelift JIT 编译器生成机器码

##### compile_to_raw_data 方法
- **功能**: 编译并提取原始模块数据
- **参数**: `exprs: &[HirExpr]` - 抽象语法树表达式
- **返回值**: `Result<RawModuleData>` - 原始模块数据
- **用途**: 供 JIT/FFI 路径使用

**章节来源**
- [src/codegen.rs:520-604](file://src/codegen.rs#L520-L604)
- [src/codegen.rs:606-707](file://src/codegen.rs#L606-L707)

### 运行时环境模块

#### 基础类型系统

```mermaid
flowchart TD
Start([运行时初始化]) --> InitPool["初始化对象池<br/>- STRING_POOL<br/>- ARRAY_POOL<br/>- OBJECT_POOL"]
InitPool --> TagSystem["设置 NaN-tagging 标签<br/>- TAG_NUMBER: 0x7FF0<br/>- TAG_STRING: 0x7FF1<br/>- TAG_OBJECT: 0x7FF2<br/>- TAG_BOOLEAN: 0x7FF3<br/>- TAG_UNDEFINED: 0x7FF4<br/>- TAG_NULL: 0x7FF5<br/>- TAG_FUNCTION: 0x7FF6<br/>- TAG_ARRAY: 0x7FF7"]
TagSystem --> PoolOps["对象池操作<br/>- store_string()<br/>- store_object()<br/>- store_array()"]
PoolOps --> TypeOps["类型判断<br/>- get_tag()<br/>- is_number()<br/>- get_string()<br/>- get_array()<br/>- get_object()"]
TypeOps --> End([运行时就绪])
```

**图表来源**
- [runtime/src/lib.rs:39-121](file://runtime/src/lib.rs#L39-L121)
- [runtime/src/lib.rs:21-24](file://runtime/src/lib.rs#L21-L24)

#### 核心运行时函数

##### 基础算术运算
- **js_add**: 加法运算
- **js_sub**: 减法运算  
- **js_mul**: 乘法运算
- **js_div**: 除法运算
- **js_fmod**: 取模运算

##### 数组操作
- **js_array_new**: 创建新数组
- **js_array_push**: 向数组添加元素
- **js_array_set**: 设置数组元素
- **js_index_get**: 读取数组/对象属性
- **js_property_length**: 获取长度属性

##### 对象操作
- **js_object_new**: 创建新对象
- **js_object_set**: 设置对象属性
- **js_object_get**: 获取对象属性

##### 文件系统操作
- **js_fs_read_file_sync**: 同步读取文件
- **js_fs_write_file_sync**: 同步写入文件
- **js_fs_exists_sync**: 检查文件存在
- **js_fs_mkdir_sync**: 创建目录
- **js_fs_unlink_sync**: 删除文件
- **js_fs_rmdir_sync**: 删除目录
- **js_fs_readdir_sync**: 读取目录内容
- **js_fs_stat_sync**: 获取文件状态

##### JSON 操作
- **js_json_stringify**: 对象序列化
- **js_json_parse**: 对象反序列化

##### 类型检查
- **js_typeof**: 获取变量类型
- **js_array_is_array**: 检查是否为数组
- **js_object_has_own**: 检查对象属性

**章节来源**
- [runtime/src/lib.rs:203-323](file://runtime/src/lib.rs#L203-L323)
- [runtime/src/lib.rs:325-595](file://runtime/src/lib.rs#L325-L595)
- [runtime/src/lib.rs:646-800](file://runtime/src/lib.rs#L646-L800)

### 项目管理模块

#### 项目结构管理

```mermaid
classDiagram
class ProjectConfig {
+Vec~String~ entries
+String src_dir
+String out_dir
}
class SourceFile {
+PathBuf path
+String module_name
+bool is_entry
+Option~String~ content
}
class Project {
+PathBuf root
+ProjectConfig config
+HashMap~PathBuf, SourceFile~ files
+Vec~PathBuf~ entries
+Vec~PathBuf~ modules
}
class DepGraph {
+HashMap~PathBuf, DepGraphNode~ nodes
+Vec~PathBuf~ compile_order
}
Project --> SourceFile : contains
DepGraph --> Project : manages
```

**图表来源**
- [src/project.rs:8-56](file://src/project.rs#L8-L56)
- [src/project.rs:58-153](file://src/project.rs#L58-L153)

#### 依赖图构建

##### 依赖解析流程
1. **模块发现**: 扫描项目目录识别所有 TypeScript 文件
2. **导入解析**: 解析每个文件的 import 语句
3. **依赖关系建立**: 构建模块间的依赖关系图
4. **拓扑排序**: 确定编译顺序
5. **符号表生成**: 收集模块导出符号

**章节来源**
- [src/project.rs:65-153](file://src/project.rs#L65-L153)
- [src/project_compiler.rs:205-246](file://src/project_compiler.rs#L205-L246)

### 加载器模块

#### 编译器 DLL 包装

```mermaid
sequenceDiagram
participant Loader as 加载器
participant DLL as ts-native.dll
participant Runtime as 运行时
participant Plugin as 插件
Loader->>DLL : tsn_compile(source)
DLL->>DLL : 解析 TypeScript
DLL->>DLL : 生成机器码
DLL->>Loader : 返回 TsnCompileResult
Loader->>Runtime : 加载 tsn_runtime.dll
Loader->>Plugin : 加载插件 DLL
Loader->>Loader : 应用重定位
Loader->>Loader : 调用入口函数
Loader-->>Loader : 返回执行结果
```

**图表来源**
- [loader/src/main.rs:387-502](file://loader/src/main.rs#L387-L502)
- [loader/src/main.rs:537-743](file://loader/src/main.rs#L537-L743)

#### 独立可执行文件生成

##### .tsnobj 文件格式
- **头部**: 包含各节区长度和符号数量信息
- **代码节**: 编译后的机器码
- **数据节**: 初始化的数据
- **符号表**: 模块符号信息
- **重定位表**: 外部符号引用

**章节来源**
- [src/standalone_gen.rs:489-605](file://src/standalone_gen.rs#L489-L605)
- [src/standalone_loader.rs:45-125](file://src/standalone_loader.rs#L45-L125)

## 依赖关系分析

```mermaid
graph LR
subgraph "编译时依赖"
A[swc_common] --> B[SWC 解析器]
C[cranelift-frontend] --> D[JIT 编译器]
E[cranelift-module] --> D
F[cranelift-object] --> D
G[object] --> H[COFF 解析]
end
subgraph "运行时依赖"
I[tsn_runtime.dll] --> J[运行时函数]
K[Windows API] --> L[内存管理]
end
subgraph "工具链"
M[rustc] --> N[编译器]
O[clang-cl] --> P[COFF 生成器]
end
```

**图表来源**
- [Cargo.toml:26-51](file://Cargo.toml#L26-L51)

**章节来源**
- [Cargo.toml:26-61](file://Cargo.toml#L26-L61)

## 性能考虑

### 编译性能优化

1. **JIT 编译**: 使用 Cranelift JIT 编译器提供高性能代码生成
2. **内存池**: 运行时使用对象池减少垃圾回收开销
3. **NaN-tagging**: 使用 IEEE 754 浮点数的 NaN 位进行类型标记，避免额外内存开销
4. **增量编译**: 支持部分重新编译，提高开发效率

### 运行时性能特性

1. **零成本抽象**: 运行时函数直接映射到机器指令
2. **内联优化**: 编译器内联常见运行时函数
3. **缓存友好**: 对象布局经过优化以提高缓存命中率

## 故障排除指南

### 常见编译错误

#### TypeScript 解析错误
- **症状**: 编译时出现语法错误
- **解决方案**: 检查 TypeScript 语法，确保使用受支持的特性

#### 运行时符号解析失败
- **症状**: 执行时出现未解析的外部符号
- **解决方案**: 确保所有必需的运行时函数都在 tsn_runtime.dll 中实现

#### 内存分配错误
- **症状**: VirtualAlloc 调用失败
- **解决方案**: 检查系统可用内存，确认有足够的虚拟内存空间

#### FFI 接口错误
- **症状**: DLL 导出函数调用失败
- **解决方案**: 验证参数类型和内存管理，确保正确使用释放函数

**章节来源**
- [src/tsn_ffi.rs:294-341](file://src/tsn_ffi.rs#L294-L341)
- [loader/src/main.rs:574-580](file://loader/src/main.rs#L574-L580)

## 结论

ts-native 提供了一个完整且高效的 TypeScript 到本地机器码的编译解决方案。其模块化架构设计使得各个组件可以独立开发和维护，同时保持良好的性能和可扩展性。通过合理的错误处理机制和详细的 API 文档，开发者可以有效地使用和扩展这个编译器系统。

## 附录

### 版本兼容性

- **最低 Rust 版本**: 1.70.0
- **目标平台**: Windows (AMD64)
- **TypeScript 支持**: ES2020 语法特性
- **运行时要求**: Windows 7 SP1 或更高版本

### 迁移指南

#### 从旧版本升级
1. 更新 Cargo.toml 中的依赖版本
2. 检查 API 变更，特别是 FFI 接口
3. 验证运行时函数的兼容性
4. 测试编译器输出的二进制兼容性

#### 自定义运行时扩展
1. 在 runtime 模块中添加新的运行时函数
2. 更新 tsn_runtime.dll 的导出符号
3. 在加载器中注册新的符号解析器
4. 编写相应的单元测试验证功能

### 使用示例

#### 基本编译流程
```typescript
// 示例 TypeScript 代码
function main(): number {
    return 42;
}
```

#### 多入口项目示例
- **入口 1**: [test_multi_entry/src/main.ts](file://test_multi_entry/src/main.ts)
- **入口 2**: [test_multi_entry/src/cli.ts](file://test_multi_entry/src/cli.ts)

**章节来源**
- [Cargo.toml:1-61](file://Cargo.toml#L1-L61)
- [runtime/src/lib.rs:425-455](file://runtime/src/lib.rs#L425-L455)
- [test_multi_entry/src/main.ts:1-15](file://test_multi_entry/src/main.ts#L1-L15)
- [test_multi_entry/src/cli.ts:1-15](file://test_multi_entry/src/cli.ts#L1-L15)