使用 Emscripten 进行交叉构建 - WebAssembly 和 asm.js¶
本示例演示如何使用 Emscripten 和 Conan 交叉构建一个简单的 C++ 项目。
Conan 支持 WASM 交叉编译,让您可以灵活地针对浏览器中不同的 JavaScript/WebAssembly 运行时。
我们建议为每个目标创建单独的 Conan 配置。下面是推荐的配置以及如何使用它们进行构建的说明。
为 WebAssembly (WASM) 设置 Conan 配置¶
[settings]
arch=wasm
build_type=Release
compiler=emcc
compiler.cppstd=17
compiler.libcxx=libc++
# Optional settings to enable multithreading (see note below)
# compiler.threads=posix
compiler.version=4.0.10
os=Emscripten
[tool_requires]
emsdk/4.0.10
[conf]
# Optional settings to enable memory allocation
tools.build:exelinkflags=['-sALLOW_MEMORY_GROWTH=1', '-sMAXIMUM_MEMORY=4GB', '-sINITIAL_MEMORY=64MB']
tools.build:sharedlinkflags=['-sALLOW_MEMORY_GROWTH=1', '-sMAXIMUM_MEMORY=4GB', '-sINITIAL_MEMORY=64MB']
注意
Conan 还支持针对 asm.js 目标进行构建,这在如今被认为是已弃用的。
asm.js 和 WASM 有什么区别?
asm.js 是 JavaScript 的一个子集,为速度进行了优化。它完全受所有浏览器(甚至是旧版浏览器)支持,并编译成一个大型
.js
文件。WebAssembly (WASM) 是一种二进制格式,加载和执行更快更小。大多数现代浏览器都支持它,通常推荐用于新项目。与 asm.js 相比,WASM 也更容易与原生浏览器 API 集成。
尽管 Emscripten 并非真正的运行时环境(如 Linux 或 Windows),但它是一个工具链生态系统的一部分,将 C/C++ 编译为 WebAssembly (WASM) 和 asm.js。
Conan 使用 os=Emscripten
来
与工具链对齐:Emscripten 集成了编译器、运行时粘合代码和 JavaScript 环境,使其成为一个实用的“类操作系统”目标。
支持向后兼容性:Conan Center Index 中的许多配方都使用
os=Emscripten
来启用或禁用专门针对 Emscripten 的功能和依赖项。保持稳定性:更改此设置会破坏依赖于它的配方,并使与替代 WASM 工具链的兼容性复杂化。
注意
wasm
架构指的是 WASM 32位
目标架构,这是默认设置。如果您希望针对 WASM64
,请在您的配置中设置 arch=wasm64
。请注意,WASM64 仍处于实验阶段,需要 Node.js v20+ 和支持它的浏览器。
重要
根据 emscripten 文档,Emscripten 支持两种多线程 API:
POSIX 线程 API(Conan 配置中的
posix
)Wasm Workers API(Conan 配置中的
wasm_workers
)
这两种 API 彼此不兼容,并且与未启用线程支持编译的二进制文件不兼容。这种不兼容性要求在编译器的二进制模型中对线程使用进行建模,从而允许 Conan 区分使用线程编译的二进制文件和未启用线程编译的二进制文件。
如果在配置中设置了线程,Conan 将自动设置编译器和链接器标志以启用线程。
上述配置使用来自 Conan Center Index 仓库 的 emsdk
包,它提供了 Emscripten SDK,包括 emcc
、em++
以及 emrun
和 node
等工具。
如果您倾向于使用系统安装的 Emscripten 而不是 Conan 提供的 Emscripten,则 tool_requires
可以替换为自定义的 compiler_executables
和 buildenv
[conf]
tools.build:compiler_executables={'c':'/path/to/emcc', 'cpp':'/path/to/em++'}
[buildenv]
CC=emcc
CXX=em++
AR=emar
NM=emnm
RANLIB=emranlib
STRIP=emstrip
通过这种方式,Conan 可以配置 emsdk 本地安装,以便从 CMake、Meson、Autotools 或其他构建系统中使用。
在某些情况下,您可能还需要 Emscripten.cmake
工具链文件以应对高级场景。此工具链已添加到我们的打包 emsdk 中,但如果您使用自己的 Emscripten 安装,可以通过使用 tools.cmake.cmaketoolchain:user_toolchain 并提供工具链文件的绝对路径来在配置文件中指定它。
注意
前述配置文件中的 tools.build:exelinkflags
和 tools.build:sharedlinkflags
是建议,但用户可以修改它们或使用 set_target_properties()
命令在 CMakeLists.txt 文件中定义它们的值。
通过启用
ALLOW_MEMORY_GROWTH
,我们允许运行时通过调用emscripten_resize_heap()
在运行时动态增长其内存。如果没有此标志,内存将在启动时分配且无法增长。MAXIMUM_MEMORY
和INITIAL_MEMORY
值指定 Emscripten 运行时的最大和初始内存大小。这些值可以根据您的应用程序需求进行调整。请注意,
arch=wasm64
理论上最大内存大小为 EB 级别,但运行时目前限制为 16GB,而arch=wasm32
最大内存大小为 4GB,arch=asm.js
最大内存大小为 2GB。
重要
emcc
编译器不保证不同版本(包括补丁)之间的 ABI 兼容性。为确保当 Emscripten 版本更改时生成新的 package_id
,建议相应地更新配置中的 compiler.version
设置。
这将确保包 ID 是根据 Emscripten 版本生成的,从而允许 Conan 检测 Emscripten 工具链的变化并相应地重新构建项目。