After you’ve installed the SDK or built an Emscripten development environment from sources, the compiler should just work! This section shows how to verify that the environment has been set up correctly, and how to troubleshoot installation problems when they do occur.
The first step in verifying the environment is to run Emscripten with --check
. The option prints out information about the toolchain and runs some basic sanity tests to check that the required tools are available.
Open a terminal in the directory in which you installed Emscripten (on Windows open the Emscripten Command Prompt). Then call the Emscripten Compiler Frontend (emcc) as shown:
./emcc --check
Note
On Windows, invoke the tool with emcc instead of ./emcc.
For example, the following output reports that the correct version of clang could not be found:
emcc (Emscripten GCC-like replacement + linker emulating GNU ld) 1.21.0
shared:INFO: (Emscripten: Running sanity checks)
emcc: warning: LLVM version for clang executable "/usr/bin/clang" appears incorrect (seeing "16.0", expected "18") [-Wversion-check]
At this point you need to Install and activate any missing components. When everything is set up properly, emcc ---check
should give no warnings, and if you just enter emcc
(without any input files), it will give an error
emcc: error: no input files
The next test is to actually build some code! On the command prompt navigate to the Emscripten directory for the current SDK and try to build the hello_world.cpp test code:
cd emscripten/<version of emscripten you installed>
./emcc test/hello_world.cpp
This command should complete without warnings and you should find the newly-compiled JavaScript file (a.out.js) in the current directory.
If compiling succeeds, you’re ready for the Emscripten Tutorial. If not, check out the troubleshooting instructions below.
Emscripten has a comprehensive test suite which may be used to further validate all or parts of the toolchain. For more information, see Emscripten Test Suite.
First run ./emcc --check
and examine the output to find missing components. You can also try ./emcc --clear-cache
to empty the compiler’s internal cache and reset it to a known good state.
Missing tools can often be added using the Emscripten SDK (emsdk). For example, to fix a warning that Java is missing, locate it in the repository, install it, and then set it as active:
#List all the components. Look for the missing component (in this case "java-7.45-64bit")
./emsdk list
#Install the missing component
./emsdk install java-7.45-64bit
#Set the component as active
./emsdk activate java-7.45-64bit
If you’re building Emscripten manually from source, see that link for information on how to obtain all dependencies.
Other common problems to check for are:
Errors in the paths in .emscripten. These are less likely if you update the file using emsdk.
Using older versions of Node or JavaScript engines. Use the default versions for the SDK as listed with emsdk list.
Using older versions of LLVM. The correct versions come with the SDK, but if you’re building the environment from source you should make sure to use the proper version of LLVM (which you can find using the emscripten-releases DEPS file and history; other versions might work, especially close-by ones, but are not tested by us and so not guaranteed to work).
If none of the above is helpful, then please contact us for help.