nim-wasm-helpers

Help quickly set up a VM configured to build WebAssembly code using Nim.

Intent

Here are a few collected aids to generating WebAssembly (WASM) from Nim using Emscripten. The Vagrantfile can be used with Vagrant and VirtualBox to create a virtual machine (VM) that's already equipped with a properly configured build environment. We won't reproduce all of the Vagrant documentation here, but in general after installing both Vagrant and VirtualBox you should be able to type:

git clone https://github.com/Feneric/nim-wasm-helpers.git
cd nim-wasm-helpers
vagrant up

and after waiting for awhile for everything to download and configure you should have your environment to play in. The vagrant command will produce a lot of output in a variety of colors (mostly green with some gray, white, yellow, and cyan, and maybe two lines of red related to dpkg-preconfigure and building a symlink). This should work on Linux, macOS, MS-Windows, Solaris, BSD, etc. but has only been tested extensively on Linux. This build environment makes use of the Bodhi Vagrant Box which runs Bodhi Linux. Once it's up, you can use:

vagrant ssh

to log in via a shell. The VM is set with a shared folder to enable you to do edits from outside, but if you want to play around directly within it, it has Vim installed with Nim syntax coloring and uses Fish for its shell.

Samples

There are also a few traditional "hello world" samples included, and a Makefile to make building them via make easy. They are all in the Samples folder. The VM provides an NGINX Web server that exposes all the samples via the local Web address: http://bodhi64.local/Samples/

• hello.nim is a one-line "hello world" program. Compiling it to WASM can be achieved by typing:

  make hello.html

• hellojs.nim outwardly appears to do much the same thing, but internally does so via DOM access via JavaScript, providing a simple example of how it's done. It can be compiled to WASM by typing:

  make hellojs.html

• hellodojo.nim again outwardly appears to do much the same thing, but complicates the example still further by accessing an external CDL to pull in a JavaScript framework, providing an example of how to modify the HTML template and make less trivial applications. It needs to have a template (here built on the fly, but in a real project you'd craft your own) and it uses its own special Makefile (in order to keep the basic sample one more generic) and can be compiled to WASM by typing:

  make -f specific.mk hellodojo.html

• Makefile is a generic Makefile to provide basic support for building both Nim and WASM programs.

• specific.mk is a project-specific Makefile built on top of the generic one but with extra information for making hellodojo. Probably for your own project you'd just incorporate this extra information into your regular Makefile so you wouldn't need to use the extra -f flag and argument.

Troubleshooting

If you are running into difficulties, you may find that it is just something transient and rerunning the vagrant up script may fix things. If you are specifically running into errors related to ifdown and ifup they are probably related to a known Vagrant Ubuntu issue. The fix is to manually vagrant ssh into the box after attempting the first vagrant up and type sudo aptitude install ifupdown in the shell. Once it completes, exit the box and try vagrant up again.

Beyond that it makes sense to enter the box and manually each of the steps listed in the Vagrantfile in order to see what fails when. This makes use of several unrelated packages, and new releases do sometimes break things. If you have some helpful tips, putting them into the wiki may help others, too.