# 快速开始

<cite>
**本文引用的文件**
- [Cargo.toml](file://Cargo.toml)
- [src/main.rs](file://src/main.rs)
- [src/lib.rs](file://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/project_compiler.rs](file://src/project_compiler.rs)
- [src/dep_graph.rs](file://src/dep_graph.rs)
- [src/standalone_gen.rs](file://src/standalone_gen.rs)
- [src/bin/native_linker_main.rs](file://src/bin/native_linker_main.rs)
- [loader/Cargo.toml](file://loader/Cargo.toml)
- [runtime/Cargo.toml](file://runtime/Cargo.toml)
- [build.rs](file://build.rs)
- [docs/README.md](file://docs/README.md)
- [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)
- [test_multi_entry/src/simple.ts](file://test_multi_entry/src/simple.ts)
- [test_multi_entry/src/utils/math.ts](file://test_multi_entry/src/utils/math.ts)
- [test_multi_entry/src/utils/string.ts](file://test_multi_entry/src/utils/string.ts)
- [test_multi_entry/src/lib/core.ts](file://test_multi_entry/src/lib/core.ts)
- [tsnp/console/ty-native.toml](file://tsnp/console/ts-native.toml)
</cite>

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

## 简介
本指南面向初学者与进阶用户，帮助你在本地快速安装并使用 ts-native 编译器，完成从单文件到多模块项目的编译与运行。你将学到：
- 如何准备 Rust 工具链与系统依赖
- 如何进行基础编译与运行
- 如何组织与编译多模块项目
- 常见问题排查与最佳实践

## 项目结构
该仓库采用多 crate 结构，核心编译器位于根 crate，配套 loader 与 runtime 分别在独立 crate 中，便于运行时加载与执行。

```mermaid
graph TB
A["根项目<br/>Cargo.toml"] --> B["编译器二进制<br/>src/main.rs"]
A --> C["库模块<br/>src/lib.rs"]
A --> D["构建脚本<br/>build.rs"]
A --> E["项目配置<br/>tsn-project.toml(待实现)"]
F["loader 二进制<br/>loader/Cargo.toml"] --> G["运行时加载器<br/>loader/src/main.rs"]
H["runtime 动态库<br/>runtime/Cargo.toml"] --> I["tsn-runtime 动态库"]
J["测试多入口项目<br/>test_multi_entry/*"] --> K["示例 TypeScript 源码"]
L["原生链接器<br/>src/bin/native_linker_main.rs"] --> M["TSN 原生链接器"]
```

图表来源
- [Cargo.toml:1-57](file://Cargo.toml#L1-L57)
- [loader/Cargo.toml:1-23](file://loader/Cargo.toml#L1-L23)
- [runtime/Cargo.toml:1-28](file://runtime/Cargo.toml#L1-L28)
- [src/bin/native_linker_main.rs:1-163](file://src/bin/native_linker_main.rs#L1-L163)

章节来源
- [Cargo.toml:1-57](file://Cargo.toml#L1-L57)
- [loader/Cargo.toml:1-23](file://loader/Cargo.toml#L1-L23)
- [runtime/Cargo.toml:1-28](file://runtime/Cargo.toml#L1-L28)

## 核心组件
- 编译器二进制：负责解析 TypeScript 输入、生成中间表示、通过 Cranelift 生成 COFF 对象文件，并输出 .obj。
- 库模块：提供代码生成、COFF 处理、项目管理、依赖图、独立运行生成等能力。
- 运行时动态库：提供基础库能力（如打印、数学运算等），供编译产物链接与运行。
- 加载器：加载运行时动态库并执行编译产物。
- 原生链接器：支持 TSN/COFF 对象文件的原生链接，生成可执行文件。

章节来源
- [src/main.rs:1-79](file://src/main.rs#L1-L79)
- [src/lib.rs:1-17](file://src/lib.rs#L1-L17)
- [src/codegen.rs:1-200](file://src/codegen.rs#L1-L200)
- [src/swc_transform.rs:1-200](file://src/swc_transform.rs#L1-L200)
- [runtime/Cargo.toml:1-28](file://runtime/Cargo.toml#L1-L28)
- [loader/Cargo.toml:1-23](file://loader/Cargo.toml#L1-L23)
- [src/bin/native_linker_main.rs:1-163](file://src/bin/native_linker_main.rs#L1-L163)

## 架构总览
下图展示了从 TypeScript 到可执行文件的端到端流程，以及运行时加载与执行的关键步骤。

```mermaid
sequenceDiagram
participant Dev as "开发者"
participant CLI as "ts-native(编译器)"
participant SWC as "SWC 解析/转换"
participant CG as "代码生成(Cranelift)"
participant OBJ as ".obj 文件"
participant LDR as "tsn-loader"
participant RT as "tsn-runtime"
Dev->>CLI : "传入输入文件与输出参数"
CLI->>SWC : "解析 TypeScript 源码"
SWC-->>CLI : "生成 HIR"
CLI->>CG : "生成 COFF 对象"
CG-->>OBJ : "写入 .obj"
Dev->>LDR : "执行 tsn-loader <input.ts>"
LDR->>RT : "加载运行时动态库"
LDR->>OBJ : "解析并执行 .obj"
RT-->>Dev : "输出运行结果"
```

图表来源
- [src/main.rs:55-76](file://src/main.rs#L55-L76)
- [src/swc_transform.rs:10-34](file://src/swc_transform.rs#L10-L34)
- [src/codegen.rs:1-200](file://src/codegen.rs#L1-L200)
- [loader/Cargo.toml:13-22](file://loader/Cargo.toml#L13-L22)
- [runtime/Cargo.toml:6-8](file://runtime/Cargo.toml#L6-L8)

## 详细组件分析

### 安装与环境准备
- Rust 工具链
  - 使用 rustup 安装最新稳定版工具链，确保 cargo 与 rustc 可用。
  - 推荐版本：Rust 1.70+（以实际工具链支持为准）。
- 系统依赖
  - Windows：MSVC 工具链（如 VS Build Tools 或 Visual Studio），确保链接器可用。
  - Linux/macOS：标准 C 工具链（cc/clang）与链接器。
- 项目依赖
  - 项目通过 Cargo 管理 Rust 依赖；构建脚本会根据需要编译少量 C 源码（如运行时启动代码）。

章节来源
- [Cargo.toml:22-51](file://Cargo.toml#L22-L51)
- [build.rs:1-33](file://build.rs#L1-L33)

### 基础编译与运行（单文件）
- 编译命令
  - 基本形式：传入 TypeScript 文件，可选 -o 指定输出对象文件名（推荐 .obj 扩展名）。
  - 若未指定输出，编译器会自动推断输出路径并添加 .obj 后缀。
- 运行方式
  - 编译完成后，控制台会提示如何使用 tsn-loader 执行编译产物。
  - tsn-loader 会加载运行时动态库并执行编译得到的对象文件。

章节来源
- [src/main.rs:10-13](file://src/main.rs#L10-L13)
- [src/main.rs:42-53](file://src/main.rs#L42-L53)
- [src/main.rs:74-75](file://src/main.rs#L74-L75)

### 多模块项目编译与运行
- 项目结构
  - 项目扫描 src 目录下的 .ts 文件，自动识别入口文件（含 main 的文件或默认 main.ts）。
  - 支持显式配置入口（待实现配置文件 tsn-project.toml）。
- 编译流程
  - 项目编译器构建依赖图，按拓扑顺序编译各模块为 .obj。
  - 为每个入口生成独立可执行文件（内嵌 loader）。
- 示例项目
  - 测试多入口项目包含多个入口与模块，演示模块间导入与运行。

章节来源
- [src/project.rs:58-153](file://src/project.rs#L58-L153)
- [src/project_compiler.rs:1-200](file://src/project_compiler.rs#L1-L200)
- [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)
- [test_multi_entry/src/simple.ts:1-5](file://test_multi_entry/src/simple.ts#L1-L5)

### 关键流程：从 TypeScript 到 COFF 对象
- 解析与转换
  - 使用 SWC 解析 TypeScript 源码，生成 AST 并转换为内部 HIR（高层中间表示）。
- 代码生成
  - 通过 Cranelift 将 HIR 编译为目标机器码，输出 COFF 对象格式。
- 符号与重定位
  - 记录符号与重定位信息，供链接与运行时解析。

```mermaid
flowchart TD
Start(["开始"]) --> Parse["解析 TypeScript 源码"]
Parse --> HIR["生成 HIR"]
HIR --> Gen["Cranelift 生成 COFF 对象"]
Gen --> Write["写入 .obj 文件"]
Write --> End(["结束"])
```

图表来源
- [src/swc_transform.rs:10-34](file://src/swc_transform.rs#L10-L34)
- [src/codegen.rs:1-200](file://src/codegen.rs#L1-L200)

章节来源
- [src/swc_transform.rs:1-200](file://src/swc_transform.rs#L1-L200)
- [src/codegen.rs:1-200](file://src/codegen.rs#L1-L200)

### 运行时与加载器
- 运行时动态库
  - 提供基础库能力（如打印、数学运算等），以 cdylib 形式输出，供编译产物链接。
- 加载器
  - 二进制入口负责加载运行时动态库并执行编译产物；针对 Windows MSVC 配置了链接参数。

章节来源
- [runtime/Cargo.toml:6-8](file://runtime/Cargo.toml#L6-L8)
- [loader/Cargo.toml:13-22](file://loader/Cargo.toml#L13-L22)

### 原生链接器与独立可执行文件
- 原生链接器
  - 支持 TSN/COFF 对象文件的原生链接，生成可执行文件。
  - 自动注入运行时对象文件，配置必要的 DLL 导入。
- 独立可执行文件生成
  - 项目编译器可生成内嵌运行时的独立可执行文件。
  - 支持符号重命名与重定位，确保模块间正确调用。

章节来源
- [src/bin/native_linker_main.rs:1-163](file://src/bin/native_linker_main.rs#L1-L163)
- [src/standalone_gen.rs:1-200](file://src/standalone_gen.rs#L1-L200)
- [src/project_compiler.rs:384-567](file://src/project_compiler.rs#L384-L567)

### 项目配置与模块解析
- 项目配置
  - 支持 ts-native.toml 中的 shim 配置。
  - 支持 tsn-project.toml（待实现）。
- 模块解析
  - 支持相对路径与非相对路径导入。
  - 优先解析用户模块，其次解析 shim，最后解析 npm 包。
  - 支持 package.json 的 exports/main 字段解析。

章节来源
- [src/project.rs:86-91](file://src/project.rs#L86-L91)
- [src/project.rs:285-354](file://src/project.rs#L285-L354)
- [src/project.rs:356-401](file://src/project.rs#L356-L401)
- [tsnp/console/ts-native.toml:1-16](file://tsnp/console/ts-native.toml#L1-L16)

## 依赖分析
- Rust 依赖
  - SWC 生态：解析与转换 TypeScript。
  - Cranelift：JIT/静态代码生成，生成目标对象。
  - serde/serde_json：序列化与 JSON 处理。
  - object：读取对象文件的节、符号与重定位。
  - clap：命令行参数解析。
- 构建依赖
  - cc：用于编译少量 C 源码（运行时启动代码）。
- 特性开关
  - native-linker：启用原生链接器相关模块（默认关闭）。
  - coff：COFF 相关功能（默认关闭）。

```mermaid
graph LR
Root["根项目"] --> SWC["swc_*"]
Root --> CL["cranelift-*"]
Root --> Serde["serde / serde_json"]
Root --> Obj["object"]
Root --> Clap["clap"]
Root --> CC["cc(build)"]
Root --> F1["特性: native-linker"]
Root --> F2["特性: coff"]
```

图表来源
- [Cargo.toml:22-56](file://Cargo.toml#L22-L56)

章节来源
- [Cargo.toml:22-56](file://Cargo.toml#L22-L56)

## 性能考虑
- 内存与时间统计
  - 项目编译器提供阶段计时与内存估算，便于定位性能瓶颈。
- 平台差异
  - Windows 使用 psapi 获取内存信息；其他平台通过 /proc 读取。
- 优化建议
  - 在 Release 配置下进行编译与链接，减少调试开销。
  - 合理拆分模块，避免单模块过大导致编译时间增长。

章节来源
- [src/project_compiler.rs:54-121](file://src/project_compiler.rs#L54-L121)

## 故障排除指南
- 无法找到 Rust 工具链
  - 确认已安装 rustup 并设置为默认工具链；更新到最新稳定版。
- Windows 链接失败
  - 确保已安装 MSVC 工具链（如 VS Build Tools），并在终端中使用正确的 shell（如 x64 Native Tools Command Prompt）。
- 未生成 .obj 或输出路径异常
  - 显式使用 -o 指定输出；若不指定，编译器会自动在输入文件同目录生成同名 .obj。
- 运行时报错找不到运行时
  - 确保 tsn-loader 与运行时动态库在同一目录或 PATH 可访问；Windows 下注意与编译器生成的目标架构一致。
- 依赖缺失或版本冲突
  - 清理缓存后重新拉取依赖；注意 serde 版本约束。
- 构建脚本报错
  - 确认 C 工具链可用；检查构建脚本是否能找到 runtime_nocrt.c/start_nocrt.c。
- 原生链接器问题
  - 确认输入对象文件格式正确；检查 DLL 导入配置；验证运行时对象文件存在。

章节来源
- [src/main.rs:10-13](file://src/main.rs#L10-L13)
- [src/main.rs:42-53](file://src/main.rs#L42-L53)
- [loader/Cargo.toml:21-22](file://loader/Cargo.toml#L21-L22)
- [Cargo.toml:26-28](file://Cargo.toml#L26-L28)
- [build.rs:1-33](file://build.rs#L1-L33)
- [src/bin/native_linker_main.rs:24-87](file://src/bin/native_linker_main.rs#L24-L87)

## 结论
通过本指南，你可以完成 ts-native 的安装与基础使用，掌握单文件与多模块项目的编译与运行方法。随着项目规模增大，建议结合项目编译器的依赖图与性能统计信息，持续优化模块划分与编译配置。

## 附录
- 更多文档入口
  - 参考文档索引，了解架构设计、贡献指南等。

章节来源
- [docs/README.md:1-9](file://docs/README.md#L1-L9)