FAQ

#FAQ

General

• Q. What does Emscripten do?

  A. Emscripten compiles LLVM bytecode into JavaScript, which then allows:

  • Compiling C/C++ and other code that can be translated into LLVM, directly into JavaScript.
  • Compiling the C/C++ runtimes of other languages into JavaScript, and then running code in those other languages in an indirect way. This works for languages like Python and Lua.

• Q. Why are you doing this?

  A. The web is standards-based, cross-platform, runs everywhere from PCs to iPads, and has numerous independent compatible implementations. It's arguably the best platform to develop for, for those reasons. But it could be even more developer-friendly: While JavaScript (when used well!) is an excellent language, lots of people want to code in other languages. By compiling to JavaScript, everyone is happy.

• Q. What is the status of Emscripten?

  A. Emscripten is mature and has been used to port a very long list of real-world codebases to JavaScript, including large projects like CPython, Poppler and Bullet. You can see some demos here.

  However, there are some unavoidable limitations, since JavaScript is not native code: CodeGuidlinesAndLimitations

• Q. How fast will the compiled code be?

  A. Right now generated code is around 3-4 times slower than gcc -O3, however, note that there are substantial differences between benchmarks, and in some cases JS engine bugs cause significantly poorer performance. See http://syntensity.com/static/splashpres.pdf (slides from a SPLASH 2011 presentation) for more details. docs/paper.pdf also has some numbers, but they are out of date.

  Emscripten-compiled code can run at similar speeds to handwritten JavaScript code in many benchmarks. While hand-crafted code can in theory do everything Emscripten does and more, in practice such code is written for clarity. Compilers, like Emscripten or gcc, emit fast code which is not necessarily easy to read, hence in some cases compiled code can be faster than handwritten code.

  It is expected that JavaScript engines will continue to improve, as JIT technology continues to be worked on. Speculation: During 2012 we will get from 3-4X slower than native code to 2-3X slower than native code. At that point JavaScript will be very close to Java, which is probably the limit - both Java and JavaScript are portable and memory-safe, which imposes some performance limitations on both, and Java JITs have been heavily optimized for many years so it will be very hard to exceed them.

  To run the emscripten benchmarks yourself, do python tests/runner.py benchmark.

• Q. How big will the compiled code be?

  A. The effective size of the code will be about the same as native code. That is, if you gzip your code, it will be about the same size as gzipped native code. For more, see this blog post.

• Q. What is the compiler written in?

  A. JavaScript. Paralleling the language we are generating code for has various benefits. For example, if we determine some expression can be known at compile time, we can do evaluate it immediately in the compiler; otherwise we can simply JSON.stringify() it for the generated code to solve at runtime. Also, (nice) JavaScript is cool.

• Q. Isn't it better just to write JavaScript code? Why compile LLVM into JavaScript?

  A. By all means write new JavaScript code. Emscripten is just another option to have, and will hopefully be useful if you have a lot of C/C++ code that you don't want to rewrite from scratch. You can still write web applications normally, but Emscripten lets you integrate existing C/C++ code when useful.

• Q. How does this relate to similar projects?

  A. There are lots of other compilers into JavaScript, for all sorts of languages, see this list.

  More directly related is a proprietary product called Mandreel, which like Emscripten compiles C and C++ to JavaScript. Mandreel focuses on games specifically and has various features related to that. Interestingly, Mandreel appears to have been influenced by Emscripten, almost certainly in ideas (their demo code shows use of concepts appearing in the Relooper algorithm in the Emscripten paper) and possibly in code (many of the variables and so forth in their demo code are identical to Emscripten's), which is great - anything that helps code be ported to the web is awesome. Comparing their generated code to Emscripten's, aside from the similarities already mentioned there are some important differences, both projects do some things better than the other it seems.

  You can also compare Emscripten and related projects to Google NaCl. NaCl has two main benefits: Reusing existing C/C++ code on the web, and running that code at native speed. Emscripten aims to provide the first of those two benefits, while hoping that JavaScript engines will get so fast that the second benefit will pretty much be achieved as well, and while doing so in a web-friendly way: Emscripten generates JavaScript, that runs on any browser on any platform and device.

• Q. Where does Emscripten itself run?

  A. Emscripten is known to work on Windows, OS X and Linux. Note however that currently the automatic tests are run mainly on Linux. Help with supporting other platforms would be very welcome.

  That's for the compiler, of course, the generated code is valid JavaScript, so it will run anywhere JavaScript can run. By default typed arrays are used (both for code compatibility and speed), however typed arrays are not universally supported yet, so Emscripten lets you also generate code without typed arrays, which will run practically everywhere.

• Q. Is this really a compiler? Isn't it better described as a translator?

  A. Well, a compiler is usually defined as a program that transforms source code written in one programming language into another, which is what Emscripten does. A translator is a more specific term that is usually used for compilation between high-level languages, which isn't exactly applicable. On the other hand a decompiler is something that translates a low-level language to a higher-level one, so that might technically be a valid description, but it sounds odd since we aren't going back to the original language we compiled from (C/C++, most likely) but into something else (JavaScript).

• Q. The name of the project sounds weird to me.

  A. I don't know why; it's a perfectly cromulent word!

Using Emscripten

• Q. How do I compile code?

  A. See the Tutorial.

• Q. I get lots of errors building the tests.

  A. Some common problems are:

  • Using older versions of Node or JS engines. Use the versions mentioned in the Tutorial.
  • Using older versions of LLVM. The recommended LLVM version is the 3.0 release. Using LLVM trunk might or might not work.
  • Typos in the paths ~/.emscripten.

• Q. Can I compile my project using Emscripten? Do I need a new build system?

  A. You can in most cases very easily use your project's current build system with Emscripten. See Building-Projects.

• Q. My code compiles very slowly.

  A. -O2 and above can be quite slow. -O1 should complete very fast which is useful for testing.

• Q. When I compile code that should work, I get odd errors in Emscripten about various things. I get different errors (or it works) on another machine.

  A. Make sure you are using the Emscripten bundled system headers. Using emcc will do so by default, but if you compile into LLVM bitcode yourself, or you use your local system headers even with emcc, problems can happen.

• Q. Why does code compiled with iostream (cout <<, etc.), STL (std::string, etc.) not work?

  A. C/C++ library code, like iostream or std::string, is normally linked to the native code when compiled. With Emscripten, the library code that is linked in is in src/library*.js, which currently has the basics of unistd.h, stdio.h and many C libraries in place, but not all the C++ iostream or STL stuff.

  It should be possible to compile an entire libc++ implementation and use that with your compiled code.

• Q. My code fails to compile, the error includes something about inline assembly (or {"text":"asm"}).

  A. Emscripten cannot compile inline assembly code, which is CPU specific, because Emscripten is not a CPU emulator.

  Many projects have build options that generate only platform-independent code, without inline assembly. That should be used for Emscripten. For example, the following might help (and are done automatically for you by emcc):

  #undef __i386__
  #undef __x86_64__
  

  Since when no CPU-specific #define exists, many projects will not generate CPU specific code. In general though, you will need to find where inline assembly is generated, and how to disable that.

• Q. My SDL app doesn't work.

  A. There are several things that could be the problem, see the documentation inside library_sdl.js for the details. Updates are in that file as opposed to the wiki for now. See the SDL automatic test, tests/hello_world_sdl.cpp, that should always work so it is a useful starting point (build it with emcc tests/hello_world_sdl.cpp -o hello.html, then run hello.html in your web browser.)

• Q. How can my compiled program access files?

  A. Emscripten uses a virtual file system that may be preloaded with data or linked to URLs for lazy loading. See the Filesystem Guide for more details.