One of the main advantages of debugging cross-platform Emscripten code is that the same cross-platform source code can be debugged on either the native platform or using the web browser’s increasingly powerful toolset — including debugger, profiler, and other tools.
Emscripten provides a lot of functionality and tools to aid debugging:
This article describes the main tools and settings provided by Emscripten for debugging, along with a section explaining how to debug a number of Emscripten-specific issues.
Emcc strips out most of the debug information from optimized builds by default. Optimisation levels -01 and above remove LLVM debug information, and also disable runtime ASSERTIONS checks. From optimization level -02 the code is minified by the Closure Compiler and becomes virtually unreadable.
The emcc -g flag can be used to preserve debug information in the compiled output. By default, this option preserves white-space, function names and variable names.
The flag can also be specified with one of five levels: -g0, -g1, -g2, -g3, and -g4. Each level builds on the last to provide progressively more debug information in the compiled output. The -g3 flag provides the same level of debug information as the -g flag.
The -g4 option provides the most debug information — it generates source maps that allow you to view and debug the C/C++ source code in your browser’s debugger on Firefox, Chrome or Safari!
Note
Some optimizations may be disabled when used in conjunction with the debug flags. For example, if you compile with -O3 -g4 some of the normal -O3 optimizations will be disabled in order to provide the requested debugging information.
The EMCC_DEBUG environment variable can be set to enable Emscripten’s debug mode:
# Linux or Mac OS X
EMCC_DEBUG=1 ./emcc tests/hello_world.cpp -o hello.html
# Windows
set EMCC_DEBUG=1
emcc tests/hello_world.cpp -o hello.html
set EMCC_DEBUG=0
With EMCC_DEBUG=1 set, emcc emits debug output and generates intermediate files for the compiler’s various stages. EMCC_DEBUG=2 additionally generates intermediate files for each JavaScript optimizer pass.
The debug logs and intermediate files are output to TEMP_DIR/emscripten_temp, where TEMP_DIR is by default /tmp (it is defined in the .emscripten configuration file).
The debug logs can be analysed to profile and review the changes that were made in each step.
Note
The debug mode can also be enabled by specifying the verbose output compiler flag (emcc -v).
Emscripten has a number of compiler settings that can be useful for debugging. These are set using the emcc -s option, and will override any optimization flags. For example:
./emcc -01 -s ASSERTIONS=1 tests/hello_world
The most important settings are:
ASSERTIONS=1 is used to enable runtime checks for common memory allocation errors (e.g. writing more memory than was allocated). It also defines how Emscripten should handle errors in program flow. The value can be set to ASSERTIONS=2 in order to run additional tests.
ASSERTIONS=1 is enabled by default. Assertions are turned off for optimized code (-01 and above).
SAFE_HEAP=1 adds additional memory access checks, and will give clear errors for problems like dereferencing 0 and memory alignment issues. Use SAFE_HEAP=2 in order to check only specific lines listed in SAFE_HEAP_LINES, and use SAFE_HEAP=3 to check all the lines except those specified. This last option is the most common operation.
You can also set SAFE_HEAP_LOG to log SAFE_HEAP operations.
A number of other useful debug settings are defined in src/settings.js. For more information, search that file for the keywords “check” and “debug”.
Compiling with the emcc -v option passes -v to LLVM and runs Emscripten’s internal sanity checks on the toolchain.
The verbose mode also enables Emscripten’s Debug mode (EMCC_DEBUG) to generate intermediate files for the compiler’s various stages.
You can also manually instrument the source code with printf() statements, then compile and run the code to investigate issues.
If you have a good idea of the problem line you can add print(new Error().stack) to the JavaScript to get a stack trace at that point. Also available is stackTrace(), which emits a stack trace and tries to demangle C++ function names. Debug printouts can even execute arbitrary JavaScript.
For example:
function _addAndPrint($left, $right) {
$left = $left | 0;
$right = $right | 0;
//---
if ($left < $right) console.log('l<r at ' + stackTrace());
//---
_printAnInteger($left + $right | 0);
}
It can sometimes be useful to compile with either LLVM optimizations (llvm-opts) or JavaScript optimizations (js-opts) disabled.
For example, the following command enables Debug information and -02 optimization (for both LLVM and JavaScript), but then explicitly turns off the JavaScript optimizer.
./emcc -O2 --js-opts 0 -g4 tests/hello_world_loop.cpp
The result is code that can be more useful for debugging issues related to LLVM-optimized code:
function _main() {
var label = 0;
var $puts=_puts(((8)|0)); //@line 4 "tests/hello_world.c"
return 1; //@line 5 "tests/hello_world.c"
}
The Emscripten memory representation assumes loads and stores are aligned. Performing a normal load or store on an unaligned address can fail.
Tip
SAFE_HEAP can be used to reveal memory alignment issues.
Generally it is best to avoid unaligned reads and writes — often they occur as the result of undefined behavior. In some cases, however, they are unavoidable — for example if the code to be ported reads an int from a packed structure in some pre-existing data format.
Emscripten supports unaligned reads and writes, but they will be much slower, and should be used only when absolutely necessary. To force an unaligned read or write you can:
If you get an abort() from a function pointer call to nullFunc or b0 or b1 (possibly with an error message saying “incorrect function pointer”), the problem is that the function pointer was not found in the expected function pointer table when called.
Note
nullFunc is the function used to populate empty index entries in the function pointer tables (b0 and b1 are shorter names used for nullFunc in more optimized builds). A function pointer to an invalid index will call this function, which simply calls abort().
There are several possible causes:
In order to debug these sorts of issues:
Another function pointer issue is when the wrong function is called. SAFE_HEAP=1 can help with this as it detects some possible errors with function table accesses.
ALIASING_FUNCTION_POINTERS=0 is also useful because it ensures that calls to function pointer addresses in the wrong table result in clear errors. Without this setting such calls just execute whatever function is at the address, which can be much harder to debug.
Infinite loops cause your page to hang. After a period the browser will notify the user that the page is stuck and offer to halt or close it.
If your code hits an infinite loop, one easy way to find the problem code is to use a JavaScript profiler. In the Firefox profiler, if the code enters an infinite loop you will see a block of code doing the same thing repeatedly near the end of the profile.
Note
The Browser main loop may need to be re-coded if your application uses an infinite main loop.
The AutoDebugger is the ‘nuclear option’ for debugging Emscripten code.
Warning
This option is primarily intended for Emscripten core developers.
The AutoDebugger will rewrite the LLVM bitcode so it prints out each store to memory. This is useful because you can compare the output for different compiler settings in order to detect regressions, or compare the output of JavaScript and LLVM bitcode compiled using LLVM Nativizer or LLVM interpreter.
The AutoDebugger can potentially find any problem in the generated code, so it is strictly more powerful than the CHECK_* settings and SAFE_HEAP. One use of the AutoDebugger is to quickly emit lots of logging output, which can then be reviewed for odd behavior. The AutoDebugger is also particularly useful for debugging regressions.
The AutoDebugger has some limitations:
To run the AutoDebugger, compile with the environment variable EMCC_AUTODEBUG=1 set. For example:
# Linux or Mac OS X
EMCC_AUTODEBUG=1 ./emcc tests/hello_world.cpp -o hello.html
# Windows
set EMCC_AUTODEBUG=1
emcc tests/hello_world.cpp -o hello.html
set EMCC_AUTODEBUG=0
Use the following workflow to find regressions with the AutoDebugger:
Any difference between the outputs is likely to be caused by the bug.
Note
False positives can be caused by calls to clock(), which will differ slightly between runs.
You can also make native builds using the LLVM Nativizer tool. This can be run on the autodebugged .ll file, which will be emitted in /tmp/emscripten_temp when EMCC_DEBUG=1 is set.
Note
The Emscripten Test Suite contains good examples of almost all functionality offered by Emscripten. If you have a problem, it is a good idea to search the suite to determine whether test code with similar behavior is able to run.
If you’ve tried the ideas here and you need more help, please Get in touch.