Using Emscripten from Visual Studio 2010

This page describes how to use Emscripten on Windows.

Setting up the Emscripten Toolchain on Windows

This section contains basic instructions on how to start using Emscripten on a clean Windows box. After these steps, you can invoke emcc from the command line by calling 'python emcc'.

1. Install Python 2.x (not 3.x) from http://www.python.org/ Set python bin\ to PATH.
2. Install cygwin from http://www.cygwin.com/ Set cygwin bin\ to PATH.
3. Install node.js from http://nodejs.org/
4. Install and set up llvm-clang.

• Follow the steps in this guide to download and build llvm and clang: http://clang.llvm.org/get_started.html
• NOTE: Instead of checking out the trunk as the guide suggests, we recommend checking out the clang 3.1 release, as that is the version emscripten is best tested to work with. This can be achieved by replacing the checkout commands in the guide with the following lines:
  • For llvm: svn co http://llvm.org/svn/llvm-project/llvm/tags/RELEASE_31/final llvm
  • For clang: svn co http://llvm.org/svn/llvm-project/cfe/tags/RELEASE_31/final clang

5. Install git. We recommend using TortoiseGit on Windows, which is installed in two steps (in the listed order!):
   1. Download and install TortoiseGit itself from http://code.google.com/p/tortoisegit/
   2. Download and install msysGit from http://msysgit.github.com/
6. Clone the kripken/emscripten repository from github. The emscripten repository contains the main compiler tool for compiling C/C++ programs to JavaScript.
   • git clone https://github.com/kripken/emscripten.git
7. Configure paths for emscripten.
   1. In command line, browse to the folder where you cloned emscripten and execute 'python emcc'
   • You should get the 'Welcome to Emscripten!' dialog.
   2. Edit the file C:\Users\username\.emscripten:
   3. Replace the line EMSCRIPTEN_ROOT to point to the emscripten root folder, e.g. EMSCRIPTEN_ROOT = 'C:/Projects/emscripten'
   4. Replace the line LLVM_ROOT to point directly to the path to where you built clang.exe, e.g. LLVM_ROOT = 'C:/Projects/llvm-build/bin/Release'
   5. Save the file and copy it to your cygwin home folder, e.g.
   • copy C:\users\username\.emscripten C:\cygwin\home\username\
   • There is a bug in emscripten that it currently looks for the file .emscripten in two places (Win7 user home folder or cygwin user home folder), depending on the environment it is executed in, so as a current workaround these files must be present and identical on Windows. (see issue #411)

Integrating Emscripten to Visual Studio 2010

It is possible to integrate the Emscripten compiler directly to Visual Studio. This allows existing VS .sln files to be directly built using emcc. The Microsoft compiler property pages are replaced by Clang and emcc -specific options.

1. Install Visual Studio 2010

• Note: Express version has not been tested, but should be ok. Please drop a line on emscripten IRC channel or mailing list to report your experience with VS2010 Express!

2. Clone the juj/vs-tool repository from github:
   • git clone https://github.com/juj/vs-tool

• The vs-tool repository contains a plugin to Visual Studio 2010 (or rather, to MSBuild) that instructs Visual Studio how to use the llvm-clang and emscripten toolchain.

3. Compile and install {emcc,em++,emar,emranlib}.exe.
   1. Open and build a Release-x86 build of the solution vs-tool\pythonemcc\pythonemcc.sln.
   2. Copy the output vs-tool\pythonemcc\bin\Release{emcc,em++,emar,emranlib}.exe to the emscripten\ root folder (the same folder where the file 'emcc' resides in)

• These executables are a workaround tool to enable Visual Studio/MSBuild to invoke python during its build process. Calling 'python emcc' directly turned out to be a difficult task for VS, which is why these native executables were created. (If someone has a solution that obsoletes this workaround, please let us know!)

4. Install vs-tool itself.
   1. Navigate to folder vs-tool\
   2. Copy the folders Clang and Emscripten to C:\Program Files (x86)\MSBuild\Microsoft.Cpp\v4.0\Platforms\.
5. Set up the required environment variables for vs-tool.
   1. Windows 7: Open Control Panel -- System -- Advanced System Settings -- Environment Variables.
   2. Create a new environment variable 'CLANG_BIN' and set it to point to the folder where you built clang to (path to clang.exe) E.g.
      • SETX CLANG_BIN C:\Projects\llvm-build\bin\Release
      • This is how vs-tool locates the folder to your llvm-clang compiler. Alternatively, this path can be set per-project in Visual Studio project property pages.
   3. Create a new environment variable 'EMCC_BIN' and set it to point to the emscripten git repository root folder (the path where you copied emcc.exe and other exes to). E.g.
      • SETX EMCC_BIN C:\Projects\emscripten
      • This is how vs-tool locates the emscripten compiler. This path can also be overridden per-project in VS property pages.
   4. Create a new environment variable 'EMCC_WEBBROWSER_EXE' and set it to point to an executable you want to use to browse emscripten-generated web pages from Visual Studio. This process is spawned when you tap Start (Ctrl-F5) in Visual Studio for a emscripten-targeted project.
      • SETX EMCC_WEBBROWSER_EXE C:\Program Files (x86)\Mozilla Firefox\firefox.exe
6. Now you are all set to start developing Emscripten-based projects from Visual Studio. To test the installation, open the Visual Studio solution file \emscripten\tests\msvc10\tests_msvc10.sln.

Tips for using Emscripten from the Visual Studio 2010 IDE

To build a Visual Studio solution using the Emscripten toolchain, select the "Emscripten" configuration from the Configuration Manager dropdown as the active configuration, and choose Build Solution (F7).

To launch a project directly to a web browser from Visual Studio, right-click on the project to run, choose "Set as Startup Project", and select Start without Debugging (Ctrl+F5). This should launch the generated .html file to the browser you specified in EMCC_WEBBROWSER_EXE. A bug(?) in Visual Studio causes a "Executable for Debug Session" dialog to occasionally open up when you hit Ctrl+F5. This can be ignored by clicking Yes, then No, or simply by hitting Esc and then tapping Ctrl+F5 again.

llvm-clang and emscripten compiler settings can be edited for the project in the "usual" Visual Studio fashion: First make sure that the Emscripten platform configuration is active, then right-click on a project, and choose Properties. In the Project properties dialog, two tree nodes Clang C/C++ and Emcc Linker should exist, which allow you to specify the desired compilation options.

If you have an existing solution file you want to build using Emscripten, open the Configuration Manager.. dialog for the solution, and in the Active Solution Platform dropdown, choose New.... In the new dialog, choose Emscripten as the platform name, and Copy settings from Empty. After this, you can switch between building the solution for Win32 and Emscripten from the Configuration Manager dropdown list.

When you want to create a new Visual Studio project for Emscripten, we recommend you start with a Visual C++ Empty Project. This will create a new project for the Win32 platform. Then convert that project for Emscripten as outlined in the previous paragraph.