Home
» Optimizing Code
Generally you should first compile and run your code without optimizations (the default). Once you are sure that the code runs correctly, you can use the techniques in this article to make it load and run faster.
Code is optimized by specifying optimization flags when running emcc. The levels include: -O0 (no optimization), -O1, -O2, -Os, -Oz, and -O3.
For example, to compile with optimization level -O2:
emcc -O2 file.cpp
The higher optimization levels introduce progressively more aggressive optimization, resulting in improved performance and code size at the cost of increased compilation time. The levels can also highlight different issues related to undefined behavior in code.
The optimization level you should use depends mostly on the current stage of development:
In addition to the -Ox options, there are separate compiler options that can be used to control the JavaScript optimizer (js-opts), LLVM optimizations (llvm-opts) and LLVM link-time optimizations (llvm-lto).
Note
There are several flags you can pass to the compiler to affect code generation, which will also affect performance — for example DISABLE_EXCEPTION_CATCHING. These are documented in src/settings.js. Some of these will be directly affected by the optimization settings (you can find out which ones by searching for apply_opt_level in tools/shared.py).
A few useful flags are:
NO_EXIT_RUNTIME: Building with -s NO_EXIT_RUNTIME=1 lets the compiler know that you don’t want to shut down the runtime environment after the main() function finishes. This allows it to discard the atexit and global destructor calls it would otherwise make, improving code size and startup speed.
This is useful if your main() function finishes but you still want to execute code, for example in an app that uses a main loop function.
Note
Emscripten will not shut down the runtime if it detects emscripten_set_main_loop(), but it is better to optimise away the unnecessary code.
This section describes optimisations and issues that are only relevant to very large projects.
By default Emscripten emits the static memory initialization code inside the .js file. This can cause the JavaScript file to be very large, which will slow down startup. It can also cause problems in JavaScript engines with limits on array sizes, resulting in errors like Array initializer too large or Too much recursion.
The --memory-init-file 1 emcc option causes the compiler to emit this code in a separate binary file with suffix .mem. The .mem file is loaded (asynchronously) by the main .js file before main() is called and compiled code is able to run.
Note
From Emscripten 1.21.1 this setting is enabled by default for fully optimized builds, that is, -O2 and above.
You may wish to build the less performance-sensitive source files in your project using -Os or -Oz and the remainder using -O2 (-Os and -Oz are similar to -O2, but reduce code size at the expense of performance. -Oz reduces code size more than -Os.)
Note
This only matters when compiling the source to bitcode. There are currently no JavaScript-specific optimization flags for -Os or -Oz, and these map to -O2 in the bitcode-to-JavaScript phase.
Tips for reducing code size include:
JavaScript engines will often compile very large functions slowly (relative to their size), and fail to optimize them effectively (or at all). One approach to this problem is to use “outlining”: breaking them into smaller functions that can be compiled and optimized more effectively.
Outlining increases overall code size, and can itself make some code less optimised. Despite this, outlining can sometimes improve both startup and runtime speed. For more information see For more information read Outlining: a workaround for JITs and big functions.
The OUTLINING_LIMIT setting defines the function size at which Emscripten will try to break large functions into smaller ones. Search for this setting in settings.js for information on how to determine what functions may need to be outlined and how to choose an appropriate function size.
Aggressive variable elimination attempts to remove variables whenever possible, even at the cost of increasing code size by duplicating expressions. This can improve speed in cases where you have extremely large functions. For example it can make sqlite (which has a huge interpreter loop with thousands of lines in it) 7% faster.
You can enable aggressive variable elimination with -s AGGRESSIVE_VARIABLE_ELIMINATION=1.
Note
This setting can be harmful in some cases. Test before using it.
C++ exceptions are turned off by default in -O1 (and above). This prevents the generation of try-catch blocks, which lets the code run much faster, and also makes the code smaller.
To re-enable exceptions in optimized code, run emcc with -s DISABLE_EXCEPTION_CATCHING=0 (see src/settings.js).
Building with -s ALLOW_MEMORY_GROWTH=1 allows the total amount of memory used to change depending on the demands of the application. This is useful for apps that don’t know ahead of time how much they will need, but it disables some optimizations. (Work is ongoing to improve this.)
Inlining often generates large functions, as these allow the compiler’s optimizations to be more effective. Unfortunately large functions can be slower at runtime than multiple smaller functions because JavaScript engines often either don’t optimize big functions (for fear of long JIT times), or they do optimize them resulting in noticeable pauses.
Note
-O1 and -O2 inline functions by default. Ironically, this can actually decrease performance in some cases!
You can try to avoid this issue by disabling inlining (in specific files or everywhere), or by using Outlining.
Enable Debug mode (EMCC_DEBUG) to output files for each JavaScript optimization pass.
A few UNSAFE optimizations you might want to try are:
Modern browsers have JavaScript profilers that can help find the slower parts in your code. As each browser’s profiler has limitations, profiling in multiple browsers is highly recommended.
To ensure that compiled code contains enough information for profiling, build your project with profiling as well as optimization and other flags:
emcc -O2 --profiling file.cpp
Emscripten-compiled code can currently achieve approximately half the speed of a native build. If the performance is significantly poorer than expected, you can also run through the additional troubleshooting steps below: