QtforWebAssembly环境配置知其然并知其所以然

真正正确的配置Qt for WebAssembly环境姿势&＃xff0c;实践所得&＃xff0c;而非照搬

背景说明&＃xff1a;我的Qt环境是Qt5.15.0 &＃43; windows &＃43; msys2&＃xff0c;由于我的Qt是通过编译源码安装的&＃xff0c;所以接下来我可能着重讲解下如何通过编译源码的方式来安装Qt for WebAssembly&＃xff0c;当然直接使用在线安装工具就没那么麻烦了。

如果你是按照别的文章苦苦尝试依旧失败才找到这里&＃xff0c;那就彻底点跟着我全部重新来过。如果是第一次那就忽略下述操作。首先删除所有之前配置失败时留下的痕迹。包括&＃xff0c;环境变量配置里所有和emsdk相关的变量&＃xff0c;比如EMSDK&＃xff0c;EM_CONFIG&＃xff0c;EMSDK_NODE&＃xff0c;JAVA_HOME(有可能被替换成了emsdk目录下的java)等&＃xff0c;用户目录(系统变量USERPROFILE指示的位置)下的emsdk生成文件&＃xff0c;比如.emscripten文件和.emscripten_cache目录等。
有了失败的经验&＃xff0c;接下来&＃xff0c;就全新开始吧。

第一大步&＃xff1a;安装Emscripten SDK&＃xff1a;

Qt使用Emscripten SDK来构建WebAssembly应用。Emscripten是一个开源的完善的WebAssembly编译工具链。Emscripten做了很多优化处理&＃xff0c;专注于将C/C&＃43;&＃43;代码编译成可在Web&＃xff0c;Node.js上运行的小体积高效率可执行文件。
Emscripten SDK(emsdk)用来安装整个工具链&＃xff0c;包括emcc和LLVM等。它可以在Linux,Windows和MacOS上使用。emcc(Emscripten Compiler Frontend)是其主要编译工具&＃xff0c;是像其他标准编译器gcc,clang等的简易替代版。emcc使用clang和LLVM编译WebAssembly应用。emcc还会生成Javascript API来支持调用编译代码&＃xff0c;生成的js可以被Node.js或者HTML执行。

下面开始安装适合Qt的Emscripten
可参考&＃xff1a;
Download and install — Emscripten 2.0.16 documentation
Qt for WebAssembly | Qt 5.15
Qt_for_WebAssembly wiki
上述官方的教程过于简洁&＃xff0c;其实存在很多不符合实际情况的地方&＃xff0c;万不可一味照搬。

• 首先&＃xff0c;决定好你的Emscripten SDK想要存放的地方。我把它放在我的Qt目录里了&＃xff0c;因为我只有Qt使用它。
• 按照官方说明&＃xff0c;可以使用git安装。进入我的Qt根目录&＃xff0c;D:\Qt5.15.0。Git Bash Here。
  执行 &＃xff1a;

git clone https://github.com/emscripten-core/emsdk.git
#(由于github被qiang的缘故&＃xff0c;不能下载或很慢&＃xff0c;可以尝试把该项目导入你的gitee中&＃xff0c;然后从你的gitee中clone该项目。当然有个科学上网工具就香了)


git bash的工作已完成&＃xff0c;退出git bash。
在克隆下来的emsdk目录内&＃xff0c;打开命令提示符&＃xff0c;执行如下&＃xff1a;

# 安装1.39.7版本的SDK&＃xff0c;会下载node.js&＃xff0c;java&＃xff0c;python&＃xff0c;llvm等时间较久
emsdk install 1.39.7
# 注意&＃xff0c;这里有个坑。官方指出Qt 5.15应使用1.39.8&＃xff0c;但实际安装版的Qt 5.15 WebAssembly是使用1.39.7的SDK编译出来的&＃xff0c;如果使用1.39.8将来编译自己的代码会一直出现编译警告&＃xff0c;所有要使用1.39.7。
# 不过我现在正是要编译Qt WebAssembly呢&＃xff0c;这个版本选哪个其实都可以。但官方使用1.39.7来发布自有它的道理&＃xff0c;还是保存一致为好# 使该版本为活跃版本&＃xff0c;其实就是在当前目录下生成.emscripten文件。这个是Emscripten的编译配置文件&＃xff0c;值得好好说道说道&＃xff0c;后面还会派上大用场。
emsdk activate 1.39.7
# (官方说的还要加--embedded&＃xff0c;其实在windows上加与不加完全没有区别。
# 另外&＃xff0c;这个激活并不会对系统造成任何影响&＃xff0c;而只是创建了.emscripten&＃xff0c;但可以使用--permanent来创建系统环境变量&＃xff0c;不过完全没必要)


