Skip to content

Home

Jump to bottom Edit New page
Jean-Marc Le Roux edited this page May 27, 2014 · 271 revisions

logo

Emscripten is an LLVM to JavaScript compiler. It takes LLVM bytecode (which can be generated from C/C++ using Clang, or any other language that can be converted into LLVM bytecode) and compiles that into JavaScript, which can be run on the web (or anywhere else JavaScript can run).

Using Emscripten, you can

  • Compile C and C++ code into JavaScript and run that on the web
  • Run code in languages like Python as well, by compiling CPython from C to JavaScript and interpreting code in that on the web
  • See the FAQ for more details

Ready to get started? Download the SDK (or build from source) and then proceed to the Tutorial!

News

Demos

Games and Game Engines

Emulators

Application Frameworks

  • pepper.js - Ports of miscellaneous PNaCl apps (earth, voronoi, bullet, etc.)
  • Qt - Ports of various Qt demos

Programming Languages

Tutorials

WIP

Utilities

Graphics

Other Examples

Technical Documentation

Get in Touch

Bug Reports

You can file issues here on GitHub. If relevant, please supply the original source, the generated .ll, and the generated .js files (in a gist, pastebin, or any other method). It's very helpful to compile with EMCC_DEBUG=1 in the environment, and grab the /tmp/emscripten_temp/emcc-* files (note - you should empty that directory manually before, so it only contains new content), that will include the bytecode, ll, and JS in several stages.

With the new fastcomp LLVM-Backend, emscripten now has three repos: this one for emscripten, one for emscripten's LLVM fork and one for emscripten's clang fork. In general, please file bugs here unless you are sure the bug is specific to one of those. Pull requests of course go to the proper repo.

Contributing

Anyone is welcome to help with Emscripten development. Feel free to get in touch with other community members on IRC or on the mailing list (links above), or through issues here on GitHub.

If you find Emscripten useful and want to help out, a good starting point is to look through the issue tracker here: many issues can be resolved without an in-depth knowledge of compiler internals. And when you help out with those, it leaves more time for the developers that do work on compiler internals to do compiler internal-ey stuff :) so everyone benefits. Also, helping out with issues is a good way to learn more about the project.

If you work on Emscripten itself, check out the Developer's Guide.

Patches should be submitted as pull requests. When submitting patches, please:

  • Add yourself to the AUTHORS file (if you aren't already there). By adding yourself, you agree to license your code under the project's open source licenses (MIT/LLVM).
  • You should run all the automatic tests and make sure they pass (python tests/runner.py). Patches that are simple enough (for example, just add library functions that were not used before) might not need this, but most will. Please mention in the pull request or issue which tests you ran.
  • Please make your pull request to incoming, not master. Code in incoming will have tests run on it, and will later merge to master when they all pass.
  • If you add any new functionality or fix an existing bug, add an automatic test to tests/runner.py.
  • Please do not include merge commits in pull requests; include only commits with the new relevant code.

Code Reviews

Current status: In general, kripken should review pull requests before merging. Exceptions are subprojects that are 'owned' by other people (so they should just push to incoming directly):

  • OpenAL and audio in general: @ehsan
  • embind: @imvu
  • Windows stuff: @juj

Branches of interest

  • master - Always safe to pull from, the test suite always passes on it
  • incoming - Where new code lands before tests have been done
  • llvmsvn - Where work to support a new version of LLVM lands. Activity typically begins near the end of an LLVM 6-month dev cycle. When LLVM launches the new version, we merge this branch to master and incoming, at which point our support officially moves to that new LLVM version (we only support one at a time)

Unit test suite

Emscripten contains a built-in unit testing facility. A server farm performs continuous testing on the codebase on Windows 8, Ubuntu 12.10 and Mac OSX 10.7.4 systems. See the latest build results in real-time at Emscripten buildbot page. The following targets exist:

  • incoming branch: win-emcc-incoming-tests, ubuntu-emcc-incoming-tests, osx-emcc-incoming-tests.
  • master branch: win-emcc-master-tests, ubuntu-emcc-master-tests, osx-emcc-master-tests.
  • The target win-emcc-incoming-code-test tests the compilation and deployment of a few simple WebGL applications.

The unit tests are run immediately after a commit occurs on incoming or master branches. Reports are logged live to IRC at #emscripten on the Mozilla network.

The OSX and Ubuntu buildbots also run the Emscripten benchmarks after the unit tests (The benchmarks are not supported on Windows at the moment, #729).

Not all tests necessarily pass on all platforms even if the buildbots report "green" status. Some long-standing failing tests have been disabled to be able to focus on new regressions better. To track the current state of recognized failing tests, see the Emscripten bug tracker with label tests.

Add a custom footer
Add a custom sidebar
Clone this wiki locally