Building Projects

Building Projects

See the emmaken.py tool (tools/emmaken.py), and instructions inside, which helps with building large projects. Also see how the large tests in tests/runner.py are built - the C++ project is actually built, using configure and make and so forth (using emmaken.py) - specifically, that includes the following tests: freetype, openjpeg, zlib and poppler.

The documentation below gives more low-level details of the process, most of which you do not need if you use emmaken.py (but it might help to understand things).

Detailed Overview

The basic idea is:

• Replace the normal compiler with Clang or llvm-gcc, and tell it to emit LLVM bitcode. Also replace the linker with {{{llvm-link}}}. For example, in CMake this can be done with

  SET(CMAKE_C_COMPILER "/..PATH../llvm-gcc-4.2-2.8.source/cbuild/install/bin/llvm-gcc") SET(CMAKE_CXX_COMPILER "/..PATH../llvm-gcc-4.2-2.8.source/cbuild/install/bin/llvm-g++") SET(CMAKE_CXX_FLAGS ${CMAKE_CXX_FLAGS} -emit-llvm) SET(CMAKE_LINKER "/..PATH../llvm-2.8/cbuild/Release/bin/llvm-link") SET(CMAKE_CXX_LINKER "/..PATH../llvm-2.8/cbuild/Release/bin/llvm-link") SET(CMAKE_C_LINK_EXECUTABLE "/..PATH../llvm-2.8/cbuild/Release/bin/llvm-link") SET(CMAKE_CXX_LINK_EXECUTABLE "/..PATH../llvm-2.8/cbuild/Release/bin/llvm-link") SET(CMAKE_AR "/..PATH../llvm-2.8/cbuild/Release/bin/llvm-link") SET(CMAKE_C_ARCHIVE_CREATE "<CMAKE_AR> -S -o <LINK_FLAGS> ") SET(CMAKE_CXX_ARCHIVE_CREATE "<CMAKE_AR> -S -o <LINK_FLAGS> ") SET(CMAKE_RANLIB "echo") # Hackish way to disable it

And here is an example for the changes needed in a Makefile:

C = /..PATH../llvm-gcc
CXX = /..PATH../llvm-g++
LINKER = /..PATH../llvm-link
CXX_LINKER = /..PATH../llvm-link

# Use this after linking
LLVM_DIS = "/..PATH../llvm-dis"

# Undefining architecture stuff means code will not generate ASM
CXXFLAGS= -emit-llvm -U__i386__ -U__x86_64__

• Build the project using its normal build system, makefiles, etc. Note that it might fail if it tries to generate executables; you should probably just create libraries. Use make VERBOSE=1 to see the commands being run, so you can make sure you are using the right compiler, etc.
• Run llvm-link to combine libraries, and llvm-dis to generate LLVM assembly (or, use -S when calling llvm-link).
• Compile the generated .ll file using Emscripten.

Other Tips

See the readmes and makefiles in the big tests, like tests/python, tests/lua, tests/bullet, etc., they explain how the project was built into an .ll file.