The Emscripten toolchain is distributed as a standalone Emscripten SDK. The SDK provides all the required tools, such as Clang, Python and Node.js along with an update mechanism that enables migrating to newer Emscripten versions as they are released.
You can also set up Emscripten from source, without the pre-built SDK, see "Installing from Source" below.
To get started with Emscripten development, see the Emscripten website documentation.
That explains how to use the emsdk to get the latest binary builds (without compiling from source). Basically, that amounts to
./emsdk install latest
./emsdk activate latest
The Emscripten SDK is effectively a small package manager for tools that are used in conjunction with Emscripten. The following glossary highlights the important concepts to help understanding the internals of the SDK:
- Tool: The basic unit of software bundled in the SDK. A Tool has a name and a version. For example, 'clang-3.2-32bit' is a Tool that contains the 32-bit version of the Clang v3.2 compiler.
- SDK: A set of tools. For example, 'sdk-1.5.6-32bit' is an SDK consisting
of the tools
clang-3.2-32bit,node-0.10.17-32bit,python-2.7.5.1-32bitandemscripten-1.5.6. - Active Tool/SDK: Emscripten stores compiler configuration in a user-specific file ~/.emscripten. This file points to paths for Emscripten, Python, Clang and so on. If the file ~/.emscripten is configured to point to a Tool in a specific directory, then that tool is denoted as being active. The Emscripten Command Prompt always gives access to the currently active Tools. This mechanism allows switching between different installed SDK versions easily.
- emsdk: This is the name of the manager script that Emscripten SDK is
accessed through. Most operations are of the form
emsdk command. To access the emsdk script, launch the Emscripten Command Prompt.
Using the emsdk pre-compiled packages requires only the minimal set of dependenencies lists below. When building from source a wider set of tools include git, cmake, and a host compiler are required. See: https://emscripten.org/docs/building_from_source/toolchain_what_is_needed.html.
- For Intel-based Macs, macOS 10.13 or newer. For ARM64 M1 based Macs, macOS 11.0 or newer.
java: For running closure compiler (optional). After installing emscripten via emsdk, typing 'emcc --help' should pop up a OS X dialog "Java is not installed. To open java, you need a Java SE 6 runtime. Would you like to install one now?" that will automatically download a Java runtime to the system.
python: Version 2.7.0 or above.java: For running closure compiler (optional)
The emsdk pre-compiled binaries are built aginst Ubuntu/Xenial 16.04 LTS and
therefore depend on system libraries compatiable with versions of glibc and
libstdc++ present in that release. If your linux distribution is very old
you may not be able to use the pre-compiled binaries packages.
java: For running closure compiler (optional)
To remove the Emscripten SDK, simply delete the emsdk directory.
The following tasks are common with the Emscripten SDK:
Run emsdk help or just emsdk to get information about all available commands.
To get a list of all currently installed tools and SDK versions, and all
available tools, run emsdk list.
- A line will be printed for each tool/SDK that is available for installation.
- The text
INSTALLEDwill be shown for each tool that has already been installed. - If a tool/SDK is currently active, a star * will be shown next to it.
- If a tool/SDK is currently active, but the terminal your are calling emsdk
from does not have
PATHand environment set up to utilize that tool, a star in parentheses (*) will be shown next to it. Runemsdk_env.bat(Windows) orsource ./emsdk_env.sh(Linux and OS X) to set up the environment for the calling terminal.
Run the command emsdk install <tool/sdk name> to download and install a new
tool or an SDK version.
Run the command emsdk uninstall <tool/sdk name> to delete the given tool or
SDK from the local hard drive completely.
emsdk update will fetch package information for all the new tools and
SDK versions. After that, run emsdk install <tool/sdk name> to install a new
version.
Emsdk contains a history of old compiler versions that you can use to maintain
your migration path. Type emsdk list --old to get a list of archived tool and
SDK versions, and emsdk install <name_of_tool> to install it.
Some Emsdk Tool and SDK targets refer to packages that are precompiled, and no compilation is needed when installing them. Other Emsdk Tools and SDK targets come "from source", meaning that they will fetch the source repositories using git, and compile the package on demand.
When you run emsdk list, it will group the Tools and SDKs under these two
categories.
To obtain and build latest upstream wasm SDK from source, run
emsdk install sdk-upstream-main-64bit
emsdk activate sdk-upstream-main-64bit
You can use this target for example to bootstrap developing patches to LLVM,
Binaryen or Emscripten. (After initial installation, use git remote add
in the cloned tree to add your own fork to push changes as patches)
If you only intend to contribute to Emscripten repository, and not to LLVM or Binaryen, you can also use precompiled versions of them, and only git clone the Emscripten repository. For more details, see
https://emscripten.org/docs/contributing/developers_guide.html?highlight=developer#setting-up
Unlike tags and precompiled versions, a few of the SDK packages are based on
"moving" git branches and compiled from source (e.g. sdk-upstream-main,
sdk-main, emscripten-main, binaryen-main). Because of that, the
compiled versions will eventually go out of date as new commits are introduced
to the development branches. To update an old compiled installation of one of
this branches, simply reissue the "emsdk install" command on that tool/SDK. This
will git pull the latest changes to the branch and issue an incremental
recompilation of the target in question. This way you can keep calling emsdk install to keep an Emscripten installation up to date with a given git branch.
Note though that if the previously compiled branch is very old, sometimes CMake
gets confused and is unable to properly rebuild a project. This has happened in
the past e.g. when LLVM migrated to requiring a newer CMake version. In cases of
any odd compilation errors, it is advised to try deleting the intermediate build
directory to clear the build (e.g. "emsdk/clang/fastcomp/build_xxx/") before
reissuing emsdk install.
You can toggle between different tools and SDK versions by running emsdk activate <tool/sdk name>. Activating a tool will set up ~/.emscripten to
point to that particular tool. On Windows, you can pass the option --permanent to
the activate command to register the environment permanently for the current user. Use --system to do this for all users.
By default, Emscripten locates all configuration files in the home directory of the user. This may be a problem if you need to simultaneously build with multiple Emscripten compiler versions, since the user home directory can only be configured to point to one compiler at a time. This can be overcome by specifying the '--embedded' option as a parameter to 'emsdk activate', which will signal emsdk to generate the compiler configuration files inside the emsdk root directory instead of the user home directory. Use this option also when it is desirable to run emsdk in a fully portable mode that does not touch any files outside the emsdk directory.
A common and supported use case of the Emscripten SDK is to enable the workflow
where you directly interact with the github repositories. This allows you to
obtain new features and latest fixes immediately as they are pushed to the
github repository, without having to wait for release to be tagged. You do not
need a github account or a fork of Emscripten to do this. To switch to using the
latest upstream git development branch main, run the following:
emsdk install git-1.9.4 # Install git. Skip if the system already has it.
emsdk install sdk-upstream-main-64bit # Clone+pull the latest emscripten-core/emscripten/main.
emsdk activate sdk-upstream-main-64bit # Set the main SDK as the currently active one.
It is also possible to use your own fork of the Emscripten repository via the
SDK. This is achieved with standard git machinery, so there if you are already
acquainted with working on multiple remotes in a git clone, these steps should
be familiar to you. This is useful in the case when you want to make your own
modifications to the Emscripten toolchain, but still keep using the SDK
environment and tools. To set up your own fork as the currently active
Emscripten toolchain, first install the sdk-main SDK like shown in the
previous section, and then run the following commands in the emsdk directory:
cd emscripten/main
# Add a git remote link to your own repository.
git remote add myremote https://github.com/mygituseraccount/emscripten.git
# Obtain the changes in your link.
git fetch myremote
# Switch the emscripten-main tool to use your fork.
git checkout -b mymain --track myremote/main
In this way you can utilize the Emscripten SDK tools while using your own git
fork. You can switch back and forth between remotes via the git checkout
command as usual.
The provided Emscripten SDK targets are metapackages that refer to a specific
set of tools that have been tested to work together. For example,
sdk-1.35.0-64bit is an alias to the individual packages clang-e1.35.0-64bit,
node-4.1.1-64bit, python-2.7.5.3-64bit and emscripten-1.35.0. This means
that if you install this version of the SDK, both python and node.js will be
installed inside emsdk as well. If you want to use your own/system python or
node.js instead, you can opt to install emsdk by specifying the individual set
of packages that you want to use. For example, emsdk install clang-e1.35.0-64bit emscripten-1.35.0 will only install the Emscripten
LLVM/Clang compiler and the Emscripten frontend without supplying python and
node.js.
This may happen if the system runs out of memory. If you are attempting to build
one of the packages from source and are running in a virtual OS or may have
relatively little RAM and disk space available, then the build might fail. Try
feeding your computer more memory. Another thing to try is to force emsdk
install to build in a singlethreaded mode, which will require less RAM
simultaneously. To do this, pass the -j1 flag to the emsdk install command.
Emscripten SDK releases are no longer packaged or maintained for 32-bit systems. If you want to run Emscripten on a 32-bit system, you can try manually building the compiler. Follow the steps in the above section "Building an Emscripten tag or branch from source" to get started.