现在可以退出命令提示符了&＃xff0c;到此SDK就完全安装好了&＃xff0c;可以通过emsdk list查看安装情况。

第二大步&＃xff1a;在线安装WebAssembly的Qt库&＃xff0c;或从源码编译

在线安装方式十分容易&＃xff0c;打开Qt在线安装维护工具&＃xff0c;将WebAssembly勾选上&＃xff0c;然后下载自动安装即可。
源码编译较为繁琐。以我的环境为例&＃xff0c;供参考。
按官方说明&＃xff0c;需要先安装sed依赖&＃xff0c;我直接在msys2中用pacman安装了。
下载qt5.15.0源码&＃xff0c;解压源码&＃xff0c;使源码的根目录为D:\qt5src&＃xff0c;创建D:\qt5build目录&＃xff0c;在该目录中打开命令提示符&＃xff0c;执行Qt for WebAssembly的交叉编译配置&＃xff1a;

..\qt5src\configure.bat -prefix D:\Qt5.15.0\webassembly -no-warnings-are-errors -xplatform wasm-emscripten -platform win32-g&＃43;&＃43; -nomake examples -opensource -confirm-license


说明&＃xff1a;-prefix 指定安装将会部署的位置&＃xff0c;根据自己情况修改 -xplatform wasm-emscripten 指示交叉编译wasm-emscripten平台代码&＃xff0c;不同于桌面版qt库&＃xff0c;web版隐式地使用静态编译&＃xff0c;原因可想而知。 -opensource -confirm-license 是为了自动确认开源证书&＃xff0c;免得到时暂停手动确认&＃xff1b;-nomake examples 不需要示例&＃xff0c;mingw桌面版Qt里已经有了。

配置结束后&＃xff0c;退出该命令提示符&＃xff0c;开始编译&＃xff1a;
在emsdk目录中找到emcmdprompt.bat并双击运行&＃xff0c;
看该脚本内容&＃xff0c;&＃64;cmd /k call emsdk_env.bat&＃xff0c;实际就是在创建Emscripten的运行环境。

为何一定要在该批处理创建的命令提示符环境下编译&＃xff1f;刚刚虽说安装好了emsdk也activate了&＃xff0c;但它并没有创建系统环境变量&＃xff0c;而仅仅是在刚刚那个命令提示符窗口里有效。调用该脚本将在当前终端自动创建完善的emsdk环境&＃xff0c;必须这样做&＃xff0c;没有必要将这些变量自己加到系统环境变量里。另外&＃xff0c;这里说道说道.emscripten文件。该编译配置文件在activate时创建&＃xff0c;记录了该活跃版本的一些编译工具集的路径变量&＃xff0c;emcmdprompt.bat&＃xff0c;emsdk_env.bat等Emscripten里的命令提示符就是使用这些变量来找到编译器等工具的。后面&＃xff0c;我们还需要将该文件修改后放到用户目录下。那是后话了&＃xff0c;先回归正题。

Qt for WebAssembly 仅支持部分Qt模块.
当前支持的 Qt Modules(模块)
• qtbase
• qtdeclarative
• qtquickcontrols2
• qtwebsockets
• qtsvg
• qtcharts
• qtmqtt &＃xff08;不知怎么编译&＃xff09;
明确不支持:
• qtmultimedia
• qtwebview
其他模块Qt官方未测试&＃xff0c;可能正常也可能不正常工作。

切换目录到D:\qt5build&＃xff0c;编译所需要的模块&＃xff1a;

mingw32-make module-qtbase module-qtdeclarative module-qtquickcontrols2 module-qtwebsockets -j16


正常情况&＃xff0c;不会出现任何编译错误&＃xff0c;如果出现了&＃xff0c;请查看官网说明&＃xff0c;确认是否少安装了依赖等

这样安装&＃xff1a;&＃xff08;官方丝毫不提如何安装&＃xff0c;这是个坑&＃xff09;

