|
|
# Win32 Hello World 示例
|
|
|
|
|
|
这个示例展示了如何使用 PHPX 编译器创建 Windows 程序，包括两种模式：
|
|
|
|
|
|
## 📁 示例文件
|
|
|
|
|
|
### 1. hello-console.php - 控制台版本（默认）
|
|
|
|
|
|
**特点：**
|
|
|
- ✅ 显示黑色控制台窗口
|
|
|
- ✅ 可以使用 `echo`、`print` 等控制台输出
|
|
|
- ✅ 可以显示消息框
|
|
|
- ✅ 适合命令行工具和调试
|
|
|
|
|
|
**编译命令：**
|
|
|
```bash
|
|
|
php ../../cli.php build --mode=bin hello-console.php
|
|
|
```
|
|
|
|
|
|
**运行效果：**
|
|
|
- 显示控制台窗口
|
|
|
- 输出文本信息到控制台
|
|
|
- 弹出消息框
|
|
|
|
|
|
---
|
|
|
|
|
|
### 2. hello-gui.php - GUI 版本（无控制台）
|
|
|
|
|
|
**特点：**
|
|
|
- ❌ 不显示控制台窗口
|
|
|
- ❌ `echo`、`print` 等控制台输出无效
|
|
|
- ✅ 只显示消息框等 GUI 元素
|
|
|
- ✅ 适合纯图形界面应用程序
|
|
|
|
|
|
**编译命令：**
|
|
|
```bash
|
|
|
php ../../cli.php build --mode=bin --no-console hello-gui.php
|
|
|
```
|
|
|
|
|
|
**运行效果：**
|
|
|
- 没有控制台窗口
|
|
|
- 直接弹出消息框
|
|
|
- 纯图形界面体验
|
|
|
|
|
|
---
|
|
|
|
|
|
### 3. debug-test.php - 调试测试程序
|
|
|
|
|
|
**特点：**
|
|
|
- ✅ 包含详细的日志记录
|
|
|
- ✅ 异常处理
|
|
|
- ✅ 逐步验证功能
|
|
|
- ✅ 用于排查 "Debug Assertion Failed" 问题
|
|
|
|
|
|
**编译命令：**
|
|
|
```bash
|
|
|
php ../../cli.php build --mode=bin --no-console debug-test.php
|
|
|
```
|
|
|
|
|
|
**使用方法：**
|
|
|
1. 编译并运行程序
|
|
|
2. 查看生成的 `debug-test.log` 文件
|
|
|
3. 根据日志定位问题
|
|
|
|
|
|
---
|
|
|
|
|
|
### 4. asan-test.php - AddressSanitizer 测试程序
|
|
|
|
|
|
**特点：**
|
|
|
- ✅ 演示 AddressSanitizer 的使用
|
|
|
- ✅ 包含各种内存操作测试
|
|
|
- ✅ 检测内存错误和泄漏
|
|
|
|
|
|
**编译命令：**
|
|
|
```bash
|
|
|
# Windows
|
|
|
php ../../cli.php build --mode=bin --sanitize=address --no-console asan-test.php
|
|
|
|
|
|
# Linux/macOS
|
|
|
php ../../cli.php build --mode=bin --sanitize=address,undefined asan-test.php
|
|
|
```
|
|
|
|
|
|
**使用方法：**
|
|
|
1. 编译带 sanitizer 的版本
|
|
|
2. 运行程序
|
|
|
3. 查看 `asan-test.log` 和控制台输出
|
|
|
4. 如果有内存错误，AddressSanitizer 会报告详细信息
|
|
|
|
|
|
---
|
|
|
|
|
|
### 5. debug-mode-test.php - 调试模式测试程序
|
|
|
|
|
|
**特点：**
|
|
|
- ✅ 演示 `--debug-info` 参数的使用
|
|
|
- ✅ 禁用优化，便于调试
|
|
|
- ✅ 生成完整的调试信息
|
|
|
- ✅ 支持 GDB、LLDB、Visual Studio 调试
|
|
|
|
|
|
**编译命令：**
|
|
|
```bash
|
|
|
# 启用调试模式（自动禁用优化 + 生成调试信息）
|
|
|
php ../../cli.php build --mode=bin --debug-info --no-console debug-mode-test.php
|
|
|
|
|
|
# 结合 AddressSanitizer
|
|
|
php ../../cli.php build --mode=bin --debug-info --sanitize=address --no-console debug-mode-test.php
|
|
|
```
|
|
|
|
|
|
**使用方法：**
|
|
|
1. 编译带调试信息的版本
|
|
|
2. 使用调试器加载程序
|
|
|
3. 设置断点、查看变量、单步执行
|
|
|
4. 查看 `debug-mode-test.log` 了解运行流程
|
|
|
|
|
|
---
|
|
|
|
|
|
## 🔧 核心功能
|
|
|
|
|
|
### C++ 函数导出
|
|
|
|
|
|
本示例展示了如何将 C++ 函数导出为 PHP 函数：
|
|
|
|
|
|
1. **函数命名规范**：必须以 `php_` 为前缀
|
|
|
2. **类型要求**：只能使用 PHPX 类型（Int, String, Bool 等）
|
|
|
3. **Stub 声明**：必须在 `.stub.php` 文件中声明函数签名
|
|
|
|
|
|
**示例：**
|
|
|
|
|
|
C++ 实现 (`cpp-src/winapi.cc`)：
|
|
|
```cpp
|
|
|
Int php_messagebox(Int hWnd, String text, String caption, Int uType) {
|
|
|
// 实现代码
|
|
|
}
|
|
|
```
|
|
|
|
|
|
PHP Stub 声明 (`cpp-src/winapi.stub.php`)：
|
|
|
```php
|
|
|
function messagebox(int $hWnd, string $text, string $caption, int $uType): int {}
|
|
|
```
|
|
|
|
|
|
### 中文支持
|
|
|
|
|
|
#### C++ 层（消息框）
|
|
|
|
|
|
使用 `MultiByteToWideChar` 将 UTF-8 转换为 UTF-16：
|
|
|
|
|
|
```cpp
|
|
|
// Convert UTF-8 to UTF-16 for Windows API
|
|
|
int wtext_len = MultiByteToWideChar(CP_UTF8, 0, text.data(), -1, NULL, 0);
|
|
|
wchar_t* wtext = new wchar_t[wtext_len];
|
|
|
MultiByteToWideChar(CP_UTF8, 0, text.data(), -1, wtext, wtext_len);
|
|
|
|
|
|
int result = MessageBoxW((HWND)hWnd, wtext, wcaption, (UINT)uType);
|
|
|
|
|
|
delete[] wtext;
|
|
|
delete[] wcaption;
|
|
|
```
|
|
|
|
|
|
#### PHP 层（时区设置）
|
|
|
|
|
|
```php
|
|
|
// Set timezone to China (UTC+8)
|
|
|
date_default_timezone_set('Asia/Shanghai');
|
|
|
```
|
|
|
|
|
|
---
|
|
|
|
|
|
## 📖 详细文档
|
|
|
|
|
|
- [WINDOWS_GUI_GUIDE.md](./WINDOWS_GUI_GUIDE.md) - Windows GUI 程序完整指南
|
|
|
- [CHINESE_SUPPORT_GUIDE.md](./CHINESE_SUPPORT_GUIDE.md) - 中文支持详细说明
|
|
|
- [CPP_FUNCTION_EXPORT_GUIDE.md](./CPP_FUNCTION_EXPORT_GUIDE.md) - C++ 函数导出规范
|
|
|
|
|
|
---
|
|
|
|
|
|
## 🚀 快速开始
|
|
|
|
|
|
### 编译控制台版本
|
|
|
|
|
|
```bash
|
|
|
# 进入示例目录
|
|
|
cd examples/win32-hello
|
|
|
|
|
|
# 编译
|
|
|
php ../../cli.php build --mode=bin hello-console.php
|
|
|
|
|
|
# 运行
|
|
|
.\hello-console.exe
|
|
|
```
|
|
|
|
|
|
### 编译 GUI 版本
|
|
|
|
|
|
```bash
|
|
|
# 进入示例目录
|
|
|
cd examples/win32-hello
|
|
|
|
|
|
# 编译（使用 --no-console 参数）
|
|
|
php ../../cli.php build --mode=bin --no-console hello-gui.php
|
|
|
|
|
|
# 运行
|
|
|
.\hello-gui.exe
|
|
|
```
|
|
|
|
|
|
---
|
|
|
|
|
|
## 💡 使用场景对比
|
|
|
|
|
|
| 场景 | 推荐模式 | 原因 |
|
|
|
|------|---------|------|
|
|
|
| 命令行工具 | 控制台模式 | 需要文本输出和输入 |
|
|
|
| 后台服务 | 控制台模式 | 需要日志输出 |
|
|
|
| 开发调试 | 控制台模式 | 便于查看调试信息 |
|
|
|
| 桌面应用 | GUI 模式 | 提供更好的用户体验 |
|
|
|
| 游戏 | GUI 模式 | 全屏或窗口化运行 |
|
|
|
| 工具软件 | GUI 模式 | 图形界面更友好 |
|
|
|
|
|
|
---
|
|
|
|
|
|
## ⚙️ 编译选项说明
|
|
|
|
|
|
### --no-console 参数
|
|
|
|
|
|
- **作用**：隐藏控制台窗口，创建纯 GUI 应用程序
|
|
|
- **适用平台**：仅 Windows
|
|
|
- **链接选项**：添加 `/SUBSYSTEM:WINDOWS`
|
|
|
- **注意事项**：
|
|
|
- 控制台输出函数（echo、print 等）将无效
|
|
|
- 需要使用消息框或其他 GUI 元素进行输出
|
|
|
- 调试时建议使用控制台模式
|
|
|
|
|
|
### 其他常用选项
|
|
|
|
|
|
```bash
|
|
|
# 优化级别
|
|
|
php cli.php build -O2 app.php
|
|
|
|
|
|
# 指定输出文件名
|
|
|
php cli.php build -o myapp app.php
|
|
|
|
|
|
# 启用调试信息
|
|
|
php cli.php build --debug-info app.php
|
|
|
|
|
|
# 并行编译
|
|
|
php cli.php build -j 8 app.php
|
|
|
```
|
|
|
|
|
|
---
|
|
|
|
|
|
## 🐛 常见问题
|
|
|
|
|
|
### Q: 为什么我的 echo 不显示？
|
|
|
|
|
|
A: 如果使用了 `--no-console` 参数，控制台被隐藏了。请改用消息框：
|
|
|
```php
|
|
|
messagebox(0, "你的消息", "标题", 0);
|
|
|
```
|
|
|
|
|
|
### Q: 如何调试没有控制台的程序？
|
|
|
|
|
|
A:
|
|
|
1. 使用消息框显示变量值
|
|
|
2. 写入日志文件：`file_put_contents('app.log', $msg, FILE_APPEND)`
|
|
|
3. 临时移除 `--no-console` 参数进行调试
|
|
|
4. 使用 [debug-test.php](./debug-test.php) 示例程序
|
|
|
5. 查看详细的 [DEBUG_GUIDE.md](./DEBUG_GUIDE.md)
|
|
|
|
|
|
### Q: 出现 "Debug Assertion Failed" 错误怎么办？
|
|
|
|
|
|
A: 这通常是由于 CRT 库冲突导致的。解决方法：
|
|
|
|
|
|
1. **重新编译**（编译器已自动添加 `/NODEFAULTLIB` 选项）
|
|
|
```bash
|
|
|
php ../../cli.php build --mode=bin --no-console your-app.php
|
|
|
```
|
|
|
|
|
|
2. **清理构建目录**
|
|
|
```bash
|
|
|
Remove-Item -Recurse -Force build/
|
|
|
php ../../cli.php build --mode=bin --no-console your-app.php
|
|
|
```
|
|
|
|
|
|
3. **使用调试测试程序**
|
|
|
```bash
|
|
|
php ../../cli.php build --mode=bin --no-console debug-test.php
|
|
|
.\debug-test.exe
|
|
|
# 查看 debug-test.log 文件
|
|
|
```
|
|
|
|
|
|
4. **查看详细调试指南**
|
|
|
- 参考 [DEBUG_GUIDE.md](./DEBUG_GUIDE.md)
|
|
|
- 使用 Visual Studio 调试器
|
|
|
- 使用 WinDbg
|
|
|
|
|
|
### Q: 中文显示乱码怎么办？
|
|
|
|
|
|
A: 确保：
|
|
|
1. 源文件使用 UTF-8 编码保存
|
|
|
2. C++ 中使用 `MultiByteToWideChar` 转换编码
|
|
|
3. 使用 `MessageBoxW` 而不是 `MessageBoxA`
|
|
|
4. 在 PHP 中设置正确的时区
|
|
|
|
|
|
### Q: 可以同时显示控制台和窗口吗？
|
|
|
|
|
|
A: 技术上可以，但不推荐。通常的做法是：
|
|
|
- 开发时使用控制台模式便于调试
|
|
|
- 发布时使用 GUI 模式提供更好的用户体验
|
|
|
|
|
|
---
|
|
|
|
|
|
## 📝 项目结构
|
|
|
|
|
|
```
|
|
|
win32-hello/
|
|
|
├── hello-console.php # 控制台版本示例
|
|
|
├── hello-gui.php # GUI 版本示例
|
|
|
├── debug-test.php # 调试测试程序（带日志）
|
|
|
├── debug-mode-test.php # 调试模式测试程序（--debug-info）
|
|
|
├── asan-test.php # AddressSanitizer 测试程序
|
|
|
├── main.php # 另一个示例文件
|
|
|
├── window.php # 窗口创建示例
|
|
|
├── cpp-src/
|
|
|
│ ├── winapi.cc # C++ 实现文件
|
|
|
│ └── winapi.stub.php # PHP Stub 声明
|
|
|
├── WINDOWS_GUI_GUIDE.md # GUI 程序指南
|
|
|
├── CHINESE_SUPPORT_GUIDE.md # 中文支持指南
|
|
|
├── CPP_FUNCTION_EXPORT_GUIDE.md # C++ 函数导出指南
|
|
|
├── DEBUG_GUIDE.md # 调试指南（重要！）
|
|
|
├── DEBUG_MODE_GUIDE.md # 调试模式使用指南
|
|
|
├── SANITIZER_GUIDE.md # AddressSanitizer 使用指南
|
|
|
├── MSVC_WARNINGS_SUPPRESSION.md # MSVC 警告屏蔽说明
|
|
|
└── README.md # 本文件
|
|
|
```
|
|
|
|
|
|
---
|
|
|
|
|
|
## 🔗 相关资源
|
|
|
|
|
|
- [PHPX 编译器文档](https://github.com/swoole/phpx)
|
|
|
- [Windows API 文档](https://docs.microsoft.com/en-us/windows/win32/api/)
|
|
|
- [MessageBoxW API](https://docs.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-messageboxw)
|
|
|
- [MultiByteToWideChar](https://docs.microsoft.com/en-us/windows/win32/api/stringapiset/nf-stringapiset-multibytetowidechar)
|
|
|
|
