125 lines
3.4 KiB
Markdown
125 lines
3.4 KiB
Markdown
# Emscripten 工具使用指南
|
|
|
|
本目录包含用于安装和使用 Emscripten 的工具脚本，用于将 Rust 编译的 WebAssembly 转换为 asm.js。
|
|
|
|
## 文件说明
|
|
|
|
- `install.bat` - Emscripten 3.1.41 安装脚本
|
|
- `gen-asm.bat` - WASM 转 asm.js 转换脚本
|
|
- `setup-env.bat` - 环境变量设置脚本（安装后自动生成）
|
|
- `.gitignore` - Git 忽略文件配置
|
|
|
|
## 使用步骤
|
|
|
|
### 1. 安装 Emscripten
|
|
|
|
```batch
|
|
# 运行安装脚本
|
|
tools\emscripten\install.bat
|
|
```
|
|
|
|
**前置要求:**
|
|
- Git (用于下载 emsdk)
|
|
- Python 3.x (Emscripten 运行需要)
|
|
|
|
安装过程会:
|
|
- 下载 Emscripten SDK
|
|
- 安装指定版本 (3.1.41)
|
|
- 验证安装
|
|
- 创建环境设置脚本
|
|
|
|
### 2. 设置环境变量
|
|
|
|
每次使用前需要设置环境变量：
|
|
|
|
```batch
|
|
# 方法1: 使用自动生成的脚本
|
|
tools\emscripten\setup-env.bat
|
|
|
|
# 方法2: 手动运行
|
|
tools\emscripten\emsdk\emsdk_env.bat
|
|
```
|
|
|
|
### 3. 转换 WASM 为 asm.js
|
|
|
|
```batch
|
|
# 语法
|
|
tools\emscripten\gen-asm.bat <wasm文件路径> <输出路径>
|
|
|
|
# 示例1: 转换 pinball-physics
|
|
tools\emscripten\gen-asm.bat pinball-physics\target\wasm32-unknown-unknown\release\pinball_physics.wasm client-cocos\assets\wasm\pinball-asm.js
|
|
|
|
# 示例2: 转换 server-rust
|
|
tools\emscripten\gen-asm.bat server-rust\target\wasm32-unknown-unknown\release\server_rust.wasm client-cocos\assets\wasm\server-asm.js
|
|
```
|
|
|
|
## 工作流程示例
|
|
|
|
```batch
|
|
# 1. 首次安装
|
|
tools\emscripten\install.bat
|
|
|
|
# 2. 编译 Rust 项目为 WASM
|
|
cd pinball-physics
|
|
cargo build --target wasm32-unknown-unknown --release
|
|
cd ..
|
|
|
|
# 3. 设置 Emscripten 环境
|
|
tools\emscripten\setup-env.bat
|
|
|
|
# 4. 转换为 asm.js
|
|
tools\emscripten\gen-asm.bat pinball-physics\target\wasm32-unknown-unknown\release\pinball_physics.wasm client-cocos\assets\wasm\pinball-asm.js
|
|
```
|
|
|
|
## 输出文件使用
|
|
|
|
生成的 asm.js 文件可以在浏览器中使用：
|
|
|
|
```html
|
|
<!DOCTYPE html>
|
|
<html>
|
|
<head>
|
|
<script src="pinball-asm.js"></script>
|
|
</head>
|
|
<body>
|
|
<script>
|
|
PinballModule().then(function(Module) {
|
|
// 使用 Module.ccall 调用 Rust 导出的函数
|
|
var result = Module.ccall('exported_function', 'number', ['number'], [42]);
|
|
console.log('Result:', result);
|
|
});
|
|
</script>
|
|
</body>
|
|
</html>
|
|
```
|
|
|
|
## 注意事项
|
|
|
|
1. **版本固定**: 当前使用 Emscripten 3.1.41 版本，确保兼容性
|
|
2. **环境变量**: 每次新开命令行窗口都需要重新设置环境变量
|
|
3. **文件大小**: asm.js 文件通常比 WebAssembly 大 3-5 倍
|
|
4. **性能差异**: asm.js 性能不如原生 WebAssembly
|
|
5. **浏览器兼容**: asm.js 主要用于兼容不支持 WebAssembly 的老旧浏览器
|
|
|
|
## 故障排除
|
|
|
|
### 安装问题
|
|
- 确保网络连接正常，能够访问 GitHub
|
|
- 检查 Git 和 Python 是否正确安装
|
|
- 如果下载失败，可以删除 `emsdk` 目录重新运行
|
|
|
|
### 转换问题
|
|
- 确保 WASM 文件存在且格式正确
|
|
- 检查 Emscripten 环境变量是否设置
|
|
- 验证输出目录权限
|
|
|
|
### 运行时问题
|
|
- 确保在支持 asm.js 的浏览器中测试
|
|
- 检查 JavaScript 控制台的错误信息
|
|
- 验证导出函数名称是否正确
|
|
|
|
## 相关链接
|
|
|
|
- [Emscripten 官方文档](https://emscripten.org/docs/)
|
|
- [asm.js 规范](http://asmjs.org/)
|
|
- [Rust WebAssembly 指南](https://rustwasm.github.io/docs/book/) |