Tutorial

Emscripten Tutorial

Emscripten is an open source LLVM to JavaScript compiler. With it, you can compile C and C++ code into JavaScript and run it on the web. And it's easy!

Requirements

To use Emscripten and complete this tutorial, you need a few things:

• The Emscripten code, from github
• LLVM with Clang (3.0)
• Node.js (0.5.5 or above)
• Python

After getting those if you don't already have them, change directory to where you put the Emscripten code. The rest of this tutorial will assume that that is where you are running commands (or, add a path to another location if you prefer).

Before continuing, it's a good idea to make sure the requirements work. Try

clang tests/hello_world.cpp
./a.out

That should use Clang and LLVM compile a "hello world" app and run it. Then, test Node.js with

node tests/hello_world.js

which should also print out "hello world".

Setting up Emscripten

If you haven't run Emscripten before, run it now with

./emcc

(Ignore a warning about no input files. If you are on Windows, you don't need "./".)

"emcc" is the "Emscripten compiler frontend", an easy way to use Emscripten basically as a drop-in replacement for a standard compiler like gcc.

The first time you run emcc (or any other of the Emscripten tools), it will create a settings file at ~/.emscripten (~ is your user's home directory). You should edit that file now, changing the directory locations of LLVM and Node to the right places in your setup (specifically, edit LLVM_ROOT and NODE_JS). If these paths are not right, Emscripten will not find LLVM, Clang or Node.js and it will fail.

Running Emscripten

You can now compile your first file! Build the same "hello world" C++ file from before, but this time using Emscripten:

./emcc tests/hello_world.cpp

There should now be an a.out.js file in the current directory. Run it with

node a.out.js

and it should print "hello, world!" as expected.

Emscripten can also generate HTML with embedded JavaScript. Try this command:

./emcc tests/hello_world_sdl.cpp -o hello.html

By specifying that the output is an HTML file, you have told Emscripten to generate a complete HTML page. In this case, the source code uses the SDL API to show a colored cube. Open the web page in your web browser to see it (it should work in any browser that supports the Canvas element.)

...

Next Steps

After completing this tutorial, you can do more sophisticated things with Emscripten. For that, it is recommended to also get

• The Closure Compiler. Emscripten generates code that is designed to be processed correctly in Closure Compiler's advanced mode, which can both minify and optimize for speed in significant ways. The Closure Compiler is run automatically by emcc in -O2 and above.
• The SpiderMonkey shell. Almost, but not all of the tests in Emscripten's test suite can run using Node.js. It's also a good idea to test using more than one engine anyhow.