# Windows Clang 工具链使用指南

## 📋 概述

PHPX 编译器现在支持在 Windows 下使用 Clang 工具链进行编译和调试，同时保留对 MSVC 的支持。

---

## 🎯 编译器选择优先级

Windows 下的编译器选择遵循以下优先级（从高到低）：

1. **环境变量 `PHPX_CC`** - 用户手动指定
2. **Clang (`clang++`)** - 如果可用，优先使用
3. **MSVC (`cl`)** - 默认 fallback

---

## 🚀 快速开始

### 方法 1：自动检测（推荐）

只需安装 LLVM/Clang，编译器会自动检测并使用：

```powershell
# 安装 LLVM for Windows
# 从 https://releases.llvm.org/ 下载并安装

# 确保 clang++ 在 PATH 中
clang++ --version

# 编译项目（自动使用 Clang）
php bin/compiler.php project.yml
```

输出：
```
Using Clang compiler (clang++)
...
```

---

### 方法 2：强制使用 MSVC

如果需要切换回 MSVC：

```powershell
# 设置环境变量
$env:PHPX_CC = "cl"

# 编译项目
php bin/compiler.php project.yml
```

输出：
```
Using compiler from PHPX_CC: cl
Using MSVC compiler (cl)
...
```

---

### 方法 3：强制使用 Clang

即使有 MSVC，也可以强制使用 Clang：

```powershell
# 设置环境变量
$env:PHPX_CC = "clang++"

# 编译项目
php bin/compiler.php project.yml
```

输出：
```
Using compiler from PHPX_CC: clang++
...
```

---

## 🔧 安装 LLVM/Clang

### 步骤 1：下载 LLVM

