第51章 Emscripten/WASM

课程目录第51章 Emscripten/WASM

第51章：Emscripten/WASM：使用CMake编译WebAssembly

说实话，我第一次接触WebAssembly（WASM）时，心里是有点抵触的。你想啊，一个C++程序员，写了十几年代码，突然要把代码跑到浏览器里——这听着就像让鱼去爬树。但后来项目需要，我硬着头皮试了一把，结果发现，嗯，真香。

这一章，我们就聊聊怎么用CMake配合Emscripten，把C++代码编译成WebAssembly。说白了，就是让你的C++代码能在浏览器里跑起来。

什么是Emscripten？

Emscripten是一个编译器工具链，它能把C/C++代码编译成WebAssembly。你可以把它想象成一个翻译官——把C++的"方言"翻译成浏览器能听懂的"普通话"。

我个人习惯把Emscripten看作是一个特殊的交叉编译器。就像你用ARM交叉编译器编译嵌入式代码一样，Emscripten就是针对WebAssembly这个"平台"的编译器。

环境搭建

在开始之前，你得先装好Emscripten。我建议直接用官方的emsdk来安装：

# 克隆emsdk
git clone https://github.com/emscripten-core/emsdk.git
cd emsdk

# 安装最新版本
./emsdk install latest
./emsdk activate latest

# 设置环境变量
source ./emsdk_env.sh

装完之后，验证一下：

emcc --version
emcmake --version

看到版本号，就说明装好了。我在项目中遇到过一个问题——如果你同时装了多个版本的Emscripten，记得每次激活后都要重新source一下环境变量，不然会踩坑。

第一个WASM项目：Hello World

我们先从一个最简单的例子开始。写一个C++函数，然后在浏览器里调用它。

先看C++代码：

// hello.cpp
#include <emscripten.h>

extern "C" {
    EMSCRIPTEN_KEEPALIVE
    int add(int a, int b) {
        return a + b;
    }

    EMSCRIPTEN_KEEPALIVE
    const char* greet(const char* name) {
        static char buffer[256];
        sprintf(buffer, "Hello, %s! From WASM.", name);
        return buffer;
    }
}

这里有两个关键点：

extern "C"：防止C++名字修饰，让函数名在WASM中保持原样
EMSCRIPTEN_KEEPALIVE：告诉编译器这个函数要保留，不要被优化掉

然后写CMakeLists.txt：

cmake_minimum_required(VERSION 3.10)
project(HelloWasm)

# 设置C++标准
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

# 添加可执行文件
add_executable(hello hello.cpp)

# 设置WASM输出
set_target_properties(hello PROPERTIES
    SUFFIX ".html"
    LINK_FLAGS "--shell-file ${CMAKE_SOURCE_DIR}/shell.html"
)

# 链接WASM相关库
target_link_options(hello PRIVATE
    -s WASM=1
    -s EXPORTED_FUNCTIONS='["_add", "_greet"]'
    -s EXPORTED_RUNTIME_METHODS='["ccall", "cwrap"]'
)

编译命令：

mkdir build && cd build
emcmake cmake ..
emmake make

编译完成后，你会得到三个文件：hello.wasm、hello.js、hello.html。直接用浏览器打开hello.html就能看到效果。

小提示：如果你不想生成HTML，只想生成WASM和JS文件，可以把SUFFIX改成".js"。我个人习惯在开发阶段生成HTML方便调试，发布时再改成纯JS。

CMake与Emscripten的集成技巧

在实际项目中，我们通常需要更精细的控制。下面是我总结的几个常用技巧。

1. 检测Emscripten工具链

if(EMSCRIPTEN)
    message(STATUS "Building with Emscripten")
    # 设置WASM相关选项
    set(CMAKE_EXECUTABLE_SUFFIX ".html")
else()
    message(FATAL_ERROR "This project requires Emscripten")
endif()

2. 优化选项

WASM的优化和普通C++不太一样。我踩过的一个坑是——默认的-O2优化会把一些函数内联掉，导致JS调用不到。所以导出函数一定要加EMSCRIPTEN_KEEPALIVE。

