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 their docs, 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
• 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 for x86. Or, this seems to work for x86_64: ../configure --prefix=pwd/install --program-prefix=llvm- --enable-llvm=/home/alon/Dev/llvm-2.9/cbuild --enable-languages=c,c++ --enable-checking.
• 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 or V8. 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. It's initial values are taken from tests/settings.py. You should edit the paths in ~/.emscripten to those relevant for you, and other settings therein.
• 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 settings.cfg, 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

Run

./emscripten.py INFILE PATH-TO-JS-ENGINE

where INFILE is the path of the file you want to compile. The file should contain LLVM bitcode in human-readable assembly form (that is, as text, and probably beginning with something like ; ModuleID =). Note: the .ll file must have annotations, use -show-annotations in llvm-dis. PATH-TO-JS-ENGINE is the JavaScript engine to use to run the compiler.

The output will be sent to stdout, so you might want to add > OUTFILE to send it to a file. You can then run that file in a JavaScript engine.

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 commandline 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:

• Define arguments (which in the console would be the commandline arguments), say as [] (just because the code expects it to exist).
• Likely you will want to disable the call to run() or 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 Pointer_make(intArrayFromString(...)) (which makes a string into an int array, then copies that to the heap and returns a pointer to it). Arrays should go through Pointer_make(...).
• Optionally, provide some print() function, if you expect the code to call that function to show output.