Reinventing the wheel

by Bartoval

A Quick Start Guide to WebAssembly: Unlocking Performance in the Browser

October 15, 2020
webassembly c c++ javascript performance browser emscripten tutorial

A Quick Start Guide to WebAssembly: Unlocking Performance in the Browser

For years, JavaScript stood as the sole language universally understood and executable by web browsers. Its dynamic nature and ease of use have been instrumental in the evolution of the web, enabling rich, interactive experiences. However, JavaScript, by design, doesn’t always provide the raw computational performance needed for certain demanding tasks, nor does it offer direct access to low-level system features or memory management often available in compiled languages.

While browsers have become incredibly efficient at executing JavaScript through just-in-time (JIT) compilation, which compiles frequently used code segments to native binary instructions on the fly, there are still limitations when dealing with computationally intensive workloads.

This is where WebAssembly (Wasm) enters the picture. WebAssembly is not a programming language you write directly (though you can), but rather a binary instruction format for a stack-based virtual machine. Its primary goal is to provide a compilation target for higher-level languages like C, C++, Rust, Go, and many others, allowing developers to bring their existing codebases and leverage the performance characteristics of these languages directly within the web browser environment.

Think of WebAssembly as a complementary technology to JavaScript. It’s designed to run alongside JavaScript, enabling performance-critical functions or entire applications written in other languages to execute at near-native speeds within the browser, while JavaScript handles the dynamic interactions, DOM manipulation, and general web page logic. This opens up a vast range of possibilities, from high-performance games and video editors to scientific simulations and augmented reality experiences, all running directly in the browser without plugins.

This article will guide you through the initial steps of getting started with WebAssembly by compiling a simple C function using the Emscripten toolchain and executing it in a web page.

Prerequisites

Before we dive into compiling code for WebAssembly, you’ll need to set up a few tools on your system. These tools form the necessary environment for the Emscripten SDK to function correctly.

  • Python: Emscripten’s build scripts and utilities rely heavily on Python. Ensure you have Python 3 installed.
  • CMake: Emscripten uses CMake internally to configure and build its supporting utilities and often relies on it for compiling larger projects.
  • Git: You’ll need Git to clone the Emscripten SDK repository.

If you are using macOS, you can typically install these dependencies using Homebrew:

brew install python3
brew install cmake
brew install git

For other operating systems like Windows or Linux, you can usually install these through your system’s package manager (e.g., apt, yum, pacman) or by downloading installers from the official websites.

Introducing the Emscripten SDK

To compile languages like C and C++ into WebAssembly, we need a specialized toolchain. The most mature and widely used toolchain for this purpose is Emscripten.

Emscripten is a complete compiler toolchain based on LLVM and Clang. It takes C/C++ (and other LLVM-supported languages) as input and can output WebAssembly (.wasm) modules along with the necessary “glue” JavaScript code (.js) to load and interact with the Wasm module in a web browser. Historically, Emscripten also targeted asm.js, a highly optimizable subset of JavaScript, as an intermediate step or output format, but the primary target is now WebAssembly.

The Emscripten SDK (emsdk) is a convenient wrapper script that helps you download, install, and manage different versions of the Emscripten toolchain and its dependencies (like Clang, LLVM, Binaryen).

Setting up the Emscripten SDK

First, you need to download the emsdk helper script repository from GitHub. Open your terminal or command prompt and clone the repository:

git clone https://github.com/juj/emsdk.git
cd emsdk

Now, use the emsdk script to download and install the latest version of the SDK. The installation process can take some time as it downloads compilers and other necessary components.

# Fetch the latest registry of available SDK versions
emsdk update

# Install the latest SDK. This downloads all components.
emsdk install latest

# Activate the latest SDK. This sets up environment variables in your current terminal session.
emsdk activate latest

In some cases, the latest alias might not work as expected, or you might need a specific version. You can list available versions using emsdk list. If the above commands don’t seem to set up the environment correctly, you might try activating a specific version explicitly, for example:

emsdk activate sdk-incoming-64bit

The emsdk activate command is crucial. It sets up environment variables (like PATH) in your current shell session, allowing you to access Emscripten commands such as emcc and emrun directly from the command line.

For macOS & Linux, you typically need to source the environment script in each new terminal session where you want to use Emscripten:

source ./emsdk_env.sh

For Windows, you can run the batch file. Using the --global flag attempts to set environment variables system-wide (may require administrator privileges):