mingw32-make module-qtbase-install_subtargets module-qtdeclarative-install_subtargets module-qtquickcontrols2-install_subtargets module-qtwebsockets-install_subtargets


如一切正常&＃xff0c;则安装成功。

测试是否能用&＃xff1a;
不使用Qt Creator&＃xff0c;通过命令可以直接使用&＃xff0c;只是有些不方便。
操作如下&＃xff1a;拷贝一个你的qt项目到一个临时目录&＃xff0c;运行emcmdprompt.bat&＃xff0c;切换到该目录&＃xff0c;执行安装好的webassemly qmake&＃xff0c;如

D:\Qt5.15.0\webassembly\bin\qmake.exe # 生成makefile文件


执行&＃xff1a;mingw32-make -j16 # 开始编译


如编译成功&＃xff0c;将生成app.html&＃xff0c;qtloader.js&＃xff0c;app.js&＃xff0c;app.wasm等主要文件。

执行&＃xff1a;emrun --no_browser . # 创建服务


将创建的服务地址输入浏览器&＃xff0c;查看效果。

第三大步&＃xff1a;配置Qt Creator便于使用

重点&＃xff1a;&＃xff1a; 将emsdk目录下的.emscrpten拷贝到用户目录下。注意&＃xff0c;无法直接使用&＃xff0c;需要将全部变量修改成绝对路径值&＃xff0c;删除无用行&＃xff0c;例如

原来的这个配置文件&＃xff0c;其实是python代码&＃xff0c;但Qt Creator却没法自动解析其内容&＃xff0c;不知是否是bug&＃xff0c;于是迫不得已通过将全部值写死来解决。另外&＃xff0c;这里的操作是因为&＃xff0c;当下一步的WebAssembly插件启用后&＃xff0c;Creator将会解析用户目录下.emscrpten来获取emsdk环境信息。我们提前设置好。

还有&＃xff0c;用户目录下的.emscrpten文件&＃xff0c;在手动运行emsdk编译器emcc或em&＃43;&＃43;也会自动生成&＃xff0c;但不知为何存在缺失变量的问题&＃xff0c;没法直接使用&＃xff0c;还是要像上面那样手动修改。

1. 启用WebAssembly插件 (安装版自动启用)
   Qt -> help ->About Plugins
   
   重启后&＃xff0c;应该能自动检测到Emscripten Compiler&＃xff0c;如下所示&＃xff1a;
   
   解释&＃xff1a;Creator没法自动检测到Emscripten的原生编译器emcc和em&＃43;&＃43;&＃xff0c;这两个其实是个调用clang进行编译的python脚本&＃xff0c;方便命令行使用的。Creator直接检测到了clang。如果强行手动添加并使用emcc的话&＃xff0c;后面编译的时候会出现配置错误而没法编译&＃xff0c;貌似Creator不支持直接使用emcc作为编译器。

2. 如果是编译源码的方式&＃xff0c;我们还要手动添加Qt Versions&＃xff0c;添加刚安装的webassembly版的qmake&＃xff0c;如下所示&＃xff1a;
   

3. 如果是编译源码的方式&＃xff0c;还要手动添加Kits&＃xff0c;
   
   修改成合适的值&＃xff0c;改好后大概如下&＃xff1a;
   

4. 至此&＃xff0c;已配置好creator环境。
   测试一个示例程序&＃xff0c;试试效果吧。
   
   编译成功&＃xff01;点击运行&＃xff01;
   
   

运行配置中&＃xff0c;默认调用且固定配置的ie浏览器运行&＃xff0c;没法手动指定浏览器&＃xff0c;而ie并不支持webassembly技术。
这应该是Creator自身的问题&＃xff0c;将来可能会修复&＃xff0c;现在有两个变通方法&＃xff1a;

1. 我们可以将该地址拷贝到自己的浏览器里执行&＃xff0c;比如edge&＃xff0c;http://localhost:30000/texteditor.html
2. 修改这个项目的.pro.user文件中的WASM.WebBrowserSelectionAspect.Browser键的值&＃xff0c;像这样
   不过这依旧只能对当前项目有效。

运行如下&＃xff1a;

终于&＃xff0c;大功告成&＃xff01;
尽情地发挥Qt跨平台的魅力吧。
希望对你有所帮助。