# 使用文档

## 安装

### 下载预编译二进制文件

访问 [Releases](https://github.com/mioLanguage/mio/releases) 页面下载对应平台的二进制文件。

> [!NOTE]
> 如果遇到依赖库缺失问题，建议从源代码编译。

### 从源代码编译

**环境要求：** C++17 兼容编译器（GCC / Clang / MSVC），LLVM 22.1.x

```bash
g++ -std=c++17 -o mioc src/main.cpp -lLLVM
```

## 命令行选项

```bash
mioc <input.mio> [选项]
```

| 选项 | 说明 |
|------|------|
| `-o <file>` | 指定输出文件（.ll/.s/.o/.exe 或无扩展名）|
| `-S` | 生成汇编文件（.s）|
| `-c` | 仅编译为目标文件（.o），不链接 |
| `-I <path>` | 添加头文件搜索路径 |
| `-D <macro>` | 定义宏（如 `-D DEBUG` 或 `-D VERSION=2`）|
| `-l <lib>` | 链接库（如 `-lstdmio -lm`），默认链接 stdmio 和 m |
| `-static` | 静态链接（无 DLL 依赖）|
| `-O0` | 不优化 |
| `-O1` | 基本优化 |
| `-O2` | 标准优化（--release 默认）|
| `-O3` | 激进优化 |
| `--release` | 发布模式（启用 -O2 和缓存）|
| `-v` / `--version` | 显示版本信息 |

## 使用示例

### 编译并运行

```bash
# 编译（自动生成同名可执行文件）
mioc hello.mio

# 指定输出文件
mioc hello.mio -o hello.exe

# 运行
./hello.exe
```

### 生成中间产物

```bash
# 生成 LLVM IR
mioc hello.mio -o hello.ll

# 生成汇编
mioc hello.mio -S

# 生成目标文件（不链接）
mioc hello.mio -c
```

### 优化和发布

```bash
# 指定优化级别
mioc hello.mio -O2

# 发布模式（-O2 + 缓存）
mioc hello.mio --release

# 静态链接
mioc hello.mio -static
```

### 头文件和宏

```bash
# 添加头文件路径
mioc hello.mio -I ./include

# 定义宏
mioc hello.mio -D DEBUG

# 链接自定义库
mioc hello.mio -lmylib
```

## 输出格式检测

编译器根据输出文件扩展名自动判断输出格式：

| 扩展名 | 输出格式 |
|--------|----------|
| `.ll` | LLVM IR |
| `.s` | 汇编代码 |
| `.o` | 目标文件 |
| `.exe`（Windows）/ 无扩展名（Linux）| 可执行文件 |

## 缓存机制

使用 `--release` 模式时，编译器会缓存生成的 `.o` 文件。如果源文件未修改，将直接使用缓存的目标文件，跳过编译步骤。

```bash
# 首次编译（生成缓存）
mioc hello.mio --release

# 第二次编译（使用缓存，跳过编译）
mioc hello.mio --release
# 输出: [cache] using cached object file 'hello.o'
```

## 库链接

### 默认链接

默认情况下，编译器自动链接以下库：
- `stdmio` — mio 标准库
- `m` — 数学库

### 库搜索路径

编译器按以下顺序搜索库文件：

**Windows：**
1. `<compiler_dir>/lib/<name>.lib`
2. `<compiler_dir>/../lib/<name>.lib`
3. `<compiler_dir>/lib/windows/<name>.lib`
4. `<compiler_dir>/../lib/windows/<name>.lib`

**Linux/macOS：**
1. `<compiler_dir>/lib/lib<name>.a`
2. `<compiler_dir>/../lib/lib<name>.a`

### 标准库位置

编译器会自动搜索 `include/` 目录中的标准库文件（`stdio.mio`、`string.mio` 等）。

## 平台支持

| 平台 | 可执行格式 | 库格式 |
|------|-----------|--------|
| Windows | `.exe` | `.lib` |
| Linux | 无扩展名 | `.a` |
| macOS | 无扩展名 | `.a` |

## Hello World

```mio
import stdio;

i32 main() {
    printf("Hello, mio!\n");
    return 0;
}
```

编译并运行：

```bash
mioc hello.mio
./hello.exe
# 输出: Hello, mio!
```