emsdk_env.bat --global

Or for the current session:

emsdk_env.bat

After activation, you should be able to run emcc --version to verify that the Emscripten compiler is accessible and shows the correct version.

Your First WebAssembly Module: A C Example

Let’s create a simple C program that performs a calculation. For our WebAssembly example, we’ll write a function that calculates the factorial of a number. This function will be called from JavaScript later.

Create a file named myFirstScript.c and add the following code:

#include <stdio.h>
#include <emscripten/emscripten.h> // Required for EMSCRIPTEN_KEEPALIVE

// EMSCRIPTEN_KEEPALIVE is a macro that tells the Emscripten compiler
// to not eliminate this function during optimization, ensuring it's
// available to be called from JavaScript.
EMSCRIPTEN_KEEPALIVE
int calcFactorial()
{
    int c, n = 10, fact = 1;

    // Calculate factorial of 10
    for (c = 1; c <= n; c++)
        fact = fact * c;

    return fact;
}

// In a typical scenario where you call a C function from JavaScript,
// you might not need a traditional main function that does complex I/O,
// as JavaScript will handle the main execution flow and interface with the DOM.
// We'll omit the main function for simplicity in this example, focusing
// on the function we intend to export and call from JS.

This simple C code defines a function calcFactorial and calculates 10!. The EMSCRIPTEN_KEEPALIVE attribute is important; without it, the compiler might remove the function if it’s not called from within the C code itself (like from a main function), assuming it’s dead code. EMSCRIPTEN_KEEPALIVE ensures it’s preserved and available for external linking, specifically from JavaScript.

Compiling C to WebAssembly with emcc

Now, let’s compile our C file into a WebAssembly module using the Emscripten compiler, emcc. The emcc command is designed to be a drop-in replacement for standard compilers like GCC or Clang, making it easy to adapt existing build systems.

Run the following command in your terminal from the directory where you saved myFirstScript.c:

emcc -O3 --emrun -s WASM=1 -o myFirstScript.html myFirstScript.c

Let’s break down the command-line arguments:

  • emcc: This invokes the Emscripten compiler.
  • -O3: This is an optimization flag. -O3 tells the compiler to apply a high level of code optimization to produce smaller and faster output. Optimization is particularly important for WebAssembly performance.
  • --emrun: This flag generates output files that are compatible with emrun, a simple local web server included with Emscripten, making it easy to test your output in a browser.
  • -s WASM=1: This “settings” flag explicitly tells Emscripten to generate WebAssembly output. This is the default behavior for modern Emscripten, but specifying it is good practice for clarity.
  • -o myFirstScript.html: This specifies the output file. When the output file has an .html extension, emcc generates not only the WebAssembly module (.wasm) but also the necessary “glue” JavaScript code (.js) to load and instantiate the Wasm module, and a basic HTML file that loads this JavaScript. This provides a self-contained package for testing. The actual .wasm and .js files will be named myFirstScript.wasm and myFirstScript.js respectively, generated alongside myFirstScript.html.
  • myFirstScript.c: This is the input source file.

After running this command, you should see myFirstScript.html, myFirstScript.js, and myFirstScript.wasm in your directory.

Running Your WebAssembly Module

Web browsers generally restrict direct access to local files for security reasons. To run a web page that loads external resources like JavaScript and WebAssembly files, you need a web server. Fortunately, the Emscripten SDK includes a simple local server called emrun.

Navigate to the directory containing your generated files and run emrun:

emrun --no_browser --port 8080 myFirstScript.html
  • emrun: Executes the simple web server.
  • --no_browser: Prevents emrun from automatically opening a browser window (you can remove this if you want it to open automatically).
  • --port 8080: Specifies that the server should listen on port 8080. You can choose a different available port if 8080 is in use.
  • myFirstScript.html: Tells emrun which file to serve as the entry point.

Now, open your web browser and navigate to http://localhost:8080/myFirstScript.html.

If your C code had a main function that used printf or other Emscripten-compatible output methods, you might see output appear on the web page or in your browser’s developer console. In our simple example where main was omitted, the HTML page generated by Emscripten will load the Wasm module, but since no function is explicitly called from the initial glue code’s execution environment, you might just see the default Emscripten shell. The real goal is to call calcFactorial from our own JavaScript, which we’ll cover next.

Streamlining Builds with emmake and Makefiles