访问 [LLVM Releases](https://releases.llvm.org/download.html) 或 [GitHub Releases](https://github.com/llvm/llvm-project/releases)

推荐下载：
- **LLVM-{version}-win64.exe** (Windows 64-bit)

---

### 步骤 2：安装

运行安装程序，建议安装到：
```
C:\Program Files\LLVM
```

**重要：** 勾选 "Add LLVM to the system PATH for all users"

---

### 步骤 3：验证安装

```powershell
# 检查版本
clang++ --version

# 应该看到类似输出
clang version 17.0.6
Target: x86_64-pc-windows-msvc
Thread model: posix
```

---

### 步骤 4：配置 Visual Studio（可选但推荐）

Clang on Windows 需要 Visual Studio 的链接器和库：

```powershell
# 启动 Developer PowerShell
Import-Module "C:\Program Files\Microsoft Visual Studio\2022\Community\Common7\Tools\Microsoft.VisualStudio.DevShell.dll"
Enter-VsDevShell -VsInstallPath "C:\Program Files\Microsoft Visual Studio\2022\Community"
```

---

## 💡 编译器对比

### MSVC vs Clang on Windows

| 特性 | MSVC (`cl`) | Clang (`clang++`) |
|------|------------|------------------|
| **编译器** | Microsoft | LLVM |
| **语法** | MSVC 特有 | GCC 兼容 |
| **警告格式** | C4xxx | 类似 GCC |
| **调试器** | Visual Studio | VS / LLDB / GDB |
| **Sanitizer** | AddressSanitizer | 完整的 Sanitizers |
| **优化** | 优秀 | 优秀 |
| **跨平台** | ❌ Windows only | ✅ 跨平台 |
| **学习曲线** | 中等 | 低（GCC 熟悉者） |
| **链接器** | link.exe | lld-link (推荐) 或 link.exe |

---

## 🔗 链接器选择

Clang on Windows 支持两种链接器：

### 1. lld-link（推荐）

**优势：**
- ✅ **速度快** - 比 link.exe 快 2-5 倍
- ✅ **并行链接** - 更好的多核利用
- ✅ **Clang 原生** - 与 Clang 集成更好
- ✅ **自动检测** - 如果可用会自动使用

**要求：**
- 需要安装 LLVM 组件（包含在 Visual Studio Clang 工具中）

---

### 2. link.exe（fallback）

**优势：**
- ✅ **稳定性好** - 与 Windows SDK 和 CRT 完全兼容
- ✅ **无需额外配置** - Visual Studio 自带

**劣势：**
- ❌ **速度较慢** - 相比 lld-link
- ❌ **并行链接支持弱**

---

### 自动选择逻辑

```
启动编译
  ↓
检测 Clang
  ├─ 1. 检查 PATH 中的 clang++
  │   └─ 找到 → 使用并检测 lld-link
  ├─ 2. 检查 LLVM_HOME 环境变量
  │   └─ 设置且有效 → 使用并检测 lld-link
  └─ 3. 都未找到 → 使用 MSVC
  ↓
检测 lld-link
  ├─ 1. 检查 PATH 中的 lld-link
  │   └─ 找到 → 使用 lld-link
  ├─ 2. 检查 LLVM_HOME/x64/bin/lld-link.exe
  │   └─ 存在 → 使用 lld-link
  └─ 3. 都未找到 → 使用 link.exe
```

编译时会显示：
```
Using Clang compiler (clang++)
Using lld-link linker from LLVM_HOME (faster than link.exe)
```

---

## 🛠️ 编译选项差异

### MSVC 选项

```powershell
cl /std:c++17 /O2 /Wall /MD ...
```

### Clang 选项（Windows）

```powershell
clang++ -std=c++17 -O2 -Wall -MD ...
```

**注意：** Clang on Windows 使用 GCC 风格的选项，但链接时使用 MSVC 的链接器。

---

## 🐛 调试支持

### 使用 Visual Studio 调试

两种编译器都生成 PDB 文件，可以用 Visual Studio 调试：

```powershell
# 启用调试信息
php bin/compiler.php app.php --debug-info

# 在 Visual Studio 中打开生成的 .exe
# 按 F5 开始调试
```

---

### 使用 LLDB 调试（Clang 专属优势）

Clang 原生支持 LLDB：

```powershell
# 编译带调试信息
php bin/compiler.php app.php --debug-info

# 使用 LLDB 调试
lldb app.exe

(lldb) breakpoint set --name main
(lldb) run
(lldb) next
(lldb) frame variable
```

---

## 🔍 Sanitizer 支持

### Clang 的优势

Clang 提供更完整的 Sanitizer 支持：

```powershell
# AddressSanitizer（内存错误检测）
php bin/compiler.php app.php --sanitize=address

# UndefinedBehaviorSanitizer（未定义行为检测）
php bin/compiler.php app.php --sanitize=undefined

# ThreadSanitizer（数据竞争检测）
php bin/compiler.php app.php --sanitize=thread

# 多个 Sanitizer 组合
php bin/compiler.php app.php --sanitize=address,undefined
```

### MSVC 的限制

MSVC 目前只支持 AddressSanitizer：

```powershell
# MSVC 仅支持 address
php bin/compiler.php app.php --sanitize=address
```

---

## ⚙️ 环境变量

### LLVM_HOME（推荐）

指定 LLVM/Clang 的安装路径：

```powershell
# 设置 LLVM_HOME（临时，当前会话）
$env:LLVM_HOME = "C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Tools\Llvm"

# 设置 LLVM_HOME（永久，用户级别）
[Environment]::SetEnvironmentVariable("LLVM_HOME", "C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Tools\Llvm", "User")

# 验证
php bin/compiler.php app.php
```

**优势：**
- ✅ 无需修改系统 PATH
- ✅ 灵活配置不同版本
- ✅ 避免硬编码路径

---

### PHPX_CC

指定使用的编译器：

```powershell
# 使用 Clang
$env:PHPX_CC = "clang++"

# 使用 MSVC
$env:PHPX_CC = "cl"

# 使用完整路径
$env:PHPX_CC = "C:\Program Files\LLVM\bin\clang++.exe"
```

---

### PATH

确保编译器在 PATH 中：

```powershell
# 添加 LLVM 到 PATH
$env:Path = "C:\Program Files\LLVM\bin;$env:Path"

# 添加 Visual Studio 工具到 PATH
Import-Module "C:\Program Files\Microsoft Visual Studio\2022\Community\Common7\Tools\Microsoft.VisualStudio.DevShell.dll"
Enter-VsDevShell -VsInstallPath "C:\Program Files\Microsoft Visual Studio\2022\Community"
```

---

## 📊 性能对比

### 编译速度

| 场景 | MSVC | Clang |
|------|------|-------|
| 首次编译 | 快 | 稍慢 |
| 增量编译 | 中等 | 快 |
| 并行编译 | 好 | 优秀 |

---

### 运行时性能

| 优化级别 | MSVC | Clang |
|---------|------|-------|
| -O0 | 相同 | 相同 |
| -O2 | 优秀 | 优秀 |
| -O3 | 优秀 | 略优 |

**注意：** 实际性能差异很小，取决于具体代码。

---

## 🎯 使用场景

### 推荐使用 Clang 的场景

1. ✅ **跨平台开发** - 代码需要在 Linux/macOS 上编译
2. ✅ **使用 Sanitizers** - 需要全面的内存/线程检测
3. ✅ **GCC 兼容性** - 熟悉 GCC 命令行
4. ✅ **开源项目** - 更多开发者可以使用
5. ✅ **学习和研究** - 更好的错误信息

---

### 推荐使用 MSVC 的场景

1. ✅ **纯 Windows 项目** - 不需要跨平台
2. ✅ **Visual Studio 集成** - 深度使用 VS 功能
3. ✅ **现有项目** - 已经使用 MSVC
4. ✅ **特定 MSVC 特性** - 需要 MSVC 独有功能

---

## 🐛 常见问题

### Q1: 如何确认当前使用的是哪个编译器？

A: 编译时会显示：

```
Using Clang compiler (clang++)
```

或

```
Using MSVC compiler (cl)
```

---

### Q2: Clang on Windows 需要什么依赖？

A: 
- LLVM/Clang 编译器
- Visual Studio Build Tools（提供链接器和库）
- Windows SDK

---

### Q3: 可以在 MSVC 和 Clang 之间切换吗？

A: 可以！使用 `PHPX_CC` 环境变量：

```powershell
# 切换到 Clang
$env:PHPX_CC = "clang++"
php bin/compiler.php app.php

# 切换到 MSVC
$env:PHPX_CC = "cl"
php bin/compiler.php app.php
```

---

### Q4: Clang 生成的代码可以和 MSVC 混用吗？

A: **不建议**。虽然都生成 COFF 格式的目标文件，但：
- ABI 可能不同
- CRT 库可能有冲突
- 调试信息格式不同

**建议：** 整个项目使用同一种编译器。

---

### Q5: 为什么 Clang 是首选？

A: 
1. **更好的错误信息** - 更清晰、更易读
2. **更快的编译速度** - 特别是增量编译
3. **完整的 Sanitizers** - AddressSanitizer, UBSan, TSan 等
4. **跨平台兼容** - 同样的代码可以在 Linux/macOS 编译
5. **活跃的社区** - LLVM 项目发展迅速

---

## 📝 配置示例

### project.yml - 使用 Clang

```yaml
name: my-app
build-mode: bin
cxx-std: c++17

# Clang 特定的编译选项
cxx-flags:
  - -Wall
  - -Wextra
  - -Wpedantic

sources:
  - src/*.php
```

编译：
```powershell
# 自动使用 Clang（如果已安装）
php bin/compiler.php project.yml

# 或强制使用
$env:PHPX_CC = "clang++"
php bin/compiler.php project.yml
```

---

### project.yml - 使用 MSVC

```yaml
name: my-app
build-mode: bin
cxx-std: c++17

# MSVC 特定的编译选项
cxx-flags:
  - /W4
  - /permissive-

sources:
  - src/*.php
```

编译：
```powershell
# 自动使用 MSVC（如果没有 Clang）
php bin/compiler.php project.yml

# 或强制使用
$env:PHPX_CC = "cl"
php bin/compiler.php project.yml
```

---

## 🔗 相关资源

- [LLVM Download Page](https://releases.llvm.org/download.html)
- [Clang Documentation](https://clang.llvm.org/docs/)
- [AddressSanitizer](https://clang.llvm.org/docs/AddressSanitizer.html)
- [Visual Studio Build Tools](https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2022)

---

## 🎉 总结

### 核心优势

1. ✅ **灵活性** - 可以在 MSVC 和 Clang 之间选择
2. ✅ **兼容性** - 保留 MSVC 支持，不影响现有项目
3. ✅ **现代化** - Clang 提供更好的工具和诊断
4. ✅ **跨平台** - 为未来的跨平台支持做准备
5. ✅ **易于切换** - 通过环境变量轻松切换

### 推荐实践

- 🆕 新项目 → 优先使用 Clang
- 🔄 现有项目 → 可以继续使用 MSVC
- 🧪 测试/调试 → 使用 Clang + Sanitizers
- 🚀 生产环境 → 根据团队熟悉度选择

希望这个指南能帮助您充分利用 Windows Clang 工具链！