compiler/CLANG_TEST_GUIDE.md

Windows Clang 支持测试指南

✅ 已完成的修改

1. 代码实现

CompilerBase.php 修改

文件位置： D:\workspace\compiler\src\Php\CompilerBase.php

主要修改：

1. detectPlatform() 方法 (第 298-327 行)

   • 添加智能编译器检测
   • 优先级：PHPX_CC 环境变量 > Clang > MSVC
   • 显示当前使用的编译器信息

2. isClangAvailable() 方法 (第 329-370 行)

   • 检测 PATH 中的 clang++
   • 自动搜索 Visual Studio LLVM 路径
   • 支持 VS 2019 和 VS 2022 所有版本
   • 找到后自动添加到 PATH

3. addCompilationOption() 方法 (第 2410-2425 行)

   • 根据编译器类型分发到不同的处理方法
   • 支持 MSVC 和 Clang

4. addWindowsClangCompilationOption() 方法 (第 2543-2647 行)

   • 新增方法，处理 Windows Clang 编译选项
   • 使用 GCC 风格的编译选项（-std, -O, -Wall）
   • 链接时使用 MSVC 链接器选项
   • 完整的 Sanitizer 支持

---

🧪 测试步骤

前置条件

您需要安装以下之一：

选项 1：Visual Studio LLVM 组件（推荐）

1. 打开 Visual Studio Installer
2. 点击 修改 您的 Visual Studio 安装
3. 切换到 单个组件 标签
4. 搜索并勾选：
   • ✅ Clang compiler for Windows
   • ✅ C++ Clang tools for Windows
5. 点击 修改 开始安装

选项 2：独立 LLVM 安装

1. 访问 https://releases.llvm.org/download.html
2. 下载 LLVM-{version}-win64.exe
3. 运行安装程序
4. 重要： 勾选 "Add LLVM to the system PATH"

---

测试 1：检查 Clang 安装

运行检查脚本：

cd D:\workspace\compiler
check-clang.bat

或使用 PowerShell：

cd D:\workspace\compiler
.\check-clang.ps1

预期输出：

如果 Clang 已安装：

=== Checking Clang Installation ===

1. Checking PATH for clang++:
Found in PATH
clang version 17.0.6

2. Checking Visual Studio paths:
Found: VS 2022 Community
clang version 17.0.6

=== Check Complete ===

如果未安装：

Not found in PATH
Not found in Visual Studio directories

To install LLVM for Visual Studio:
1. Open Visual Studio Installer
2. Modify your installation
...

---

测试 2：编译器检测

运行 PHP 测试脚本：

php test-compiler-detection.php

预期输出：

如果使用 Clang：

=== Testing Compiler Detection ===

Platform Detection:
  isWindows: true
  cppCompiler: clang++
  cxxStd: c++17

Clang Detection Test:
  isClangAvailable: true

✓ Clang is available and will be used by default

=== Test Complete ===

如果使用 MSVC：

Platform Detection:
  isWindows: true
  cppCompiler: cl
  cxxStd: c++17

Clang Detection Test:
  isClangAvailable: false

✗ Clang not found, will use MSVC

=== Test Complete ===

---

测试 3：实际编译测试

测试 3a：使用 Clang 编译

# 确保 Clang 可用
php test-compiler-detection.php

# 编译测试文件
php bin/compiler.php test-clang-simple.php

# 运行生成的可执行文件
test-clang-simple.exe

预期输出：

Hello from PHPX!
Testing Clang compiler support...
PHP Version: 8.x.x
Sum of [1,2,3,4,5] = 15
Test completed successfully!

---

测试 3b：强制使用 MSVC

# 设置环境变量强制使用 MSVC
set PHPX_CC=cl

# 编译
php bin/compiler.php test-clang-simple.php

# 运行
test-clang-simple.exe

---

测试 3c：强制使用 Clang

# 设置环境变量强制使用 Clang
set PHPX_CC=clang++

# 编译
php bin/compiler.php test-clang-simple.php

# 运行
test-clang-simple.exe

---

测试 4：Sanitizer 测试（仅 Clang）

# 使用 AddressSanitizer 编译
php bin/compiler.php test-clang-simple.php --sanitize=address

# 运行（如果有内存错误会报告）
test-clang-simple.exe

---

📊 验证清单

完成后，请确认以下功能：

• Clang 正确安装在系统中
• isClangAvailable() 能检测到 Clang
• 默认情况下优先使用 Clang（如果可用）
• 可以通过 PHPX_CC 环境变量切换编译器
• Clang 编译的程序可以正常运行
• MSVC 仍然可以正常工作
• Sanitizer 选项在 Clang 下工作
• 编译时显示正确的编译器信息

---

🐛 故障排除

问题 1：Clang 未被检测到

症状： isClangAvailable() 返回 false

解决：

1. 确认 Clang 已安装
2. 检查 PATH 环境变量
3. 重启命令行窗口
4. 手动添加 Clang 到 PATH：

   set PATH=C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Tools\Llvm\x64\bin;%PATH%
   

---

问题 2：编译失败

症状： 编译时出现错误

检查：

1. 确认使用的是正确的编译器
2. 检查 Visual Studio Developer Command Prompt
3. 查看详细的错误信息

尝试：

# 清除缓存后重新编译
del /s /q *.o 2>nul
del /s /q *.obj 2>nul
php bin/compiler.php test.php

---

问题 3：链接错误

症状： 编译成功但链接失败

原因： Clang on Windows 需要 MSVC 的链接器

解决：

1. 确保 Visual Studio Build Tools 已安装
2. 使用 Developer Command Prompt
3. 检查 Windows SDK 是否安装

---

📝 下一步

如果测试成功，您可以：

1. ✅ 开始在项目中使用 Clang
2. ✅ 利用 Clang 的 Sanitizers 进行调试
3. ✅ 享受更好的错误信息和诊断
4. ✅ 为跨平台开发做准备

---

🔗 相关文档

• WINDOWS_CLANG_GUIDE.md - 完整的使用指南
• YAML_CONFIG_NAMING_CONVENTION.md - YAML 配置规范
• CONFIG_PRIORITY_RULES.md - 配置优先级规则

---

💡 提示

快速切换编译器：

# 使用 Clang
set PHPX_CC=clang++
php bin/compiler.php app.php

# 使用 MSVC
set PHPX_CC=cl
php bin/compiler.php app.php

# 自动选择（默认）
set PHPX_CC=
php bin/compiler.php app.php

永久设置（系统环境变量）：

# 设置为 Clang
setx PHPX_CC "clang++"

# 设置为 MSVC
setx PHPX_CC "cl"

# 删除设置（自动选择）
setx PHPX_CC ""

---

祝测试顺利！如有问题，请查看详细文档或报告 bug。