For projects with multiple source files, complex dependencies, or custom build steps, using a build system like make is standard practice. Emscripten integrates seamlessly with such systems through the emmake command.

emmake is a wrapper script that essentially runs a command (like make) within the Emscripten environment. It intercepts calls to standard compilers (like gcc or clang) made by the build system and redirects them to the emcc compiler with the correct Emscripten-specific flags and paths configured. This allows you to use existing Makefiles (or CMake, Autotools, etc.) with minimal modifications to build your project for the web.

Let’s create a simple Makefile for our myFirstScript.c example. This Makefile will compile the C file and generate the necessary .js and .wasm files.

Create a file named Makefile in the same directory as myFirstScript.c:

# Define project name and the C function to export
PROJ = myFirstScript
EXP_FUNC = calcFactorial

# Define the delete command based on the operating system
ifeq ($(OS),Windows_NT)
    RM = del /Q /F
else
    RM = rm -f
endif

# Define the compiler as emcc
CC = emcc

# Define compiler flags
# -s WASM=1: Ensure WebAssembly output
# --emrun: Generate output compatible with emrun (useful for testing the generated .html)
# -O3: Apply aggressive optimizations
# -s EXPORTED_FUNCTIONS='["_$(EXP_FUNC)"]': Crucially, tells the linker to export the C function
#                                           '_calcFactorial' so it can be called from JavaScript.
#                                           Emscripten prefixes C functions with an underscore by default.
CFLAGS = -s WASM=1 --emrun -O3 -s EXPORTED_FUNCTIONS='["_$(EXP_FUNC)"]'

# Default target: Builds the project.
# It depends on the C source file.
# The -o target.js syntax tells emcc to generate the target.js glue code
# and the corresponding target.wasm module. It can also generate target.html
# if --emrun is used and no separate HTML file is specified with --shell-file.
# For this example, targeting .js is sufficient as it implies the .wasm is also built.
$(PROJ).js: $(PROJ).c
 @echo "Compiling $< to $@ and $(PROJ).wasm..."
 $(CC) $(CFLAGS) -o $@ $^

# Phony target for cleaning generated files
.PHONY: clean
clean:
 @echo "Cleaning up generated files..."
 $(RM) $(PROJ).js $(PROJ).wasm $(PROJ).html

Now, instead of typing the long emcc command directly, you can simply run:

emmake make

emmake intercepts the make command, ensuring that make uses emcc with the correct settings. This command will execute the rule to build myFirstScript.js (which in turn generates myFirstScript.wasm and myFirstScript.html due to the flags).

You can clean up the generated files using:

emmake make clean

Using emmake with a Makefile is a much more robust way to manage your WebAssembly projects, especially as they grow in complexity.

Calling WebAssembly from JavaScript

The most common and powerful way to use WebAssembly is to load the .wasm module within your own web page and call its exported functions directly from JavaScript. This allows you to integrate high-performance Wasm code into your existing web application structure.

Here’s how you can modify an HTML page and add JavaScript to load and run the calcFactorial function from myFirstScript.wasm.

First, create a simple HTML file, for example, index.html:

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <title>Calling WebAssembly from JavaScript</title>
  </head>
  <body>
    <h1>WebAssembly Factorial Example</h1>
    <p>Calculating factorial(10) from WebAssembly:</p>
    <div id="output">Loading WebAssembly...</div>

    <script>
      // Wait for the DOM to be fully loaded
      document.addEventListener("DOMContentLoaded", async () => {
        const outputDiv = document.getElementById("output");
        outputDiv.textContent = "Loading WebAssembly...";

        // Check if the browser supports WebAssembly
        if (!window.WebAssembly) {
          outputDiv.textContent = "Your browser does not support WebAssembly.";
          console.error("WebAssembly is not supported in this browser.");
          return;
        }

        try {
          // Fetch the WebAssembly module bytes from the server
          const response = await fetch("myFirstScript.wasm");

          // Check if the fetch was successful
          if (!response.ok) {
            throw new Error(`HTTP error! status: ${response.status}`);
          }

          // Instantiate the WebAssembly module
          // instantiateStreaming is the most efficient way to load and compile Wasm
          // as it streams the bytes directly from the network.
          const result = await WebAssembly.instantiateStreaming(response);

          // The result object contains 'module' and 'instance'.
          // The 'instance' object contains the 'exports', which are the functions
          // and objects exposed by the WebAssembly module.
          const wasmExports = result.instance.exports;

          // Call the exported C function (Emscripten prefixes C function names with an underscore)
          // The function name matches what we specified in EXPORTED_FUNCTIONS in the Makefile/emcc flags.
          const factorialResult = wasmExports._calcFactorial();

          // Display the result on the page
          outputDiv.innerHTML = `Output from Wasm: <strong>${factorialResult}</strong>`;
          console.log("Factorial calculated by WebAssembly:", factorialResult);
        } catch (error) {
          outputDiv.textContent = `Failed to load or run WebAssembly: ${error}`;
          console.error("WebAssembly error:", error);
        }
      });
    </script>
  </body>
