# 多平台编译指南

## ✨ 使用 cargo-zigbuild 一键编译所有平台

本项目使用 `cargo-zigbuild` 实现本地多平台编译，无需容器或复杂配置！

**支持平台**：
- ✅ macOS Intel (x86_64)
- ✅ macOS Apple Silicon (ARM64)
- ✅ Linux x86_64
- ✅ Linux ARM64
- ✅ Windows x86_64

---

## 环境准备（首次使用）

```bash
# 1. 安装 cargo-zigbuild（交叉编译工具）
cargo install cargo-zigbuild

# 2. 安装 MinGW（Windows 编译需要）
brew install mingw-w64

# 3. 添加 Rust 标准库
rustup target add x86_64-unknown-linux-gnu \
                  aarch64-unknown-linux-gnu \
                  x86_64-pc-windows-gnu
```

---

## 快速开始

### 编译所有平台（推荐）

```bash
cd scripts
./install.sh
```

**输出**：
- 所有平台的二进制文件：`../target/releases/`
- 当前平台同时安装到：`~/data/bin`

### 只编译当前平台

```bash
cd scripts
BUILD_MODE=local ./install.sh
```

---

## 环境变量

| 变量 | 可选值 | 默认值 | 说明 |
|------|--------|--------|------|
| `BUILD_MODE` | `local` / `all` | `all` | 编译模式 |
| `BUILD_CMD` | `auto` / `cargo` / `zigbuild` | `auto` | 编译工具（auto=自动选择） |
| `DEBUG` | `true` / `false` | `false` | 调试模式 |

**示例**：
```bash
# 强制使用 zigbuild 编译所有平台
BUILD_CMD=zigbuild ./install.sh

# 调试模式
DEBUG=true ./install.sh
```

---

## 编译产物结构

```
target/releases/
├── x86_64-apple-darwin/          # macOS Intel
│   ├── git_commit_generator
│   └── another_tool
├── aarch64-apple-darwin/         # macOS Apple Silicon
│   ├── git_commit_generator
│   └── another_tool
├── x86_64-unknown-linux-gnu/     # Linux x86_64
│   ├── git_commit_generator
│   └── another_tool
├── aarch64-unknown-linux-gnu/    # Linux ARM64
│   ├── git_commit_generator
│   └── another_tool
└── x86_64-pc-windows-gnu/        # Windows x86_64
    ├── git_commit_generator.exe
    └── another_tool.exe
```

---

## 工作原理

脚本会自动选择合适的编译工具：

- **macOS 平台**：使用 `cargo`（原生编译）
- **Linux/Windows 平台**：使用 `cargo-zigbuild`（交叉编译）

`cargo-zigbuild` 使用 Zig 作为链接器，可以在 macOS 上直接交叉编译到 Linux 和 Windows，无需复杂的工具链配置。

---

## 常见问题

### 1. cargo-zigbuild 编译失败

**问题**：
```
error: could not compile `portable`
```

**解决**：
确保已安装 mingw-w64（Windows 编译需要）：
```bash
brew install mingw-w64
```

### 2. 缺少 Rust 标准库

**问题**：
```
error: can't find crate for `core`
```

**解决**：
```bash
rustup target add x86_64-unknown-linux-gnu \
                  aarch64-unknown-linux-gnu \
                  x86_64-pc-windows-gnu
```

## 相关资源

- [cargo-zigbuild GitHub](https://github.com/rust-cross/cargo-zigbuild)
- [Zig 官网](https://ziglang.org/)
- [Rust 交叉编译指南](https://rust-lang.github.io/rustup/cross-compilation.html)
