Getting started

Getting Started

Preparations

Operating System

Emscripten is developed and tested on Linux, and is known to have problems elsewhere. Help with supporting other platforms would be very welcome, see our issue tracker. For now, if you are not on Linux already, it would be best to run Emscripten in a Linux VM.

LLVM & Clang

You will need to get and build LLVM and Clang (or, instead of Clang you can use llvm-gcc). You should really read the official Clang installation guide, but here is a short sketch:

• Get LLVM 2.9 (other versions may not work).
• Get Clang 2.9 and place it in your LLVM directory under tools/clang (note: not clang-2.9 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

If you want to use llvm-gcc instead of Clang, do the above except for the part about Clang, then do this:

• Get LLVM-GCC 2.9

• As before, make a cbuild directory inside it

• If you're on an x86 machine, in cbuild/ run:

    ../configure --prefix=`pwd`/install --program-prefix=llvm- --enable-llvm=ABSOLUTE_PATH_TO_LLVM/cbuild --enable-languages=c,c++ --target=i686-pc-linux-gnu --with-tune=generic --with-arch=pentium4
  

  If you're on a x86-64 machine, run:

    ../configure --prefix=`pwd`/install --program-prefix=llvm- --enable-llvm=ABSOLUTE_PATH_TO_LLVM/cbuild --enable-languages=c,c++ --enable-multilib
  

  • Note: Must run configure with flex and bison already installed
  • Note: Need ABSOLUTE path as shown there!

• Then do make. Takes a very long time.

• Then make install. Don't forget this, it sets up a cbuild/build-i686-linux[..] (or similar) directory, with the actual gcc, g++ etc.

Note: LLVM 2.7 and 2.8 may also work, but currently all testing is done on 2.9.

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 run clang or llvm-gcc 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 the human-readable assembly, you translate that to .ll using llvm-dis with the -show-annotations option. 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.

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.