Emscripten

Now that we know what LLVM is, we can discuss Emscripten. Emscripten was developed to compile LLVM IR into JavaScript, but has recently been updated to compile LLVM into WebAssembly. The idea is that, when you get the LLVM compiler working, you can have the benefit of all the languages that compile to LLVM IR. In practice, the WebAssembly specification is still in its early days and does not support common language features such as GC. Therefore, only non-GC languages such as C/C++ and Rust are currently supported. WebAssembly is still in the early MVP phase of its development, but the addition of GC and other common language features are coming soon. When that happens, there should be an explosion of programming languages that will compile to WebAssembly.

When Emscripten was released in 2012, it was intended to be an LLVM-to-JavaScript compiler. In 2013, support was added for asm.js, which is a faster, easily optimized subset of the JavaScript language. In 2015, Emscripten began to add support for LLVM-to-WebAssembly compiling. Emscripten also provides a Software Development Kit (SDK) for both C++ and JavaScript that provides glue code to give users better tools for interaction between JavaScript and WebAssembly than those currently offered by the WebAssembly MVP alone. Emscripten also integrates with a C/C++-to-LLVM compiler called Clang, so that you can compile your C++ into WebAssembly. In addition, Emscripten will generate the HTML and JavaScript glue code you need to get your project started.

Emscripten is a very dynamic project and changes to the toolchain happen frequently. To stay up to date with the latest changes in Emscripten, visit the project home page at https://emscripten.org.

Installing Emscripten on Windows

I am going to keep this section brief because these instructions are subject to change. You can supplement these instructions with the official Emscripten download and install instructions found on the Emscripten website: https://emscripten.org/docs/getting_started/downloads.html.

We will need to download and build Emscripten from the emsdk source files on GitHub. First, we will walk through what to do on Windows.

Python 2.7.12 or higher is a prerequisite. If you do not have a version of Python higher than 2.7.12 installed, you will need to get the windows installer from python.org and install that first: https://www.python.org/downloads/windows/.

If you have installed Python and you are still getting errors telling you that Python is not found, you may need to add Python to your Windows PATH variable. For more information, refer to this tutorial: https://www.pythoncentral.io/add-python-to-path-python-is-not-recognized-as-an-internal-or-external-command/.

If you have Git installed already, cloning the repository is relatively simple:

1. Run the following command to clone the repository:

git clone https://github.com/emscripten-core/emsdk.git

2. Wherever you run this command, it will create an emsdk directory. Enter that directory using the following:

cd emsdk

You may not have Git installed, in which case, the following steps will bring you up to speed:

1. Go to the following URL in a web browser: https://github.com/emscripten-core/emsdk.
2. You will see a green button on the right-hand side that says Clone or download. Download the ZIP file:

3. Unzip the downloaded file to the c:\emsdk directory.
4. Open up a Windows Command Prompt by typing cmd into the start menu and pressing Enter.
5. From there, you can change to the c:\emsdk\emsdk-master directory by typing the following:

 cd \emsdk\emsdk-master

At this point, it does not matter whether you had Git installed or not. Let's move forward:

1. Install emsdk from the source code running the following command:

emsdk install latest

2. Then activate the latest emsdk:

emsdk activate latest

3. Finally, set up our path and environment variables:

emsdk_env.bat

This last step will need to be rerun from your install directory every time you open a new command-line window. Unfortunately, it does not permanently set the Windows environment variables. Hopefully, that will change in the future.

Installing Emscripten on Ubuntu

If you are installing on Ubuntu, you should be able to use the apt-get package manager and git for the complete install. Let's move forward:

1. Python is required, so if you do not have Python installed, be sure to run the following:

sudo apt-get install python

2. If you do not already have Git installed, run the following:

sudo apt-get install git

3. Now you will need to clone the Git repository for emsdk:

git clone https://github.com/emscripten-core/emsdk.git

4. Change your directory to move into the emsdk directory:

cd emsdk

5. From here, you need to install the latest version of the SDK tools, activate it, and set your environment variables:

./emsdk install latest
./emsdk activate latest
source ./emsdk_env.sh

6. To make sure everything was installed correctly, run the following command:

emcc --version

Using Emscripten

We run Emscripten from the command line; therefore, you can use any text editor you choose to write your C/C++ code. Personally, I am partial to Visual Studio Code, which you can download here: https://code.visualstudio.com/download.

One beautiful thing about Visual Studio Code is that it has a built-in command-line terminal, which lets you compile your code without switching windows. It also has an excellent C/C++ extension that you can install. Just search for C/C++ from the extensions menu and install the Microsoft C/C++ Intellisense extension.

Whatever you choose for your text editor or integrated development environment, you need a simple piece of C code to test out the emcc compiler.

1. Create a new text file and name it hello.c.
2. Type the following code into hello.c:

#include <emscripten.h>
#include <stdlib.h>
#include <stdio.h>

int main() {
    printf("hello wasm\n");
}

3. Now I can compile the hello.c file into WebAssembly and generate a hello.html file:

emcc hello.c --emrun -o hello.html

4. The --emrun flag is necessary if you want to run the HTML page from emrun. This flag adds code that will capture stdout, stderr, and exit in the C code and emrun will not work without it:

emrun --browser firefox hello.html

Running emrun with the --browser flag will pick the browser where you would like to run the script. The behavior of emrun seems to be different between browsers. Chrome will close the window when the C program exits. That can be annoying because we are just trying to display a simple print message. If you have Firefox, I would suggest running emrun using the --browser flag.

I do not want to imply that Chrome cannot run WebAssembly. Chrome does have different behavior when a WebAssembly module exits. Because I was trying to keep our WebAssembly module as simple as possible, it exits when the main function completes. That is what is causing problems in Chrome. These problems will go away later when we learn about game loops.

To find out what browsers are available to you, run the following:

emrun --list_browsers

emrun should open an Emscripten-templated HTML file in a browser.

Make sure you have a browser capable of running WebAssembly. The following versions of the major browsers should work with WebAssembly:

• Edge 16
• Firefox 52
• Chrome 57
• Safari 11
• Opera 44

If you are familiar with setting up your own web server, you may want to consider using it rather than emrun. After using emrun for the first few chapters of this book, I returned to using my Node.js web server. I found it easier to have a Node-based web server up and running at all times, rather than restarting the emrun web server every time I wanted to test my code. If you know how to set up an alternative web server (such as one for Node, Apache, and IIS), you may use whatever web server you prefer. Although IIS requires some additional configuration to handle WebAssembly MIME types.