# 命令行工具

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

## 更新摘要
**变更内容**
- 增加了详细的 CLI 工具使用说明和实用技巧
- 补充了命令行示例和最佳实践
- 添加了故障排除指南和调试技巧
- 完善了性能监控和编译报告解读方法
- 增强了插件系统的使用指导

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

## 简介
本文件为 ts-native 的命令行工具提供全面的使用文档，涵盖以下内容：
- 主 CLI 工具（ts-native）与独立加载器（tsn-loader）的功能特性、命令参数与使用方法
- build 命令的选项、输入输出格式与配置参数
- native-linker 工具的使用场景与集成方法
- 实际命令行示例与使用案例
- 错误处理机制与调试选项
- 性能监控与编译报告的解读方法
- 实用技巧与最佳实践

## 项目结构
ts-native 项目采用多 crate 设计，包含核心编译器库、独立加载器程序以及可选的原生链接器功能：
- 核心库（tsnative）：提供编译器能力与 FFI 接口
- CLI 工具（ts-native）：面向用户的命令行入口
- 独立加载器（tsn-loader）：支持直接加载 COFF 对象或通过 DLL 编译执行
- 原生链接器（native-linker）：实验性功能，用于生成独立可执行文件
- 运行时库（runtime）：提供 C 语言实现的运行时函数

```mermaid
graph TB
subgraph "CLI 工具"
TSN["ts-native<br/>src/main.rs"]
NL["native-linker<br/>src/bin/native_linker_main.rs"]
end
subgraph "加载器"
LOADER["tsn-loader<br/>loader/src/main.rs"]
end
subgraph "核心库"
LIB["tsnative<br/>src/lib.rs"]
CODEGEN["代码生成<br/>src/codegen.rs"]
COFF["COFF 解析<br/>src/coff.rs"]
SWC["SWC 转换<br/>src/swc_transform.rs"]
PROJECT["项目管理<br/>src/project.rs"]
PCOMP["项目编译器<br/>src/project_compiler.rs"]
STANDALONE["独立生成器<br/>src/standalone_gen.rs"]
FFI["FFI 接口<br/>src/tsn_ffi.rs"]
NLINKER["原生链接器<br/>src/native_linker.rs"]
end
TSN --> LIB
NL --> NLINKER
LOADER --> FFI
LIB --> CODEGEN
LIB --> COFF
LIB --> SWC
LIB --> PROJECT
LIB --> PCOMP
LIB --> STANDALONE
LIB --> NLINKER
```

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

