Getting started

Getting Started

TL;DR

• Get LLVM and Clang, version 3.0 (or SVN, until 3.0 is released)
• Get the trunk versions of SpiderMonkey and V8. Older versions will not work!
• Run the emscripten test runner, python tests/runner.py. On first run it will create ~/.emscripten. Edit that so the paths are to the right places
• Run the test runner and see that the tests pass. Or run just an individual test with python tests/runner.py clang_0_0.test_hello_world

Preparations

Operating System

Emscripten is developed and tested on Linux, but should work on every platform where you can run a JS engine, LLVM, and Python.

LLVM & Clang

You will need to get and build LLVM and Clang. You should really read the official Clang installation guide, but here is a short sketch:

• Get LLVM 3.0 (or SVN, until 3.0 is released). Other versions may not work!
• Get Clang 3.0 and place it in your LLVM directory under tools/clang (note: not clang-3.0 or anything like that - simply clang)
• Make a cbuild/ directory inside the LLVM (not Clang) directory
• In cbuild/, run cmake .. (or ../configure) and then make. This will build LLVM and Clang.

LLVM-GCC

As of LLVM 3.0, llvm-gcc is deprecated, so Emscripten doesn't officially support it either. It might still work, or it might not.

JavaScript Engine

Next you need a JavaScript engine like SpiderMonkey (building guide) or V8 (building guide). Get one of those and build it. Or better yet get both. Note that you should get a recent version - from hg for SpiderMonkey, and svn for V8. For V8, build it with scons d8 to build the d8 shell.

Running the Automated Tests

• In the top directory, run python tests/runner.py. That will run all the tests. They should all pass. This will take a long time - we have a lot of tests!
• Note that the first time you run the tests (or emscripten.py), it will create a config file, ~/.emscripten. Its initial values are taken from settings.py. You should edit the paths in ~/.emscripten to those relevant for you.
• You can do python tests/runner.py clang_0_0.test_X where X is one of the tests in runner.py (for example, intvars or fannkuch). This will run that single test. You can then view the generated code by going to the temp directory (TEMP_DIR) mentioned in ~/.emscripten, and looking at src.cpp.o.js. The other files in that directory can also be useful to figure out what went wrong.
  • clang_0_0 in the example above defines how to compile it. First is the compiler name, clang or llvm_gcc. Then whether to run LLVM optimizations (1 for yes, 0 for no), and whether to optimize & reloop (1 for yes, 0 for no).
• If you get errors on all the tests, there is probably something wrong in the config file that is mentioned above. To debug that, run a single test, say python tests/runner.py clang_0_0.test_hello_world, and look at the output files in the temp directory as mentioned above.

Compiling Code

Emscripten compiles LLVM bytecode (.bc) or assembly (.ll) files. To generate the .bc files from C or C++, you should run emmaken.py (in tools/), which is a script that wraps around clang. emmaken runs clang with the proper parameters so it generates LLVM bitcode, uses the emscripten header files instead of your system ones, and sets various flags that tell clang not to generate platform-specific code if possible. For example, you can use emmaken as follows:

python emmaken.py myfile.cpp -o myfile.bc

That will generate myfile.bc, which contains LLVM bytecode, you can then run emscripten.py on that.

You can also run clang directly, instead of with emmaken. In this case, you should run it with -emit-llvm. You should also use the -g flag when compiling to preserving symbols, since Emscripten uses these to calculate struct field offsets.

To generate human-readable assembly (.ll) from a .bc file, you should translate that to .ll using llvm-dis with the -show-annotations option (emscripten.py will do this for you if necessary). Note that the automatic test runner, tests/runner.py, does all of this during the tests, so reading what it does can be a useful way to learn.

• Note that Emscripten expects the output to be formatted and annotated the way llvm-dis -show-annotations does. So if you get .ll output from something else, you should run it through llvm-as (to generate LLVM bitcode) and then llvm-dis -show-annotations (to get properly formatted and annotated .ll).

For building large projects, see Building Projects.

When you have a .bc or .ll file, compile it using ./emscripten.py infile. For more options, run ./emscripten.py --help. You can then run the resulting code in a JavaScript engine. You will need an ~/.emscripten file; see the 'Running the Automatic Tests' section. If you have issues with compiling or with the generated code, see the Debugging page.

Running Emscriptened Code on the Web

By default the generated code is meant to run in a console engine, which is useful for the automated tests (for example, arguments is then equal to the command line arguments). To run that code in a browser, a few trivial changes should be done. For an example, see demos/cubescript.html and demos/cubescript.js. The basic steps are:

• If you want to pass command like arguments, define scriptArgs to an array of strings.
• Likely you will want to disable the call to run() (the entry point) by setting INVOKE_RUN to 0 in settings.js before compilation and call it yourself at the right time.
• Connect your web JavaScript to the Emscriptened JavaScript. Currently this must be done manually. Again, see the cubescript demo mentioned before, but in general:
  • Calling Emscriptened code requires you to use the name-mangled function names (thirdparty/demangler.py can help unmangle them).
  • Parameters need to be converted. Integers and floats should be fine, but strings need to go through allocate(intArrayFromString('foo')) (which makes a string into an int array, then copies that to the heap and returns a pointer to it). Arrays should go through allocate([1, 2, 3]).
• Optionally, provide some print() function, if you expect the code to call that function to show output. For lower level I/O controls, see the Filesystem Guide.