</html>

In this HTML file:

  • We have a div with id="output" where we’ll display the result.
  • We include a <script> tag containing our JavaScript code.

The JavaScript code performs the following steps:

  1. Feature Detection: It checks if the browser supports the WebAssembly object.
  2. Fetching the Module: It uses the Fetch API to get the bytes of the myFirstScript.wasm file from the server. Fetch returns a Promise.
  3. Instantiating the Module: WebAssembly.instantiateStreaming() is the recommended and most efficient way to compile and instantiate a WebAssembly module fetched from the network. It takes the Fetch response as input. This method also returns a Promise.
  4. Accessing Exports: Once the Promise resolves, we get a result object. result.instance.exports is an object containing all the functions and global variables that were exported from the WebAssembly module (using EMSCRIPTEN_KEEPALIVE in C or the EXPORTED_FUNCTIONS linker flag).
  5. Calling the Function: We access our factorial function via wasmExports._calcFactorial() and call it. Note the underscore prefix; Emscripten adds this by default to C function names unless specific steps are taken to prevent it.
  6. Displaying Output: The result is then inserted into the div on the page.

To compile the C code specifically for this scenario (generating just the .wasm and glue .js file, not the full .html wrapper), you would typically use a command like this, or ensure your Makefile does this:

emcc -O3 -s WASM=1 -s EXPORTED_FUNCTIONS='["_calcFactorial"]' -o myFirstScript.js myFirstScript.c

Note: In the Makefile example above, the target $(PROJ).js combined with --emrun and -o $@ was set up to generate the .html, .js, and .wasm. For this specific JS integration example with your own HTML, you only strictly need myFirstScript.wasm and potentially parts of myFirstScript.js if the Wasm module has imports or complex initialization. However, generating myFirstScript.js is standard as it contains the necessary setup code for the Wasm module. Let’s ensure our Makefile includes -s EXPORTED_FUNCTIONS so the function is callable. The Makefile provided earlier does include this flag.

Now, place index.html, myFirstScript.wasm, and myFirstScript.js (generated by emmake make) in the same directory. Use emrun again to serve this directory:

emrun --no_browser --port 8080 index.html

Open your browser to http://localhost:8080/index.html. You should see the page load and then the text “Output from Wasm: 3628800” appear, confirming that the factorial was calculated by your WebAssembly module and the result was displayed by JavaScript.

Beyond the Basics

This guide has only scratched the surface of what’s possible with WebAssembly and Emscripten. Here are just a few areas you might explore next:

  • Passing Data: Learn how to pass arguments of different types (numbers, strings, arrays) between JavaScript and WebAssembly and how to work with WebAssembly’s linear memory.
  • Calling JavaScript from Wasm: Discover how Wasm code can call functions defined in JavaScript using Emscripten’s --js-library feature or the WebAssembly Import Object.
  • More Complex Projects: Explore compiling larger C/C++ codebases, using libraries, and managing dependencies with CMake and Emscripten.
  • Other Languages: Try compiling Rust, Go, or other languages that support Wasm as a target.
  • Debugging: Learn how to debug WebAssembly modules directly in browser developer tools.
  • Advanced Emscripten Features: Explore threads, SIMD, file system emulation, and more.

Conclusion

WebAssembly is a transformative technology for the web platform. It breaks the “JavaScript-only” barrier, allowing developers to harness the performance and capabilities of languages like C and C++ directly in the browser. By providing a safe, fast, and portable compilation target, WebAssembly unlocks new categories of web applications that were previously impractical, pushing the boundaries of what’s possible in a standard web browser environment.

Getting started with Emscripten, as shown in this guide, is your first step into this exciting world. As you become more familiar with the toolchain and the WebAssembly JavaScript API, you’ll be able to integrate increasingly complex and performance-critical code into your web projects, creating richer and more powerful user experiences.