Qt for WebAssembly 环境配置 - 知其然并知其所以然

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

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

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

第一大步：安装Emscripten SDK：

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

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

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

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

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

# 安装1.39.7版本的SDK，会下载node.js，java，python，llvm等时间较久
emsdk install 1.39.7  
# 注意，这里有个坑。官方指出Qt 5.15应使用1.39.8，但实际安装版的Qt 5.15 WebAssembly是使用1.39.7的SDK编译出来的，如果使用1.39.8将来编译自己的代码会一直出现编译警告，所有要使用1.39.7。
# 不过我现在正是要编译Qt WebAssembly呢，这个版本选哪个其实都可以。但官方使用1.39.7来发布自有它的道理，还是保存一致为好

# 使该版本为活跃版本，其实就是在当前目录下生成.emscripten文件。这个是Emscripten的编译配置文件，值得好好说道说道，后面还会派上大用场。
emsdk activate 1.39.7  
# (官方说的还要加--embedded，其实在windows上加与不加完全没有区别。
# 另外，这个激活并不会对系统造成任何影响，而只是创建了.emscripten，但可以使用--permanent来创建系统环境变量，不过完全没必要)

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

第二大步：在线安装WebAssembly的Qt库，或从源码编译

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

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

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

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

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

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

切换目录到D:\qt5build，编译所需要的模块：

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

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

这样安装：（官方丝毫不提如何安装，这是个坑）

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

如一切正常，则安装成功。

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

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

执行：mingw32-make -j16   # 开始编译

如编译成功，将生成app.html，qtloader.js，app.js，app.wasm等主要文件。

执行：emrun --no_browser .    # 创建服务

将创建的服务地址输入浏览器，查看效果。

第三大步：配置Qt Creator便于使用

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

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

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

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

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

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

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

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

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

运行如下：

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

---