It’s been a long-time request: Build Uno Platform WebAssembly apps in Visual Studio on Windows using Ahead of Time (AOT) compilation.
Good news, it’s now available in preview in Uno dev branch! The Uno.Wasm.Bootstrap package 1.1-dev.416 package now provides the ability to create AOT, Mixed (AOT+Interpreter) and Interpreter (with Bitcode dependencies) builds on Windows 10, without leaving Visual Studio 2019. To our knowledge, Uno is the first one to provide this kind of functionality. If we are not – please let us know in the comments below; maybe we missed something.
This new Uno feature makes transparent use of the Windows Subsystem for Linux (WSL) to create the final binaries. You’ll only need to setup your WSL environment once using a simple script, and don’t worry if you forget to set it up, the bootstrapper will explain what to do.
Quick Start – Uno, Visual Studio, WASM, AOT
- Make sure WSL with Ubuntu 18.04 is installed
- Install the latest Uno Visual Studio templates
- Create a new Uno Cross Platform app project
- Update the Uno.Wasm.Bootstrap and Uno.Wasm.Bootstrap.Cli nuget packages to 1.1-dev.416 or later, using the Nuget Package manager (There’s no need to update other packages)
- In the Wasm project, add the following line inside the first PropertyGroup:
- After first PropertyGroup, add the following block to enable emscripten IDBFS:
<ItemGroup> <WasmShellExtraEmccFlags Include="-lidbfs.js" /> </ItemGroup>
- Build once, you’ll get a message with a bash command to execute. (This script, for reference).
- Open a Windows Command line or PowerShell and paste the command there. It may take a few minutes as it installs Mono and .NET Core
- Build again. At this step, the build will install the required Emscripten version in the “obj” folder of your application. This may also take a few more minutes.
- Run the application without the debugger and you’ll get an AOT enabled build of your app
Two important notes on using AOT compilation:
- Generating an AOT app always takes some time, which is why this is not enabled by default. You may need to enable is like this:
This will enable AOT for release builds only and use the interpreter otherwise.
- You may adjust the AOT process by balancing the use of the interpreter and AOT compiled code by using the MonoRuntimeMixModeExcludedAssembly Build time, package size , and runtime performance can be tuned balanced by adding or removing assemblies for the AOT generation.
More Technical Details
The dynamic linking feature (referencing a “.wasm” file, through P/Invoke in mono) was intended to be used for development purposes on Windows only as it gives decent build times.
This requirement is caused by the inability of the mono-wasm SDK to run on natively on Windows to do static linking (referencing an LLVM “.bc” bitcode file). This prevented developers using Visual Studio on Windows to build applications that make use of either AOT or that reference those libraries.
The deciding factor for enabling Windows support is the inability to use dynamic linking (the ability to reference “.wasm” files, through P/Invoke in mono) properly since the LLVM backend has been enabled in emscripten (1.39.1 and later). A chain of issues has made this process fragile and very difficult to work with. This also prevented the use of libraries such as libSkia or SQLite.
Windows 10 provides support for WSL, and a while back we provided some steps to build using AOT, but it still was an out of band manual process. Now with the updated bootstrapper, this process is transparent, given that you’ve setup your environment with the provided scripts.
This update also gives the ability to add some additional emscripten parameters, such as enabling back IDFBS which was disabled by the mono for some default size constraints. It also adds the ability to include other native libraries that may be referenced by external code, such as libtpng or libfreetype.
You can head over to the documentation for additional information.
Features above are available in Uno ‘dev’ branch, which will eventually be merged into the ‘master’ branch. It is meant to those of you who are very eager to get started with it.
If you are new to the Uno Platform, you may want to run through the Getting Started tutorial. This will ensure you have the correct environment set up and that you have the latest release of Uno. Of course, we will be blogging more about AOT, Uno Platform and .NET / Visual Studio – so please stay tuned to our blogs and subscribe to Uno Platform blog RSS