**章节来源**
- [README.md:39-62](file://README.md#L39-L62)
- [Cargo.toml:8-21](file://Cargo.toml#L8-L21)

## 核心组件
本节概述三个主要命令行工具及其职责：

### ts-native CLI 工具
- 功能：将单个 TypeScript 文件编译为 COFF 对象文件，并提供后续执行指导
- 主要行为：
  - 解析命令行参数（输入文件、输出文件）
  - 使用 SWC 解析 TypeScript 源码
  - 通过 CodeGen 生成 COFF 二进制
  - 写入 .obj 文件并打印执行建议

**章节来源**
- [src/main.rs:7-78](file://src/main.rs#L7-L78)

### tsn-loader 独立加载器
- 功能：支持两种执行模式
  - 直接加载 COFF 对象文件（传统模式）
  - 通过 DLL 编译 TypeScript 并执行（DLL 模式）
- 支持的选项：
  - -v/--verbose：详细输出（包含 IR）
  - -q/--quiet：仅输出错误
  - --log-level：设置日志级别（error|warn|info|debug|trace）
  - -c/--compile：强制编译模式（.ts 文件自动启用）
  - -s/--save：保存编译后的 COFF 对象
  - -p/--plugins：加载插件 DLL（逗号分隔）
  - -d/--plugins-dir：从目录加载所有 .dll 插件
  - --download-plugins：下载缺失的插件
  - -h/--help：显示帮助

**章节来源**
- [loader/src/main.rs:17-40](file://loader/src/main.rs#L17-L40)
- [loader/src/main.rs:66-99](file://loader/src/main.rs#L66-L99)

### native-linker 原生链接器
- 功能：不依赖外部链接器，直接生成 Windows PE 可执行文件
- 支持的参数：
  - -o/--output：指定输出可执行文件
- 内置配置：
  - 入口点：_start
  - 子系统：Console
  - 堆栈与堆大小配置
  - 自动注入运行时对象文件
  - 导入表：kernel32.dll、ntdll.dll、shell32.dll

**章节来源**
- [src/bin/native_linker_main.rs:24-87](file://src/bin/native_linker_main.rs#L24-L87)
- [src/bin/native_linker_main.rs:89-162](file://src/bin/native_linker_main.rs#L89-L162)

## 架构概览
ts-native 的编译与执行流程如下：

```mermaid
flowchart TD
A["TypeScript 源码"] --> B["SWC 解析<br/>swc_transform.rs"]
B --> C["HIR 生成<br/>codegen.rs"]
C --> D["Cranelift 代码生成<br/>codegen.rs"]
D --> E["COFF 目标文件<br/>coff.rs"]
E --> F["独立可执行文件<br/>standalone_gen.rs"]
E --> G["PE 可执行文件<br/>native_linker.rs"]
E --> H["tsn-loader 执行<br/>loader/src/main.rs"]
```

**图表来源**
- [ARCHITECTURE.md:5-17](file://ARCHITECTURE.md#L5-L17)
- [src/swc_transform.rs:10-34](file://src/swc_transform.rs#L10-L34)
- [src/codegen.rs:19-48](file://src/codegen.rs#L19-L48)
- [src/coff.rs:55-70](file://src/coff.rs#L55-L70)
- [src/standalone_gen.rs:36-95](file://src/standalone_gen.rs#L36-L95)
- [src/native_linker.rs:18-35](file://src/native_linker.rs#L18-L35)
- [loader/src/main.rs:42-127](file://loader/src/main.rs#L42-L127)

## 详细组件分析

### ts-native CLI 工具详解
- 参数解析：
  - 输入文件：必须提供（无输入时打印用法并退出）
  - 输出文件：支持 -o/--output 指定；若省略则基于输入文件推导 .obj 名称
- 编译流程：
  1) 读取源文件内容
  2) 使用 SWC 解析为 HIR
  3) 通过 CodeGen 生成 COFF 二进制
  4) 写入 .obj 文件并打印执行建议（提示使用 tsn-loader）

```mermaid
sequenceDiagram
participant U as "用户"
participant CLI as "ts-native"
participant SWC as "SWC 解析"
participant CG as "CodeGen"
participant FS as "文件系统"
U->>CLI : 运行 ts-native <input.ts> [-o <output>]
CLI->>CLI : 解析参数
CLI->>FS : 读取输入文件
CLI->>SWC : 解析 TypeScript
SWC-->>CLI : HIR
CLI->>CG : 生成 COFF
CG-->>CLI : 二进制数据
CLI->>FS : 写入 .obj 文件
CLI-->>U : 打印执行建议
```

**图表来源**
- [src/main.rs:7-78](file://src/main.rs#L7-L78)
- [src/swc_transform.rs:10-34](file://src/swc_transform.rs#L10-L34)
- [src/codegen.rs:19-48](file://src/codegen.rs#L19-L48)

**章节来源**
- [src/main.rs:10-53](file://src/main.rs#L10-L53)
- [src/main.rs:55-77](file://src/main.rs#L55-L77)

### tsn-loader 加载器详解
- 模式选择：
  - COFF 模式：直接加载 .obj 文件执行
  - DLL 模式：调用 ts-native.dll 编译并执行
- 插件系统：
  - 支持加载外部 DLL 插件，解析 js_* 符号
  - 插件目录扫描与自动下载功能
- 执行流程：
  1) 初始化日志系统（支持 RUST_LOG 环境变量）
  2) 解析命令行参数
  3) 根据模式选择执行路径
  4) 分配可执行内存，复制代码与数据
  5) 应用重定位，解析外部符号
  6) 调用入口点（main 函数）

```mermaid
sequenceDiagram
participant U as "用户"
participant LDR as "tsn-loader"
participant LOG as "日志系统"
participant PLG as "插件管理器"
participant EXE as "执行引擎"
U->>LDR : tsn-loader <file> [options]
LDR->>LOG : 初始化日志
LDR->>LDR : 解析参数
alt COFF 模式
LDR->>EXE : 加载并执行 COFF
else DLL 模式
LDR->>PLG : 加载插件
PLG-->>LDR : 插件符号表
LDR->>EXE : 分配内存并应用重定位
end
EXE-->>LDR : 返回执行结果
LDR-->>U : 输出结果
```

**图表来源**
- [loader/src/main.rs:42-127](file://loader/src/main.rs#L42-L127)
- [loader/src/main.rs:130-200](file://loader/src/main.rs#L130-L200)
- [loader/src/main.rs:270-333](file://loader/src/main.rs#L270-L333)
- [loader/src/main.rs:537-743](file://loader/src/main.rs#L537-L743)

**章节来源**
- [loader/src/main.rs:106-127](file://loader/src/main.rs#L106-L127)
- [loader/src/main.rs:270-333](file://loader/src/main.rs#L270-L333)
- [loader/src/main.rs:537-743](file://loader/src/main.rs#L537-L743)

### native-linker 原生链接器详解
- 功能特性：
  - 解析多个 COFF 对象文件
  - 合并节区（.text, .data, .rdata, .bss）
  - 构建全局符号表，解析外部符号引用
  - 处理 x64 重定位（REL32, ADDR32NB, ADDR64）
  - 生成导入表（kernel32.dll 等系统 DLL）
- 配置参数：
  - 入口点：_start
  - 子系统：Console
  - 堆栈与堆大小：预留/提交参数
  - 自动注入运行时：启用时自动加载 start_nocrt.o 与 runtime_nocrt.o
  - 导入函数：预定义系统 API 列表

```mermaid
flowchart TD
A["输入对象文件"] --> B["解析 COFF 头与节区"]
B --> C["合并节区数据"]
C --> D["构建符号表"]
D --> E["解析外部符号"]
E --> F["应用重定位"]
F --> G["生成导入表"]
G --> H["输出 PE 可执行文件"]
```

**图表来源**
- [src/bin/native_linker_main.rs:89-162](file://src/bin/native_linker_main.rs#L89-L162)
- [src/native_linker.rs:18-35](file://src/native_linker.rs#L18-L35)
- [src/native_linker.rs:132-145](file://src/native_linker.rs#L132-L145)

**章节来源**
- [src/bin/native_linker_main.rs:24-87](file://src/bin/native_linker_main.rs#L24-L87)
- [src/native_linker.rs:163-200](file://src/native_linker.rs#L163-L200)

## 依赖分析
命令行工具之间的依赖关系如下：

```mermaid
graph LR
CLI["ts-native<br/>src/main.rs"] --> LIB["tsnative<br/>src/lib.rs"]
LINKER["native-linker<br/>src/bin/native_linker_main.rs"] --> NLLIB["native_linker<br/>src/native_linker.rs"]
LOADER["tsn-loader<br/>loader/src/main.rs"] --> FFI["tsn_ffi<br/>src/tsn_ffi.rs"]
LIB --> CODEGEN["codegen<br/>src/codegen.rs"]
LIB --> COFF["coff<br/>src/coff.rs"]
LIB --> SWC["swc_transform<br/>src/swc_transform.rs"]
LIB --> PROJECT["project<br/>src/project.rs"]
LIB --> PCOMP["project_compiler<br/>src/project_compiler.rs"]
LIB --> STANDALONE["standalone_gen<br/>src/standalone_gen.rs"]
```

**图表来源**
- [Cargo.toml:8-21](file://Cargo.toml#L8-L21)
- [src/lib.rs:1-17](file://src/lib.rs#L1-L17)
- [loader/Cargo.toml:13-15](file://loader/Cargo.toml#L13-L15)

**章节来源**
- [Cargo.toml:8-21](file://Cargo.toml#L8-L21)
- [loader/Cargo.toml:13-15](file://loader/Cargo.toml#L13-L15)

## 性能考虑
- 编译报告指标：
  - 总耗时：编译全流程时间
  - 内存使用：各阶段估算内存占用（Windows RSS）
  - 代码大小：代码段、数据段、只读数据段
  - 函数覆盖率：已编译函数数 / 总声明函数数
  - 阶段耗时：模块编译、可执行文件生成、报告生成
- 性能优化建议：
  - 使用 release 构建以获得最佳性能
  - 合理组织模块，减少不必要的依赖
  - 利用插件系统复用运行时功能
  - 在 DLL 模式下避免重复编译

**章节来源**
- [README.md:89-108](file://README.md#L89-L108)
- [src/project_compiler.rs:139-187](file://src/project_compiler.rs#L139-L187)
- [src/project_compiler.rs:27-52](file://src/project_compiler.rs#L27-L52)

## 故障排除指南
- 常见错误与解决方法：
  - 文件不存在：检查输入路径是否正确
  - 编译失败：查看编译报告中的错误信息与上下文
  - 符号未解析：确认插件 DLL 是否存在且包含所需符号
  - 内存分配失败：检查可用内存与虚拟内存设置
- 调试选项：
  - tsn-loader：使用 -v/--verbose 获取详细输出，--log-level 设置日志级别
  - 环境变量：RUST_LOG 控制日志级别，TSN_LOG 控制编译器日志
  - 阶段计时器：自动记录各阶段耗时，便于性能分析

**章节来源**
- [loader/src/main.rs:166-222](file://loader/src/main.rs#L166-L222)
- [loader/src/main.rs:387-420](file://loader/src/main.rs#L387-L420)

## 实用技巧与最佳实践

### ts-native CLI 工具使用技巧
- **批量编译优化**：使用 `-o` 参数明确指定输出文件，避免自动推导导致的命名冲突
- **路径处理**：确保输入文件路径正确，支持相对路径和绝对路径
- **输出验证**：编译完成后会提示使用 tsn-loader 执行，确保 .obj 文件存在

### tsn-loader 加载器使用技巧
- **日志级别控制**：
  - `-q/--quiet`：仅输出错误信息，适合生产环境
  - `--log-level debug`：调试模式，输出详细执行过程
  - `--log-level trace`：完整跟踪，包含 IR 输出
- **插件管理最佳实践**：
  - 使用 `-p/--plugins` 明确指定必需的插件 DLL
  - 通过 `-d/--plugins-dir` 批量加载插件目录
  - 启用 `--download-plugins` 自动下载缺失插件
- **执行模式选择**：
  - `.ts` 文件自动进入 DLL 模式
  - `.obj` 文件使用 COFF 模式直接执行
  - 强制模式：使用 `-c/--compile` 强制编译模式

### native-linker 链接器使用技巧
- **多文件链接**：支持同时链接多个 COFF 对象文件
- **运行时注入**：自动注入必要的运行时对象文件
- **导入表管理**：自动处理系统 DLL 导入函数

### 性能监控与调试
- **阶段计时器**：自动记录各阶段执行时间，便于性能分析
- **内存监控**：跟踪各阶段内存使用情况
- **符号解析**：显示符号表和重定位信息
- **代码预览**：输出执行代码的十六进制预览

### 插件系统高级用法
- **模块映射**：通过 `tsnp_module_map.txt` 配置模块到 DLL 的映射关系
- **自动发现**：支持从源文件目录自动发现插件
- **版本管理**：通过 `tsn-lock.json` 管理插件依赖版本
- **网络下载**：支持从配置的 URL 下载缺失的插件

**章节来源**
- [loader/src/main.rs:157-222](file://loader/src/main.rs#L157-L222)
- [loader/src/main.rs:1065-1260](file://loader/src/main.rs#L1065-L1260)

## 结论
ts-native 提供了从 TypeScript 到原生可执行文件的完整工具链，包含灵活的命令行工具与强大的加载器系统。通过合理使用这些工具，开发者可以高效地构建高性能的原生应用程序。掌握本文档中的实用技巧和最佳实践，将帮助您更好地利用 ts-native 的强大功能。

## 附录

### 命令行示例
- **基础编译**：
  - `ts-native main.ts -o main.obj`
- **生成独立可执行文件**：
  - `ts-native main.ts -o main.obj`
  - `native-linker main.obj -o main.exe`
- **直接执行 TypeScript**：
  - `tsn-loader main.ts -c`
- **使用插件执行**：
  - `tsn-loader main.ts -p runtime.dll -v`
- **详细调试模式**：
  - `tsn-loader main.ts --log-level debug`
- **静默模式**：
  - `tsn-loader main.ts -q`

**章节来源**
- [src/main.rs:10-13](file://src/main.rs#L10-L13)
- [src/bin/native_linker_main.rs:27-33](file://src/bin/native_linker_main.rs#L27-L33)
- [loader/src/main.rs:17-40](file://loader/src/main.rs#L17-L40)

### 配置参数参考
- **ts-native CLI**：
  - `-o/--output`：指定输出文件路径
- **tsn-loader**：
  - `-v/--verbose`：详细输出（包含 IR）
  - `-q/--quiet`：静默模式（仅错误）
  - `--log-level <level>`：设置日志级别（error|warn|info|debug|trace）
  - `-c/--compile`：强制编译模式
  - `-s/--save`：保存编译后的 COFF 对象
  - `-p/--plugins`：插件 DLL 列表（逗号分隔）
  - `-d/--plugins-dir`：从目录加载所有 .dll 插件
  - `--download-plugins`：自动下载缺失插件
- **native-linker**：
  - `-o/--output`：指定输出可执行文件

**章节来源**
- [src/main.rs:22-27](file://src/main.rs#L22-L27)
- [loader/src/main.rs:23-32](file://loader/src/main.rs#L23-L32)
- [src/bin/native_linker_main.rs:43-48](file://src/bin/native_linker_main.rs#L43-L48)

### 环境变量配置
- `RUST_LOG`：控制日志级别和输出
- `TSN_LOG`：控制编译器日志输出
- `PATH`：确保 ts-native 和 tsn-loader 可执行文件在系统路径中

### 常见问题解答
- **如何验证编译结果**：检查输出的 .obj 文件是否存在和大小
- **如何查看详细错误信息**：使用 `-v` 或 `--log-level debug` 选项
- **如何优化执行性能**：使用 release 构建和合适的日志级别
- **如何管理插件依赖**：使用 `tsn-lock.json` 和 `tsnp_module_map.txt`