# 调试模式
target_compile_options(hello PRIVATE -O0 -g4)

# 发布模式
target_compile_options(hello PRIVATE -O3 -flto)
target_link_options(hello PRIVATE -O3 -flto --closure 1)

3. 文件系统支持

如果你的C++代码需要读写文件，Emscripten提供了虚拟文件系统：

target_link_options(hello PRIVATE
    -s FORCE_FILESYSTEM=1
    -s ALLOW_MEMORY_GROWTH=1
)

实战：图像处理库移植

我记得有一次，团队需要把一个C++的图像处理库移植到Web端。这个库依赖OpenCV，听起来很复杂对吧？其实用CMake+Emscripten，步骤很清晰。

项目结构：

image-processor/
├── CMakeLists.txt
├── src/
│   ├── processor.cpp
│   └── processor.h
├── third_party/
│   └── opencv/  # 预编译的OpenCV WASM库
└── web/
    └── index.html

CMakeLists.txt：

cmake_minimum_required(VERSION 3.10)
project(ImageProcessor)

set(CMAKE_CXX_STANDARD 17)

# 添加OpenCV库
set(OpenCV_DIR "${CMAKE_SOURCE_DIR}/third_party/opencv")
find_package(OpenCV REQUIRED)

# 添加源文件
add_executable(processor
    src/processor.cpp
)

# 链接OpenCV
target_link_libraries(processor PRIVATE ${OpenCV_LIBS})

# WASM配置
target_link_options(processor PRIVATE
    -s WASM=1
    -s ALLOW_MEMORY_GROWTH=1
    -s TOTAL_MEMORY=256MB
    -s EXPORTED_FUNCTIONS='["_processImage", "_getResult"]'
    -s EXPORTED_RUNTIME_METHODS='["ccall", "cwrap", "getValue"]'
    --preload-file assets
)

这里要注意--preload-file选项，它会把assets目录下的文件打包到WASM的虚拟文件系统中。这样C++代码就能像操作本地文件一样读取它们。

性能优化建议

WASM的性能虽然已经很接近原生，但还是有一些优化空间。我总结了几点：

优化项	说明	推荐做法
内存管理	WASM有独立的内存空间	使用`ALLOW_MEMORY_GROWTH`，但设置初始大小
函数导出	导出函数有开销	只导出必要的函数，内部函数用static
数据传输	JS和WASM之间传数据有成本	批量传输，避免频繁小数据交换
编译优化	不同优化级别影响性能	发布用-O3，调试用-O0

注意：我曾经犯过一个错误——在WASM里用了大量的std::cout。结果浏览器控制台刷屏，性能直接崩了。WASM里的IO操作非常慢，能省则省。

调试技巧

调试WASM代码比调试原生代码要麻烦一些。这里分享几个我常用的方法：

使用浏览器开发者工具：Chrome和Firefox都支持WASM调试，可以设置断点
添加日志输出：用emscripten_log代替printf
生成source map：编译时加-g4 --source-map-base，可以在浏览器里看到C++源码

# 调试模式编译
target_compile_options(hello PRIVATE -g4 -O0)
target_link_options(hello PRIVATE -g4 --source-map-base http://localhost:8080/)

知识体系总览

下面这张图展示了本章的核心知识结构：

常见问题与避坑

最后，分享几个我实际踩过的坑：

内存溢出：WASM默认内存只有16MB，如果你的程序需要更多，记得设置TOTAL_MEMORY
函数名被改：忘了加extern "C"，结果JS里死活找不到函数
文件路径问题：WASM里的文件路径是虚拟的，和实际文件系统不一样
浏览器缓存：修改了WASM代码后，浏览器可能还加载旧的.wasm文件，记得清缓存

核心要点：

用emcmake和emmake替代常规的cmake和make
导出函数必须加EMSCRIPTEN_KEEPALIVE和extern "C"
合理设置内存大小和优化选项
调试时用-g4生成source map

好了，这一章的内容就到这里。WASM的世界其实挺大的，我们只是开了个头。你可以在自己的项目里试试，把一些计算密集型的模块用WASM重写，效果往往出乎意料。

📚 课程目录