ChangeLog.md
This document describes changes between tagged Emscripten SDK versions.
Note that version numbers do not necessarily reflect the amount of changes between versions. A version number reflects a release that is known to pass all tests, and versions may be tagged more or less frequently at different times.
Note that there is no ABI compatibility guarantee between versions - the ABI may change, so that we can keep improving and optimizing it. The compiler will automatically invalidate system caches when the version number updates, so that libc etc. are rebuilt for you. You should also rebuild object files and libraries in your project when you upgrade emscripten.
Not all changes are documented here. In particular, new features, user-oriented fixes, options, command-line parameters, breaking ABI changes, deprecations, significant internal modifications and optimizations etc. generally deserve a mention. To examine the full set of changes between versions, you can use git to browse the changes between the tags.
See docs/process.md for more on how version tagging works.
WASM_JS_TYPES setting was removed, as the corresponsing propsal was
pushed back to phase 1. (#26739)-sDETERMINISTIC setting was removed. This setting just injected
src/deterministic.js as a --pre-js. For now, this file remains part of
emscripten so folks can sill use it manually if needed. If you are a user of
this feature please let us know otherwise this may be deleted in a future
release. (#26648)-m64 compiler flag is now honored, and works are an alias for
-sMEMORY64 and/or --target=wasm64. (#26765)umask(). (#50739)syscall_arch.h no longer exists, but can be
replaced with emscripten/syscalls.h. (#26658).message and .stack fields of the thrown
object will only be populated if -sEXCEPTION_STACK_TRACES is set. (#26523)emcmake no longer automatically injects --experimental-wasm-threads and
--experimental-wasm-bulk-memory flags when used with versions of node older
than v16. (#26560)EXPORT_EXCEPTION_HANDLING_HELPERS is deprecated and setting it will not do
anything. getExceptionMessage is exported anyway when ASSERTIONS or
EXCEPTION_STACK_TRACES is set, which are set by default at -O0. At -O1
or above, you can export it separately by
-sEXPORTED_RUNTIME_METHODS=getExceptionMessage,decrementExceptionRefcount.
(#26499)EMSCRIPTEN macro is now defined in emscripten.h rather than
on the command line (__EMSCRIPTEN__, which is built into LLVM, should be
used instead). (#26417)-sWASM_WORKERS.
This is an extension of #26336 which removed many of them. These APIs were
not previously functional under Wasm Workers, but if there is strong use case
it may be possible to enable them in future. (#26487)EMSCRIPTEN macro (__EMSCRIPTEN__ should
be used instead). (#26381)-sRELOCATABLE setting was effectively removed (moved to legacy
settings). This setting was deprecated in #25265 and has not been used
internally since #25522.-sWASM_WORKERS emscripten will no longer include pthread
API stub functions. These stub functions where never designed to work under
Wasm Workers, so its safer to error at link time if pthread APIs are used
in Wasm Worker-based programs. (#26336)SDL_hid_init() and related
functions. (#26297)NODEJS_CATCH_REJECTION setting was removed. This setting only has an
effect when targeting very old versions of node (< 15). Its trivial to replace
with a simple --pre-js file or with the --unhandled-rejections=strict
command line flag which it essentially emulates. Versions of node above v15
have this behavior by default. (#26330)NODEJS_CATCH_EXIT setting was removed. This setting was disabled by
default in #22257, and is no longer used by emscripten itself. It is also
problematic as it injects a global process.on handler. It is easy to replace
with a simple --pre-js file for those that require it. (#26326)bool type rather than int. For example emscripten_proxy_sync and
emscripten_is_main_runtime_thread. (#26316)emcc.bat) were removed from the git
repository. These scripts are created by the ./bootstrap script which
must be run before the toolchain is usable (for folks using a git checkout of
emscripten). (#26247)logReadFiles was removed from the default INCOMING_MODULE_JS_API list.
To use this feature you now need to explictly add logReadFiles to
INCOMING_MODULE_JS_API. (#26190);WASM_OBJECT_FILES setting (which has been long deprecated)
was removed. -flto enables bitcode object files, otherwise Wasm object
files have been the default for a long time already. (#26219).-sEXECUTABLE setting was added which adds a #! line to the resulting
JavaScript and makes it executable. This setting defaults to true when the
output filename has no extension, or ends in .out (e.g. a.out) (#26085)class_<T>::iterable(). register_vector uses this so bound std::vector
works with for...of/Array.from()/spread. (#25993)__async: 'auto', which allows async JS function to be used unmodified with
ASYNCIFY/JSPI. In addition, when such function are also marked as __proxy: 'sync' it is now possible for them to be called from back background threads
with the same blocking semantics. (#26130, #26019, #26000)test_EXPORT_EXCEPTION_HANDLING_HELPERS in
test_core.py to see the usage. (#25988)select() and poll() system calls can now block under certain
circumstances. Specifically, if they are called from a background thread and
file descriptors include pipes. (#25523, #25990)-sAUDIO_WORKLET setting (which depends on
shared memory and -sWASM_WORKERS). To do this, build with
-sENVIRONMENT=worklet. In this environment, because audio worklets don't
have a fetch API, you will need to either use -sSINGLE_FILE (to embed the
Wasm file), or use a custom instantiateWasm callback to supply the
Wasm module yourself. (#25942)contrib.lua to Lua version 5.5.0 (#26033)-sPROXY_TO_WORKER setting (along with the corresponding
--proxy-to-worker flag) was removed due to lack of usage. If you were
depending on this feature but missed the PSA, please let us know about your
use case. (#25645, #25440)-sFETCH_STREAMING is enabled.NODE_HOST_ENV setting was added which exposes the host environment
variables to the generated program, when running under Node. This setting is
enabled by default when -sNODERAWFS is used but can also be controlled
separately. (#18820)-sFAKE_DYLIBS setting was added. When enabled you get the current
emscripten behavior of the -shared flag, which is to produce regular object
files instead of actual shared libraries (side modules). Because this
setting is enabled by default this doesn't change the default behavior of the
compiler. If you want to experiment with real shared libraries you can
explicitly disable this setting. (#25826)wasm-ld after
the internal emscripten linker flags. This means that users can now override
emscripten defaults with things -Wl,--stack-first. (#25803)emscripten_html5_remove_event_listener function in html5.h in order
to be able to remove a single callback. (#25535)file_packager.py script no longer supports --embed with JS
output (use --obj-output is now required for embedding data). This usage
has been producing a warning since #16050 which is now an error. (#25049)RETAIN_COMPILER_SETTINGS setting and the corresponding
emscripten_get_compiler_setting API no longer store or report internal
compiler settings (those listed in settings_internal.js). We made an
exception here for EMSCRIPTEN_VERSION which is the only internal setting
where we could find usage of emscripten_get_compiler_setting (in a global
GitHub search). (#25667)-sRELOCATABLE when linking the main module. (#25522)emrun.py script no longer support running on python2. (#25597)-sUSE_WEBGPU was removed in favor of the external port Emdawnwebgpu which
are used via --use-port=emdawnwebgpu. See 4.0.10 release notes for details.CROSS_ORIGIN setting was added in order to work around issues hosting
emscripten programs across different origins (#25581)SINGLE_FILE mode was changed from base64 to
directly embed binary data into UTF-8 string. Users who use the SINGLE_FILE
mode along with a custom HTML file should declare the files to have UTF-8
encoding. See src/settings.js docs on SINGLE_FILE. Use the option
-sSINGLE_FILE_BINARY_ENCODE=0 to fall back to base64 encoding. (#25599)globalThis polyfill and universally enabling
mutable globals: (#25375, #25385)
val functions call, operator(), and new_ now support
passing pointers by using the allow_raw_pointers() argument. This feature
is only enabled with C++17 and newer. Older versions will allow pointers by
default.RELOCATABLE and LINKABLE settings were deprecated in favor of the higher
level and better supported MAIN_MODULE / SIDE_MODULE settings. (#25265)-gsource-map flag has been updated to be independent of other types of
debugging effects (in particular it no longer causes the wasm binary to have
a name section, and it no longer suppresses minification of the JS output).
To get the previous behavior, add -g2 along with -gsource-map.
See also the newly updated
documentation which
covers debugging flags and use cases (#25238).-sASYNCIFY_LAZY_LOAD_CODE setting and the corresponding C function
emscripten_lazy_load_code were removed. (#25236)addRunDependency and removeRunDependency API are now optional and need
to be included and/or exported using, for example,
DEFAULT_LIBRARY_FUNCS_TO_INCLUDE or EXPORTED_RUNTIME_METHODS. (#24974)LOAD_SOURCE_MAP setting was made an internal setting. This was always
an internal detail of the sanitizers, which is enabled automatically when
needed, so setting it explicitly should never be needed. (#24967)USE_OFFSET_CONVERTER
setting. This feature only existed to work around an old v8 bug that was fixed
back in 2019. (#24963)handle callback on the preloadPlugins used by --use-preload-plugins
(and FS_createPreloadedFile API`) was converted from callbacks to async.
Any externally managed plugins would need to be updated accordingly. An
assertion will detect any such non-async plugins in the wild. (#24914)sdl-config and sdl2-config scripts were simplified to avoid using python
and the .bat file versions were removed, matching upstream SDL. (#24907)addRunDependency/removeRunDependency now assert in debug builds if
they are not passed an id parameter. We have been issuing warnings in
this case since 2012 (f67ad60), so it seems highly unlikely anyone is not
passing IDs here. (#24890).-sMODULARIZE setting generates a factory function that must be called
before the program is instantiated that run. However, emscripten previously
had very special case where this instantiation would happen automatically
(with no parameterization) under certain specific circumstances: When
-sMINIMAL_RUNTIME, -sSINGLE_FILE and -sMODULARIZE were used in
combination with default html output. This special case was removed. If you
want to instantiate the module on startup you can still do so by adding a call
the factory function in --extern-post-js. (#24874)MINIMAL_RUNTIME_STREAMING_WASM_COMPILATION is used
when not generating html output. This was always incompatible but previously
ignored. (#24849)MINIMAL_RUNTIME_STREAMING_WASM_COMPILATION or
MINIMAL_RUNTIME_STREAMING_WASM_INSTANTIATION are used with SINGLE_FILE.
These are fundamentally incompatible but were previously ignored. (#24849)--export-es6 flag was added to file_packager.py available when run
standalone, to enable ES6 imports of generated JavaScript code (#24737)#! line that emscripten, under some circumstances, will add to the
generated JS code no longer injects the --experimental-wasm-bigint node
flag. This flag is not needed on recent versions of node, and in fact
errors there, so it's not possible to know if it's safe to include. (#24808)-sMODULARIZE mode the factory function will now always return a promise,
even when WASM_ASYNC_COMPILATION is disabled. This is because emscripten
has other features that might also return async module creation (e.g. loading
files over the network, or other users of the addRunDependency API). For
consistency and simplicity we now always return a promise here. (#24727)fsblkcnt_t and fsfilcnt_t types used by statfs/statvfs were
changed from 32-bit to 64-bit. (#24769)-sTEXT_DECODER=0 was removed, due to widespread support for
TextDecoder. The remaining valid values for this setting are =1
(conditional use of TextDecoder with fallback) and =2 (unconditional use
of TextDecoder). (#24700)emdump tool/script was removed. This tool was mostly useful for analyzing
asm.js code, which emscripten has not generated in a long time now.-fprofile-instr-generate -fcoverage-mapping. (#24160)ENVIRONMENT setting will now be automatically updated to include
worker if multi-threading is enabled. (#24525)HEADLESS option. It tried to simulate a minimal browser-like
environment before browser engines had real headless modes. For headless
testing, users are now encouraged to use
Playwright, Puppeteer or
Node.js with JSDOM instead. You can also
use browser headless mode with emrun as follows:
emrun --browser=chrome --browser-args=--headless [..]
for chrome, or
emrun --browser=firefox --browser-args=-headless [..]
for firefox. (#24537)async library functions are no longer automatically
wrapped with WebAssembly.Suspending functions. To automatically wrap library
functions for use with JSPI they must now explicitly set
myLibraryFunction__async: true. (#24550)size_t in Embind, since it was also inadvertently
affecting unsigned long on wasm64. Both will now match the behaviour of
other 64-bit integers on wasm64 and will be passed as bigint instead of
number to the JavaScript code. (#24678).pc files so they will show up, for
example, when you run pkg-config --list-all or pkg-config --cflags <portname>. Bare in mind that the correct PKG_CONFIG_PATH needs to be set for
this to work. One way to do this is to run emmake pkg-config. (#24426)Module['_malloc']) prior to instantiation will no longer work. In
debug builds we generate stub functions that can detect this case. (#24384)-sASYNCIFY_LAZY_LOAD_CODE setting was deprecated. This setting was
added as an experiment a long time ago and as far we know has no active users.
In addition, it cannot work with JSPI (the future of ASYNCIFY). (#24383)-sUSE_WEBGPU was deprecated in favor of the external port Emdawnwebgpu, a
fork of Emscripten's original bindings, implementing a newer, more stable
version of the standardized webgpu.h interface. Please try migrating using
--use-port=emdawnwebgpu. If you find issues, verify in the latest
nightly release and file feedback
with Dawn. (Emdawnwebgpu is maintained as part of Dawn, the open-source
WebGPU implementation used by Chromium, but it is still cross-browser.)-sMAYBE_WASM2JS setting was removed. This was originally added for
debugging purposes, and we now have -sWASM=2 for folks that want to be able
to fall back to js if wasm fails. (#24176)responseUrl is added to emscripten_fetch_t. This is notably
usable for obtaining resolved URL, in line with JS XMLHttpRequest.responseURL
field. (#24414)emscripten_fetch_get_response_headers_length now excludes the trailing
null character from the length calculation to match the documented behaviour.
(#24486)--closure=1 can now be used while preserving readable function names with
-g2 or -g.UTF8ToString, UTF16ToString and UTF32ToString take a new
optional ignoreNul parameter that allows to ignore the NUL characters and
read the entire string up to the specific byte length. (#24487)-sUSE_SDL=2) or
directly (e.g. by running ./embuilder build sdl2). (#24306)InternalError, BindingError,
count_emval_handles) and from libbrowser.py (requestFullscreen,
requestFullScreen, createContext, getUserMedia, setCanvasSize) are no
longer exported by default. They can be exported using
-sEXPORTED_RUNTIME_METHODS=requestFullscreen, for example. (#24223, #24269)-sSAFE_HEAP and
-sSUPPORT_BIG_ENDIAN features. (#24283)-sWASM_WORKERS and -sAUDIO_WORKLET no longer generate
separate .ww.js and .aw.js files. This is similar to the change that was
already made for pthreads in #21701. This saves on complexity, code size and
network requests. (#24163, #24190)settings.CLOSURE_ARGS
(#24192)val now requires a pointer policy when using pointers. e.g.
(val v(pointer, allow_raw_pointers()).-sWASM_ESM_INTEGRATION. This is currently only supported in node behind a
flag and not in any browsers. (#23985)Module['preRun'] or Module['postRun'], or
using addOnPreRun(), addOnInit(), addOnPostCtor(), addOnPreMain(),
addOnExit(), or addOnPostRun(), are now enqueued and executed following
the order of registration (i.e. Module['preRun'] = [a, b], or equivalently
addOnPreRun(a); addOnPreRun(b); will run a then b; the previous behavior
was to run b then a). While this might be a breaking change for some users,
the intention is to be more consistent by making those callbacks match the
behavior of Module['preInit'] and compile time callbacks (rather than the
contrary, as we generally expect an array of functions to be executed left to
right). (#24012)-sSTRICT and
-sMINIMAL_RUNTIME. If you need to access those from outside the module code
you can export them by adding them to -sEXPORTED_RUNTIME_METHODS. For
example, -sEXPORTED_RUNTIME_METHODS=HEAP8,HEAPU32 (if you need HEAP8 and
HEAPU32). (#24079)-sSOURCE_MAP_PREFIXES=["<old>=<new>"] with -gsource-map.
Alternatively, you can now embed the sources content into the source map file
using -gsource-map=inline. (#23741)__file__ builtin now works in the emscripten config file.
(#23973)__errno_location if needed.$demangle JS library function.
(#23975)-sSOURCE_PHASE_IMPORTS. This is currently experimental and not yet
implemented in browsers. (#23175)FS.allocate API was removed. This was originally intended to
implement the fallocate/posix_fallocate system calls, but without the ability
to punch holes (FALLOC_FL_PUNCH_HOLE) the FS.truncate API is sufficient
for resizing files.-sUSE_SDL=3. This port
is still experimental. (#23630)--output_eol command line flag was renamed --output-eol for
consistency with other flags. The old name continues to work as an alias.
(#20735)--use-port=contrib.lua) to easily embed the Lua
scripting language in any C/C++ Emscripten project (#23682)USE_ES6_IMPORT_META settings was removed. This setting was always
on by default, but now it cannot be disabled. This setting was originally
added in 2019 as a temporary measure while engines and bundlers learned to
deal with import.meta. (#23171)--target and --sysroot argument that would normally be injected by
emcc itself. This enables support for C++20 in cmake projects. (#21987)EM_LOG_C_STACK flag to emscripten_log was deprecated and the helper
file on which it was based (emscripten-source-map.min.js) deleted. This
feature (userspace source map parsing in logs) was never ported to wasm
source maps, so it has not worked in many years, and there have been no
requests for it. This has no impact on the source map support in browser
devtools. (#23553)wasmfs_create_fetch_backend now
takes a second parameter (uint32_t chunk_size) to configure the size of
each chunk. If a file is read a few times with random accesses, a small
chunk size will minimize bandwidth; if a file is read in larger contiguous
ranges, a larger chunk size will reduce the number of requests. (#23021)-sWASM_LEGACY_EXCEPTIONS=0, now uses the
LLVM backend implementation rather than the previously used Binaryen
translator
(https://github.com/WebAssembly/binaryen/blob/main/src/passes/TranslateEH.cpp).
(#23469) No specific action from the user is required.-msimd128 -mavx2
to enable targeting AVX2.src/ were renamed from library_foo.js to
lib/libfoo.js. They are still included via the same -lfoo.js flag so
this should not be a user-visible change. (#23348)-DEMSCRIPTEN_FORCE_COMPILERS=ON.emscripten_webgl_create_context now displays a warning message when there is
a conflict between the majorVersion requested and the WebGL support defined
via linker flags (MIN_WEBGL_VERSION and MAX_WEBGL_VERSION). This warning
will be turned into a hard failure in a future release. (#23372, #23416)-sWASM_LEGACY_EXCEPTIONS option is added. (#23365) If true, it will emit
instructions for the legacy Wasm exception handling proposal
(https://github.com/WebAssembly/exception-handling/blob/main/proposals/exception-handling/legacy/Exceptions.md),
and if false, the new standardized exception handling proposal
(https://github.com/WebAssembly/exception-handling/blob/main/proposals/exception-handling/Exceptions.md).
This option defaults to true, given that major web browsers do not support the
new proposal by default yet. This option replaces the existing
-sWASM_EXNREF, whose meaning was the opposite.MIN_SAFARI_VERSION setting) (#23312). This has several effects:
-mno-nontrapping-fptoint flag. (#23007)WASM_BIGINT feature is enabled by default. This has the effect that
Wasm i64 values are passed and returned between Wasm and JS as BigInt values
rather than being split by Binaryen into pairs of Numbers. (#22993)BULK_MEMORY feature is enabled by default. memory.copy and
memory.fill instructions are used in the implementation of C memcpy and
memset, and Clang may generate them elsewhere (#22873). It can be
disabled with the -mno-bulk-memory -mno-bulk-memory-opt flags.-sMODULARIZE we now assert if the factory function is called with
the JS new keyword. e.g. a = new Module() rather than b = Module().
This paves the way for marking the function as async which does not allow
new to be used. This usage of new here was never documented and is
considered an antipattern. (#23210)PATH.basename() no longer calls PATH.normalize(), so that
PATH.basename("a/.") returns "." instead of "a" and
PATH.basename("a/b/..") returns ".." instead of "a". This is in line with
the behaviour of both node and coreutils, and is already the case when using
NODERAWFS". (#23180)-sMODULARIZE mode is now marked as async
when WASM_ASYNC_COMPILATION is enabled (the default). This allows us to use
await during module creation. One side effect of this is that code in
--post-js files will now be delayed until after module creation and after
main runs. This matches the existing behaviour when using sync instantation
(-sWASM_ASYNC_COMPILATION=0) but is an observable difference. (#23157)POLYFILL_OLD_MATH_FUNCTIONS setting was removed. The browser versions
that require these polyfills are no longer supported by emscripten so the
polyfills should never be needed. (#23262)-lfoo.js. This works like the
existing --js-library flag but will search the library path (all paths
specified with -L) for libfoo.js. (#23338)mallinfo struct members are now defined as size_t which makes them
compatible with larger memories, and is also how linux defines them. (#23368)-O0 and/or -sASSERTIONS). This means that
things like double-free will be detected in these builds. Previously this was
only true with -sASSERTIONS=2. (#23330)--proxy-to-worker no longer contains support for
reading the ?noProxy URL parameter (this was not documented or tested).
(#23297)std::basic_string (https://github.com/llvm/llvm-project/pull/72694), the
support for std::basic_string<unsigned char> was removed from embind.
(#23070)MEMORY64 setting is no longer experimental. At time of writing all
browsers still require a flag to run the resulting binaries but that should
change in the coming months since the proposal is now at stage 4. (#22864)-Wnontrivial-memaccess warning has been updated to also warn about
passing non-trivially-copyable destination parameter to memcpy,
memset and similar functions for which it is a documented undefined
behavior (#22798). See https://github.com/llvm/llvm-project/pull/111434$HOME/.emscripten_cache when the emscripten
directory is read-only was removed. This automatic behaviour could cause
confusion. Anyone who really wants to use $HOME/.emscripten_cache can
still do so either via an environment variable (EMCC_CACHE) or via a config
file setting CACHE.file_packager.py tool now outputs modern JS (specifically it
includes nullish assignment). If you use this output directly and you want
to support older browsers you may need to transpile it. If you use
file_packager via emcc the output will be transpiled as part of the emcc
output. (#22805)EM_BOOL in the emscripten API has been replaced with C/C++
bool. This change should not be observable since EM_BOOL has been
equivalent to bool since #22157. (#22155)EXPORTED_RUNTIME_METHODS. (#22705)-msimd128 -mavx to
enable targeting AVX..worker.js file. This file was
made redundant back in 3.1.58 and now is completely removed. (#22598)nonnull<ret_val>() to Embind to omit | null from TS definitions
for functions that return pointers.pthread_kill function was fixed to match the spec
and will now run the designated handler on the target thread. (#22467)emscripten_console_trace and emscripten_dbg_backtrace APIs we were
added to console.h. The former simply maps directly to console.trace.
The latter uses dbg() so it writes directly to stderr under node (better for
multi-threaded apps).--emit-minification-map command line flag was added, which can be used
to emit a minification map in the case that import/export minification is
performed (this happens at higher optimization levels). (#22428)Module['quit'] handling. This could be used to override the internal
method for shutting down the program, but it was neither documented nor
tested. Programs that want to intercept the shutting down of a program can
use Module['onExit']. (#22371)NODEJS_CATCH_EXIT setting is now disabled by default. This setting
is only useful under very specific circumstances, and has some downsides, so
disabling it by default makes sense. (#22257).webp) decoding support in file preloading. (#22282)EMSCRIPTEN_ROOT environment
variable, in which case it will assume that SCons will find the binaries in
(its) PATH.emscons to apply the EMSCRIPTEN_ROOT, EMSCONS_PKG_CONFIG_LIBDIR
and EMSCONS_PKG_CONFIG_PATH environment variables. The SCons tool will use
last two to set up PKG_CONFIG_LIBDIR and PKG_CONFIG_PATH respectively.EM_BOOL type changed from int/u32 to bool/u8. This changes the
layout and size of some structs in the emscripten API. (#22157)EMSCRIPTEN_FETCH_WAITABLE flag along with the emscripten_fetch_wait
API were marked a deprecated. These feature have not functions for several
years now. (#22138)read_ function was removed. We now just use readBinary or
readAsync. (#22080)strftime from musl rather than using a custom
JavaScript implementation. (#21379)readAsync function now returns a promise rather than accepting
callback arguments.EXPORTED_FUNCTIONS list can now include JS library symbols even if they
have not been otherwise included (e.g. via DEFAULT_LIBRARY_FUNCS_TO_INCLUDE).
(#21867).worker.js file that is now generated as part
of pthread builds so that is generated alongside the main JavaScript file.
See #21701. ()-sASYNCIFY=2 is setting now deprecated, use -sJSPI instead. (#21824)-sMAIN_MODULE=1 mode no longer exports all the main module symbols on
Module object. This saves a huge amount of generated JS code due the fact
that -sMAIN_MODULE=1 includes all native symbols in your program as well
is from the standard library. The generated JS code for a simple program
in this mode is reduced from from 3.3mb to 0.5mb. The current implementation
of this feature requires wasm-ld to be on the program twice which could have a
noticeable effect on link times. (#21785)-sMODULARIZE mode, the argument passed into the module constructor is
no longer mutated in place. The expectation is that the module instance will
be available via the constructor return value. Attempting to access methods
on the object passed into the constructor will now abort. (#21775):: to escape port option separator (#21710)--extern-pre-js and --extern-post-js code is
now only run on the main thread, and not on each of the workers. (#21750).worker.js file. This
saves on code size and network requests. In order to make this change go
smoothly, without breaking build systems that expect a worker.js, emscripten
will generate an empty .worker.js to give folks time to transition their
deployment scripts. In -sSTRICT mode, this empty file will not be
generated. (#21701)MODULARIZE mode we no longer export the module ready promise as ready.
This was previously exposed on the Module for historical reasons even though
in MODULARIZE mode the only way to get access to the module is to wait on
the promise returned from the factory function. (#21564)stackSave/stackRestore/stackAlloc) are now just regular JS library
function and as such are only included if you explicitly depend on them. If
you use these functions in your JS code you will need to depend on them via
either:
EM_JS_DEPS macro for EM_ASM/EM_JS code.__deps attribute for JS library functions-sDEFAULT_LIBRARY_FUNCS_TO_INCLUDE flag for --pre-js/--post-js
code
(#21555)--emit-tsd. The option --embind-emit-tsd has been
deprecated, use --emit-tsd instead.ASYNCIFY_PROPAGATE_ADD setting, to control whether the ASYNCIFY_ADD
list propagates or not. By default this is enabled; as a result you may see larger
ASYNCIFY builds as more of the function tree may be instrumented than you were
previously manually specifying in ASYNCIFY_ADD. To stop propagation you can
specify functions in the ASYNCIFY_REMOVE list, or to return to the previous
behaviour, disable this setting (set -sNO_ASYNCIFY_PROPAGATE_ADD.) (#21672)unused-command-line-argument warning if
a -s setting is specified more than once on the command line with
conflicting values. In this case the first setting is ignored. (#21464)STRICT mode the HEAPXX symbols (such as HEAP8 and HEAP32) are now
only exported on demand. This means that they must be added to
EXPORTED_RUNTIME_METHODS for them to appear on the Module object. For
now, this only affects users of STRICT mode. (#21439)--memory-init-file (i.e. extracting static
data into an external .mem file). This feature was only available under
wasm2js (-sWASM=0) anyway so this change will only affect users of this
setting. (#21217)INITIAL_HEAP setting is introduced to control the amount of initial
memory available for dynamic allocation without capping it. If you are
using INITIAL_MEMORY, consider switching to INITIAL_HEAP. Note that
it is currently not supported in all configurations (#21071).DEMANGLE_SUPPORT setting and the associated demangle function are
now deprecated since Wasm stack traces always contain demangled symbols these
days. (#21346)EMSCRIPTEN_WEBGL_CONTEXT_HANDLE was changed to unsigned and
the only valid error returned from emscripten_webgl_create_context is
now zero. This allows EMSCRIPTEN_WEBGL_CONTEXT_HANDLE to hold a pointer
to memory even in 2GB+ mode. Since emscripten_webgl_create_context never
returns anything except zero for its errors today this change should not
require any action. (#21268)--use-port option to emcc. This option allows ports to be enabled
by name and is designed to replace all existing -sUSE_XXX settings for
ports. You can use --show-ports to get the list of available ports that
can be used with this new option. (#21214)--pre-js and --post-js files can now opt into being run through the JS
preprocessor. This change was originally landed in #18525, but it got
reverted in #19006. Now it requires explicit opt-in by adding #preprocess to
the top of the JS file. This is useful as it allows things like {{{ POINTER_SIZE }}} and {{{ makeGetValue(..) }}} to be used in pre/post JS
files, just like they can be in JS library files. (#21227)tools/ports/contrib/README.md for details.A first contrib port is
available via --use-port=contrib.glfw3: an emscripten port of glfw written
in C++ with many features like support for multiple windows. (#21244 and
#21276)--use-port=/path/to/my_port.py (#21316)embuilder can now build ports with options as well as external ports using
the same syntax introduced with --use-port
(ex: embuilder sdl2_image:formats=png,jpg) (#21345)# is now ignored.
This is useful when listing exported symbols. (#21330)stackSave, stackRestore,
stackAlloc) are no longer exported by default. Users of these function
now need to depend on them explicitly (either via __deps attributes or via
-sEXPORTED_FUNCTIONS). (#21075)pthreads+EXPORT_ES6 will now emit the worker file as
NAME.worker.mjs rather than .js. This is a necessary breaking change to
resolve other pthreads+EXPORT_ES6 issues in Node.js (because Node.js is
affected by the suffix in some cases). (#21041)-sUSE_SDL=2) now use -isystem rather
then -I. This means that files in user-specified include directories will
now take precedence over port includes. (#21014)main was mistakenly included in debug builds but not in
release builds. (#20971).emscripten config file settings. In the
past we used this to run the java version of closure compiler. If there are
folks who prefer to use the java version of closure compiler for some reason
it should be possible by adding --platform=java to --closure-args or
EMCC_CLOSURE_ARGS but emscripten will no longer do this automatically.
(#20919)--default-obj-ext command line flag was removed. (#20917).bc files as source files. These means that will get
compiled by clang before being passed to the linker. This matches the
behaviour of clang. (#20922)MIN_CHROME_VERSION will now result in build-time error. All of these
browser versions are at least 8 years old now so the hope is that nobody
is intending to target them today. (#20924)SUPPORT_ERRNO setting is now deprecated as it only controlled setting
errno from JS library functions and emscripten no longer requires this.
(#21074)-sMIN_EDGE_VERSION/-sMIN_IE_VERSION was removed. (#20881)/usr/lib/libz.so was passed to emscripten it would silently re-write
this to -lz, which would then search this a libz in its own sysroot. Now
this file is passed though the linker like any other input file and you will
see an unknown file type error from the linker (just like you would with the
native clang or gcc toolchains). (#20886)-sMIN_EDGE_VERSION was removed.
Using -sLEGACY_VM_SUPPORT should still work if anyone still wanted to target
this or any other legacy browser.*glGetProcAddress() family of functions now
requires passing a linker flag -sGL_ENABLE_GET_PROC_ADDRESS. This prevents
ports of native GL renderers from later accidentally attempting to activate
"dormant" features if web browser implementations gain new WebGL extensions in
the future, which *glGetProcAddress() is not able to support. (#20802)devicePixelRatio browser property and changes the size of the canvas
accordingly (including dynamically if the canvas is moved from a 4K screen to
a 2K screen and vice-versa). glfwGetFramebufferSize now properly returns the
canvas size in pixels, while glfwGetWindowSize returns the canvas size is
screen size. By default, this feature is disabled. You can enable it before
creating a window by calling glfwWindowHint(GLFW_SCALE_TO_MONITOR, GLFW_TRUE). You can also dynamically change it after the window has been
created by calling glfwSetWindowAttrib(window, GLFW_SCALE_TO_MONITOR, GLFW_TRUE). (#20584)-sLEGACY_VM_SUPPORT) do not need to ensure their code is closure
compliant. (#20879)-sMALLOC=mimalloc. (#20651)clang or clang++ depending only
on whether emcc or em++ was run. Previously it would determine which to
run based on individual file extensions. One side effect of this is that you
may now see a clang warning when building .c source files using em++:
warning: treating 'c' input as 'c++' when in C++ mode. This also means that
the DEFAULT_TO_CXX setting now only applies when linking and not when
compiling. (#20712)-sPOLYFILL=0 setting. (#20700)BENCHMARK setting. That has not been used by the benchmark suite for
some time now (at least not by default), and is much less useful these days
given lazy compilation in VMs (which makes it impossible to truly benchmark
execution separately from compilation, which BENCHMARK hoped to do).glfwSetWindowSize function no longer switches to fullscreen when the
width/height provided as parameters match the screen size. This behavior
now matches the behavior of SDL and glut. In order to switch to fullscreen,
the client code should invoke Module.requestFullscreen(...) from a user
triggered event otherwise the browser raises an error. (#20600)assert function is no longer available in release builds when
-sSTRICT is used. This should only affect users with custom JS library code
which doesn't use #if ASSERTIONS guards around their assert calls. This
behaviour matches that of MINIMAL_RUNTIME. (#20592)bootstrap script was added. This script is for emscripten
developers and helps take a care of post-checkout tasks such as npm install.
If this script needs to be run (e.g. because package.json was changed, emcc
will exit with an error. (#19736)new together with std::nothrow no
longer aborts if the allocation fails. Instead nullptr is returned now.
This does not change the behavior of regular usage of new.MIN_CHROME_VERSION was increased from 75 to 85 and default
MIN_FIREFOX_VERSION was increased from 68 to 79 to allow Emscripten
to use some ES2021 features for smaller JavaScript code size. (#20549)Set-ExecutionPolicy command. (#20416)emscripten::val now supports C++20 co_await operator for JavaScript
Promises. (#20420)noExitRuntime global is now a JS library symbol that will only be
included as needed. User of noExitRuntime will now need to declare a
dependency on it. It will get implicitly included if noExitRuntime is part
of INCOMING_MODULE_JS_API. (which it is by default), or it can be added to
either DEFAULT_LIBRARY_FUNCS_TO_INCLUDE or noExitRuntime. (#20336)-sMEMORY64. (#20276)emscripten/html5.h that correspond the WebIDL long type are
now represented as int rather than long types so that they are 32-bit wide
on both wasm32 and wasm64. (#20290)EM_JS and EM_ASM that are present in side module now have their syntax
validated at build time. (#20258)MAIN_THREAD_EM_ASM_PTR macro added for code that returns a pointer. This
mirrors the existing EM_ASM_PTR. (#20261)raise cals. (#20257)emscripten::val now prevents accidental access to the underlying JavaScript
value from threads other than its owner. This already didn't work correctly
in majority of cases, but now it will throw a clear assertion failure. (#20344)emscripten::val can now be iterated over with a C++ range-based for loop.
(#20364)wasmTable global is now a JS library function that will only be included
as needed. Code that references wasmTable will no need to declare a
dependency on it. It can also be explicitly included using
-sEXPORTED_RUNTIME_METHODS=wasmTable.--minify=0 command line flag will now preserve comments as well as
whitespace. This means the resulting output can then be run though closure
compiler or some other tool that gives comments semantic meaning. (#20121)-sSTRICT now implies -sINCOMING_MODULE_JS_API=[] which is generally good
for code size. If you -sSTRICT you now need to be explicit about the
incoming module APIs you are supplying. Users who supply symbols on the
incoming module but forget to include them in -sINCOMING_MODULE_JS_API
will see an error in debug builds so this change will not generate any
silent failures.__deps and __async are now type checked so
that errors are not silently ignored.USE_GLFW settings now defaults to 0 rather than 2. This matches other
other settings such as USE_SDL that default to 0 these days and also matches
the existing behaviour for MINIMAL_RUNTIME and STRICT mode.
If you use GLFW you now need to explicitly opt into it using -sUSE_GLFW or
-lglfw. (#19939)TABLE_BASE was introduced that can be used to place static
function addresses (table slots) at a certain offset. This defaults to 1
which is the previously fixed value. (#20149)-Wunused-variable improved,
which may require changes in user code (see #20169).mergeInto, to the more specific addToLibrary. This new function does not
require the passing of LibraryManager.library as a first argument. The old
mergeInto continues to exist for backwards compat.--log_html option was removed from emrun. This option was already not
working with python3.8 or above so we hope is safe to say that nobody was
relying on it.EM_LOG_FUNC_PARAMS flag to emscripten_log/emscripten_get_callstack
has been deprecated and no longer has any effect. It was based on a
long-deprecated JS API. (#19820)read_ and readAsync functions no longer handle data URIs.
(Higher-level functions are expected to handle that themselves, before calling.)
This only affects builds that use -sSINGLE_FILE or --memory-init-file.
(#19792)asm property of the Module object (which held the raw exports of the
wasm module) has been removed. Internally, this is now accessed via the
wasmExports global. If necessary, it is possible to export wasmExports
on the Module object using -sEXPORTED_RUNTIME_METHODS=wasmExports. (#19816)--embind-emit-tsd <filename> option.__i53abi decorator. When this is set to true, i64 values are
automatically converted to JS numbers (i53) at the JS boundary. Parameters
outside of the i53 will show up as NaN in the JS code (#19711)-sMIN_NODE_VERSION=101900 which will apply the previous minimum version of
10.19.0. (#19192).EMCC_LOGGING=0.-sMAIN_MODULE. Instead stub functions
will be included that fail at runtime. This matches the behaviour of other
libc functions that we don't implement. For those that prefer to get a linker
error we have the -sALLOW_UNIMPLEMENTED_SYSCALLS settings. (#19527)modifyFunction helper in parseTools.js was renamed to
modifyJSFunction and its callback function no longer takes the name of the
function being modified. The name is not relevant for JS library functions
and can be safely ignored.CHECK_NULL_WRITES) was added to disabled the checking of
address zero that is normally done when STACK_OVERFLOW_CHECK is enabled.
(#19487)_emscripten_out(), _emscripten_err() and _emscripten_dbg() functions
declared in emscripten/console.h no longer have the underscore prefix and
are now documented. (#19445)err() function will now bind to console.error by default rather
than console.warning. For debugging/tracing/logging we recommend the
dbg() function instead. (#19326)WASM2C options has been removed. All known users are using upstream wabt
these days anyhow.dladdr function will now always return an error rather than filling in
dummy values. (#19319)-sDYNAMIC_EXECUTION=0 was removed. This restriction was being enforced
unnecessarily since dynamic linking has not depended on eval() for a while
now.EM_PYTHON_MULTIPROCESSING environment variable no longer has any effect.
This was added a temporary fallback but should no longer be needed. (#19224)tools/deps_info.py has been
removed and the existing __deps entries in JS library files can now be used
to express JS-to-native dependencies. As well being more precise, and
extensible via user-supplied JS libraries, this also speeds up link times
since we no longer need scan linker inputs using llvm-nm. It also
completely removes the need for the REVERSE_DEPS settings which has now
been deprecated. (#18905)USES_DYNAMIC_ALLOC setting has been deprecated. You can get the same
effect from -sMALLOC=none. (#19164)The following JavaScript runtime functions were converted to JavaScript library functions:
If you use any of these functions in your JS code you will now need to include them explicitly in one of the following ways:
__deps entry in your JS library file (with leading $)DEFAULT_LIBRARY_FUNCS_TO_INCLUDE (with leading $)EXPORTED_FUNCTIONS (without leading $)-sLEGACY_RUNTIME to include all of them at once.FS.loadFilesFromDB and FS.saveFilesToDB were removed. We think it's
unlikely there were any users of these functions since there is now a separate
IDBFS filesystem for folks that want persistence. (#19049)
allocateUTF8 and allocateUTF8OnStack library function moved to
library_legacy.js. Prefer the more accurately named stringToNewUTF8 and
stringToUTF8OnStack. (#19089)
SDL_image port was updated to version 2.6.0.
-z arguments are now passed directly to wasm-ld without the need for the
-Wl, prefix. This matches the behaviour of both clang and gcc. (#18956)
Reverted #18525 which runs the JS pre-processor over files passed via
--pre-js and --post-js. It turned out this change caused issue for several
folks who had JS files with lines that start with # so can't be run through
the pre-processor. If folks want to re-enable this we can looks into ways to
make it conditional/optional.
The {{{ cDefine('name') }}} helper macro can now be simplified to just {{{ cDefs.name }}}.
EM_JS functions defined in other object files. This was a bug
that was introduced when LLD_REPORT_UNDEFINED was enabled by default back in
3.1.28. (#18928)-pthread
flag. The -sUSE_PTHREADS setting still works but is marked as legacy and
will generate a warning in -sSTRICT mode.-sMODULARIZE, we no longer internally catch
unhandled promise rejections or exit status code. That is to say the,
NODEJS_CATCH_REJECTION and NODEJS_CATCH_EXIT are no longer compatible
with -sMODULARIZE.other.test_cpp_module. (#18915)sys/sysctl.h compatibility header. We don't implement the function
it defines. (#18863)LLD_REPORT_UNDEFINED setting has been removed. It's now essentially
always enabled. (#18342)-sEXPORT_KEEPALIVE to export symbols. When using
MINIMAL_RUNTIME, the option will be disabled by default.
This option simply exports the symbols on the module object, i.e.,
Module['X'] = X;Atomics.waitAsync.
(#18861)emscripten_proxy_async_with_callback API was replaced with a simpler
emscripten_proxy_callback API that takes a second callback to be called if
the worker thread dies before completing the proxied work.-sEXCEPTION_STACK_TRACES which will display a stack
trace when an uncaught exception occurs. This defaults to true when
ASSERTIONS is enabled. This option is mainly for the users who want only
exceptions' stack traces without turning ASSERTIONS on. (#18642 and #18535)SUPPORT_LONGJMP's default value now depends on the exception mode. If Wasm
EH (-fwasm-exceptions) is used, it defaults to wasm, and if Emscripten EH
(-sDISABLE_EXCEPTION_CATCHING=0) is used or no exception support is used, it
defaults to emscripten. Previously it always defaulted to emscripten, so
when a user specified -fwasm-exceptions, it resulted in Wasm EH + Emscripten
SjLj, the combination we do not intend to support for the long term.Module object by default. For
example, previously if you were using Module._malloc but not explicitly
including _malloc in EXPORTED_FUNCTIONS, it might have been exported
anyway due to internal use of malloc within the JS library code. (#18564)STACK_SIZE, STACK_ALIGN, POINTER_SIZE, and ASSERTIONS JavaScript
globals were removed by default. In debug builds a clear error is shown if
you try to use these. (#18503)-sEXPORT_ALL can now be used to export symbols on the Module object
when used with -sMINIMAL_RUNTIME and -sMODULARIZE together. (#17911)-sSTACK_SIZE by
default. Set DEFAULT_PTHREAD_STACK_SIZE explicitly to override this.
(#18479)buffer JavaScript variable was removed. This underlying buffer is
still accessible via wasmMemory.buffer or HEAPXX.buffer. In debug builds,
a clear error is shown if you try to use it. (#18454)SDL_events.h) you will now need to add -sUSE_SDL explicitly at
compile time. If you include the SDL headers with the directory name included
(e.g. SDL/SDL_events.h) you will not be affected by this change. (#18443)PROXY_TO_PTHREAD whereby certain async operations on the main
thread would cause the whole program to exit, even when the proxied main
function was still running. (#18372)Module.pthreadPoolReady promise for the PTHREAD_POOL_DELAY_LOAD
mode that allows to safely join spawned threads. (#18281)PTHREAD_POOL_SIZE) or proxying (PROXY_TO_PTHREAD) options. (#18305)LLD_REPORT_UNDEFINED is now enabled by default. This makes undefined symbol
errors more precise by including the name of the object that references the
undefined symbol. The old behaviour (of allowing all undefined symbols at
wasm-ld time and reporting them later when processing JS library files) is
still available using -sLLD_REPORT_UNDEFINED=0. (#16003)EMSCRIPTEN_ROOT. This
setting has long been completely ignored by emscripten itself. For
applications that wish to know where emscripten is installed looking for
emcc in the PATH has long been the recommended method (i.e. which emcc).
(#18279)emscripten_get_now clocks between main
thread and pthreads.
This also changes the absolute value returned by the function, but it shouldn't
affect correct usages as the function has always returned different values on
different platforms, and is clearly documented as "only meaningful in
comparison to other calls to this function". (#18267)BINARYEN_ROOT, LLVM_ROOT, NODE_JS)
are not set. Allows emscripten to run with an empty config file given the
right tools in the PATH. (#18289)-sEXPORT_ES6/*.mjs on Node.js. (#17915)STACK_SIZE was reduced from 5MB to 64KB. Projects that use more
than 64Kb of stack will now need specify -sSTACK_SIZE at link time. For
example, -sSTACK_SIZE=5MB can be used to restore the previous behaviour.
To aid in debugging, as of #18154, we now also place the stack first in memory
in debug builds so that overflows will be immediately detected, and result in
runtime errors. This change brings emscripten into line with wasm-ld and
wasi-sdk defaults, and also reduces memory usage by default. In general,
WebAssembly stack usage should be lower than on other platforms since a lot of
state normally stored on the stack is hidden within the runtime and does not
occupy linear memory at all. The default for DEFAULT_PTHREAD_STACK_SIZE was
also reduced from 2MB to 64KB to match.MIN_SAFARI_VERSION)
was updated from 12.0 to 14.1, and support for the old EdgeHTML engine
(MIN_EDGE_VERSION) was removed by default. If you want to continue to
support these older engines you can use these settings
(-sMIN_SAFARI_VERSION=120000 and/or -sMIN_EDGE_VERSION=44) to revert to
the previous defaults, which will result in the new proposals being disabled.
Note that in order to avoid support for the sign-extension emscripten uses
a binaryen pass, so targeting older browsers requires the running of wasm-opt
and is therefore incompatible with ERROR_ON_WASM_CHANGES_AFTER_LINK (i.e.
fast linking). (#17690)--reproduce command line flag (or equivalently EMCC_REPRODUCE
environment variable). This options specifies the name of a tar file into
which emscripten will copy all of the input files along with a response file
that will allow the command to be replicated. This can be useful for sharing
reproduction cases with others (inspired by the lld option of the same name).
(#18160)TOTAL_STACK setting was renamed to STACK_SIZE. The old name will
continue to work as an alias. (#18128)print/printErr via -sEXPORTED_RUNTIME_METHODS is deprecated in
favor of out/err. The former symbols are supposed to be used with
-sINCOMING_MODULE_JS_API instead. (#17955)-Wcast-function-type)
are now stricter. This warning is intended to help with CFI errors but also
helps wasm builds since wasm traps on such type mismatches in indirect calls.
We recommend that users enable it to prevent such errors (which can be hard to
debug otherwise). The older (less strict) behavior is also still possible with
-Wcast-function-type -Wno-cast-function-type-strict (or
-Wno-error=cast-function-type-strict if you want the warnings to be visible
but not errors). See https://reviews.llvm.org/D134831-fwasm-exceptions), when ASSERTIONS is enabled,
uncaught exceptions will display stack traces and what() message. (#17979 and
#18003)EM_JS_DEPS macro in the em_macros.h header. Adding dependencies in this
way avoids the need to specify them on the command line with
-sDEFAULT_LIBRARY_FUNCS_TO_INCLUDE. (#17854)__EMSCRIPTEN_major__/minor__/tiny__ macros are no longer defined on the
command line but require <emscripten.h/> (or just <emscripten/version.h>
to be included. (#17883)emcc -r + -flto is no longer supported.
emcc -r will now always use lld to link to an object file. This matches the
behavior of upstream llvm where bitcode linking using lld does not exist.
The recommend way to combine bitcode input is to use library files (ar
archives). See #13492 for more details.-Oz or -Os will no longer pass -fno-inline-functions to clang and
instead rely on clang's normal inline heuristics for these optimization
levels. -fno-inline-functions can be passed explicitly if needed.-std=c++14 (or technically
-std=gnu++14) to revert to the previous default.-Wclosure warning flags
rather than via a specific/custom CLOSURE_WARNINGS setting. The old
setting continues to work but will issue a deprecation warning.
If you link with -Werror but you don't want closure warnings to be errors
you can add -Wno-error=closure or -Wno-closure.LEGACY_RUNTIME setting is no longer enabled by default. If you use any
of these legacy runtime functions (except in library code with explicit
dependencies) then you would need to set LEGACY_RUNTIME on the command line
or add the ones you need to DEFAULT_LIBRARY_FUNCS_TO_INCLUDE:
getTempRet0/setTempRet0 helper functions are now implemented directly
in WebAssembly, rather than supplied by the JS host. This simplifies the
wasm/JS interface. These functions are no longer exported in all cases. If
your code directly calls these functions from JS, you can add them to
-sEXPORTED_RUNTIME_METHODS.sys/soundcard.h and sys/ptrace.h. (#17704)-g -gsource-map. (#17484)align argument to the makeGetValue/makeSetValue JS library macros was
removed (and replaced with an assert) as it had no uses internally and was
removed (and replaced with an assert) as it had now uses internally and was
untested.calledMain global variable from the JS runtime. Folks who
want to know when main is done can use Module[postRun].-Werror builds will now fail
in the presence of JS compiler warnings. As usual -Wno-js-compiler and
-Wno-error=js-compiler) can be used to control these warnings. (#17365)EXPORTED_RUNTIME_METHODS
it is no longer necessary to also add them to
DEFAULT_LIBRARY_FUNCS_TO_INCLUDE. This change allows us to transition
runtime functions to JS library functions without the need for folks to add
DEFAULT_LIBRARY_FUNCS_TO_INCLUDE. (#17369)LEGACY_RUNTIME which is enabled by default. When LEGACY_RUNTIME is
disabled (which it may be in the future) these symbols would only be included
if there were explicitly exported via EXPORTED_RUNTIME_METHODS or added to
DEFAULT_LIBRARY_FUNCS_TO_INCLUDE. LEGACY_RUNTIME is disabled by default
in STRICT mode so this change only affects users of STRICT mode. (#17370,
#17403)run runtime function is no longer exported by default. It can be added
to EXPORTED_RUNTIME_METHODS if needed.DEFAULT_LIBRARY_FUNCS_TO_INCLUDE or
EXPORTED_RUNTIME_METHODS if you want to use them outside of JS library code.time_t was restored 64-bit after being converted to 32-bit in
3.1.11. (#17401)hasExportedFunction has been replaced with
hasExportedSymbol, which takes an unmangled (no leading underscore) symbol
name.EMCC_READ_METADATA=binaryen in the environment. (#17337)BigInt64Array so -sWASM_BIGINT can be used in Safari
v14. (#17103)-print-file-name and reports the correct library paths in
-print-search-dirs.tools/file_packager no longer generates (or requires) any "pre-js" code when
running in --embed-file mode. Instead the embedded files are loaded at
static constructor time.WASM_BIGINT feature
requires and will automatically set the defaults accordingly. (#17163)noexcept. (#17140)main function now gets mangled (by clang) in the
same way as with other wasm targets. This means that within the wasm module
the name of the main function can now be __main_argc_argv, but, since we
still export this to JS as _main, this should not be a user-visible change.emscripten_runtime_keeplive_push() and emscripten_runtime_keeplive_pop()
are now exposed to native code and can be used to keep the runtime alive
without immediately unwinding the event loop (as
emscripten_exit_with_live_runtime() does). (#17160)--use-preload-cache now only invalidates the
cache if the data contents has changed. (#16807)*) with getValue/setValue library functions. (#17028)emscripten_get_compiler_setting was changed from int
to long so that it is compatible with MEMORY64. The return value of this
function sometimes contains a pointer value so int is not sufficiently
wide under wasm64. (#16938)EM_BUILD_VERBOSE environment variable only affects test code these days
and therefore was renamed to EMTEST_BUILD_VERBOSE. (#16904)-sSHELL_FILE setting, which (unlike the --shell-file command line
options) we believe was never tested or externally used, has been removed.
(#16589)-sEXCEPTION_CATCHING_ALLOWED when not linking as C++. (#16609)-s) are now type checked. For example, passing a
string to a boolean setting will now generate an error (e.g.
-sEXIT_RUNTIME=foo). Previously, the value of foo would have have been
interpreted as non-zero and accepted as valid. (#16539)library_glfw.js. This changes
the vertical scroll amount for GLFW 3. (#16480)-sASMFS
settings. The new wasmfs filesystem is far enough along that it seems clear
that ASMFS will not need to be revived.munmap that was introduced in 3.1.5. The deadlock would
occur in multi-threaded programs when a partial unmap was requested (which
emscripten does not support). (#16413)EMMAKEN_COMPILER, EMMAKEN_CFLAGS, and
EMMAKEN_NO_SDK environment variables. These are all legacy and redundant
in the face of other settings/flags:
EMMAKEN_COMPILER -> LLVM_ROOT in the config settingsEMMAKEN_CFLAGS -> EMCC_CFLAGSEMMAKEN_NO_SDK -> standard -nostdlib and -nostdinc flags--generate-config option, in case that is what they want.
(#13962)allocate() runtime function. For backwards
compatibility with external JS code we still include this function by default
but it will no longer be included in -sSTRICT mode. Usages of this function
are generally best replaced with _malloc, stackAlloc or allocateUTF8.-fnew-alignment and -fshort-wchar).__EMSCRIPTEN_major__, __EMSCRIPTEN_minor__ and __EMSCRIPTEN_tiny__
macros are now available via the emscripten/version.h header file. For the
time being, unless you enable -sSTRICT, these are still also defined
directly on the command line. If you use these macros please make sure you
include emscripten/version.h (or emscripten.h which indirectly includes
it). (#16147)emcc now uses this mode when the --embed-file option is used. If you
use file_packager directly it is recommended that you switch to the new mode
by adding --obj-output to the command line. (#16050)--bind flag used to enable embind has been deprecated in favor of
-lembind. The semantics have not changed and the old flag continues to
work. (#16087)-sSUPPORT_LONGJMP=wasm. This can
be used with Wasm exception support (-fwasm-exceptions), but not with
Emscripten exception support (-fexceptions or
-sDISABLE_EXCEPTION_CATCHING=0). When using Wasm EH with Wasm SjLj, there is
one restriction that you cannot directly call setjmp within a catch
clause. (Calling another function that calls setjmp is fine.)
(#14976 and #16072)POLYFILL, was added which is on by default but can be disabled
(via -sNO_POLYFILL) to prevent emscripten from outputting needed polyfills.
For default browser targets, no polyfills are needed so this option only has
meaning when targeting older browsers.EVAL_CTORS has been rewritten and improved. The main differences from before
are that it is much more capable (it can now eval parts of functions and not
just all or nothing, and it can eval more wasm constructs like globals). It is
no longer run by default, so to use it you should build with -s EVAL_CTORS.
See settings.js for more details. (#16011)wasmX test suites that are defined in test_core.py have been renamed to
coreX to better reflect where they are defined. The old suite names such
as wasm2 will continue to work for now as aliases.-sMIN_CHROME_VERSION=10),
emscripten will now run closure compiler in WHITESPACE_ONLY mode in order to
transpile any ES6 down to ES5. When this automatic transpilation is performed
we generate a warning which can be disabled (using -Wno-transpile) or by
explicitly opting in-to or out-of closure using --closure=1 or
--closure=0. (#15763).EMMAKEN_CFLAGS is favor of EMCC_CFLAGS.parseTools.js. While
emscripten no longer needs any of these functions, there is slim chance that
some external JS library is depending on them. Please file issues if any such
library code is found. The removed/unused functions are:
removePointing, pointingLevels, removeAllPointing, isVoidType,
isStructPointerType, isArrayType, isStructType, isVectorType,
isStructuralType getStructuralTypeParts, getStructuralTypePartBits,
isFunctionDef, isPossiblyFunctionType, isFunctionType, getReturnType,
splitTokenList, _IntToHex, IEEEUnHex, Compiletime.isPointerType,
Compiletime.isStructType, Compiletime.INT_TYPES, isType.shell.html and shell_minimal.html templates no longer override
printErr on the module object. This means error message from emscripten and
stderr from the application will go to the default location of console.warn
rather than console.error. This only affects applications that use the
example shell html files.SIDE_MODULE, MAIN_MODULE or LINKABLE. If you
need to export a hidden symbol you can still do so by adding it to
EXPORTED_FUNCTIONS.__internal: true in JS
system libraries. Such symbols should not be used by external libraries and
are subject to change. As of now we generate warning when external libraries
depend on the these symbols.library_syscall.js and library.js were replaced with
native code stubs (See system/lib/libc/emscripten_syscall_stubs.c). This
should be better for wasm module portability as well as code size. As part
of this change the return value of popen was fixed to return NULL rather
than -1 and the getpwnam family of functions were changed to return an
error rather than throw a JavaScript exception (this behaviour matches what
the other stub functions do). As before, the ALLOW_UNIMPLEMENTED_SYSCALLS
setting controls whether of not these stubs get included at link time, and
STRICT disables this setting.-c) mode. Just like with clang itself, this warning can be
disabled using the flag: -Wno-unused-command-line-argument.__syscall22) to name-based (e.g. __syscall_open). This should not be
a visible change except for folks trying to intercept/implement syscalls
in native code (#15202).EMSCRIPTEN_SYSTEM_PROCESSOR which can be used
to override the default value of CMAKE_SYSTEM_PROCESSOR set by the
toolchain file.EMIT_EMSCRIPTEN_METADATA setting. This setting has
been deprecated for some time now and we don't know of any remaining reasons to
keep it around.Emval.{toHandle, toValue} as well as a C++ method
val::as_handle() to allow passing values between the val class and
EM_JS/ EM_ASM JavaScript snippets. (#15279)EM_ASYNC_JS macro - similar to EM_JS, but allows using await
inside the JS block and automatically integrates with Asyncify without
the need for listing the declared function in ASYNCIFY_IMPORTS (#14728).embuilder tool some of the names of the
libraries have changed (they now match the filenames in the tools/ports/
directory). For example sdl-image is now sdl_image (#14737).-Wl,--allow-undefined or
-Wl,--unresolved-symbols=ignore-all.long double, which is a 128-bit floating-point value
implemented in software, is reduced from 16 to 8. The lower alignment allows
max_align_t to properly match the alignment we use for malloc, which is 8
(raising malloc's alignment to achieve correctness the other way would come
with a performance regression). (#10072)alignMemory function is now a library function and therefore not
included by default. Debug builds will automatically abort if you try
to use this function without including it. The normal library __deps
mechanism can be used to include it, or can be added to
DEFAULT_LIBRARY_FUNCS_TO_INCLUDE.ASYNCIFY to suspend execution until
the library is loaded and then continue on as if dlopen was blocking. For
users who don't want to use ASYNCIFY (which has a size and runtime cost)
there is a async (callback-based) version of the dlopen API available as
emscripten_dlopen() declared in emscripten/emscripten.h. See
docs/api_reference/emscripten.h.rst (or the online version) for more
details.awaited.
When Asyncify is used somewhere in the callstack, previously Embind would
return 0 / null / false / instance with a NULL pointer, making it
impossible to wait for the function to actually finish and retrieve its
result. Now in those cases it will return a Promise instead that will
resolve with the function's return value upon completion. (#11890)d8, js, or jsc is not something that most emscripten users ever want to
do, so including the support code is, more often than not, unnecessary. Users
who want shell support can enable it by including 'shell' in -s ENVIRONMENT
(#14535).ALLOW_UNIMPLEMENTED_SYSCALLS was added. This setting
is enabled by default but, if disabled, will generate link-time errors if
a program references an unimplemented syscall. This setting is disabled
by default in STRICT mode.EXIT_RUNTIME=1 is specified) emscripten programs running
under node will no longer call process.exit() on exit(). Instead they
will simply unwind the stack and return to the event loop, much like they do
on the web. In many cases the node process will then exit naturally if there
is nothing keeping the event loop going.
Note for users of node + pthreads: Because of the way that threads are
implemented under node multi-threaded programs now require EXIT_RUNTIME=1
(or call emscripten_force_exit) in order to actually bring down the process.Buffer.from which was added in v5.10.0. If it turns out
there is still a need to support these older node versions we can
add a polyfill under LEGACY_VM_SUPPORT (#14447).--preload-file in Node.js. (#11785)-lfoo rather
than using their full path. This is in line with how gcc and clang pass system
libraries to the linker. This should not affect any builds unless a project a
happens to have, for example, a file called libc.a in one of its library
paths. This would have the effect of overriding the system library (as it
would with gcc or clang) (#14342).cmake --install (or running the
install target, via make install for example) will install resources into
the sysroot such that they can later be found and used by find_path,
find_file, find_package, etc. Previously the default was to attempt to
install into the host system (e.g /usr/local) which is almost always not
desirable. Folks that were previously using CMAKE_INSTALL_PREFIX to build
their own secondary sysroot may be able to simplify their build system by
removing this completely and relying on the new default.-s settings passed when not linking
(i.e. when compiling with -c). As before this can be disabled with
-Wno-unused-command-line-argument (#14182).ENV to undefined. This is useful for variables, such
as LANG, for which Emscripten normally provides a default value.-g. See
https://reviews.llvm.org/D102999.-Wl,-O0.
This should significantly reduce the size of dwarf debug information in the
wasm binary.<module>.deferred.wasm instead of <module>.wasm.deferred.wasm-ld) now performs string tail merging on any
static string data in your program. This has long been part of the native
ELF linker and should not be observable in well-behaved programs. This
behavior can be disabled by passing -Wl,-O0.fork, vfork, posix_spawn and system now fail with
the errno value ENOSYS (52) rather than EAGAIN (6). This is more
correct, since they will never work and attempting to retry won't help.EXPORT_ES6 will now emit static URLs for main WebAssembly file as well
as for helper Worker used by -pthread that can be statically detected
by modern bundlers at build time. In particular, you no longer have to set
Module.locateFile hook and Module.mainScriptUrlOrBlob settings -
both bundlers and browsers should pick up the required files automatically.
Note: this doesn't yet cover other use-cases that emit external files,
such as dynamic linking, --proxy-to-worker, external memory etc. (#14135)EXPORT_ES6 can now be used in combination with -o [filename].html. (#14165)EXPORT_ES6 no longer requires setting custom EXPORT_NAME too. (#14139)emscripten-version.txt file that is checked into
the repository now reflect the next, upcoming, release once a release is
made. Previously they would continue to reflect the old release until after
we decide to cut the release. Switching to this method allow for a slightly
simpler release process that also allows us to tag a version that contains
the correct version information.-v/--version now includes a -git suffix
(e.g. 2.0.19-git) when running from git checkout (to help distinguish
unreleased git versions from official releases) (#14092).-Wunused-command-line-argument warnings introduced
in 2.0.19.-s settings are specified in
compile-only (-c) mode. Just like with clang itself, this warning can be
disabled using the flag: -Wno-unused-command-line-argument.-s MAIN_MODULE emscripten will now error on undefined
symbol by default. This matches the behaviour of clang/gcc/msvc. This
requires that your side modules be present on the command line. If you do not
specify your side modules on the command line (either directly or via
RUNTIME_LINKED_LIBS) you may need to add -s WARN_ON_UNDEFINED_SYMBOLS=0 to
avoid errors about symbol that are missing at link time (but present in your
side modules provided at runtime). We hope that this case is not common and
most users are building with side modules listed on the command line (#14060).RUNTIME_LINKED_LIBS setting is now deprecated. It's better to simply
list dynamic library dependencies directly on the command line.makeBigInt function was removed from the emscripten runtime since it
had no internal users.EXTRA_EXPORTED_RUNTIME_METHODS is deprecated in favor of just using
EXPORTED_RUNTIME_METHODS.MAIN_MODULE=2 the linker will now automatically include
any symbols required by side modules found on the command line. This means
that for many users of MAIN_MODULE=2 it should no longer be necessary to
list explicit EXPORTED_FUNCTIONS. Also, users of MAIN_MODULE=1 with
dynamic linking (not dlopen) who list all side modules on the command line,
should be able to switch to MAIN_MODULE=2 and get a reduction in code size.MAIN_MODULE it is now possible to warn or error on
undefined symbols assuming all the side modules are passed at link time. This
means that for many projects it should now be possible to enable
ERROR_ON_UNDEFINED_SYMBOLS along with MAIN_MODULE.--closure) is now supported when using dynamic
linking (building with -s MAIN_MODULE) (#13880)EM_CONFIG inline (python code in the environment variable itself)
is no longer supported (#13855). This has been long deprecated but finally
completely removed.-g4, which is a little confusing as it does not do more than -g3
but instead emits source maps instead of DWARF. -g4 will now warn. A new
flag -gsource-map enables source maps without warning.-llibc rather than -lc will no longer work.foo.a via -lfoo will no longer work.
(libraries found via -l have to start with lib)-flegacy-pass-manager (and -Wl,--lto-legacy-pass-manager when doing LTO)
(note however that neither workaround affects the building of system
libraries, unless you modify emscripten or build them manually). (#13427)EM_PYTHON_MULTIPROCESSING=1 that can be set
to revert back to using Python multiprocessing, in case there are reports of
regressions (that variable is intended to be temporary). (#13493)-sBINARYEN_EXTRA_PASSES=--one-caller-inline-max-function-size=1 (#13744).--emit-symbol-map for JS targets.
When -s WASM=2 is used. Two symbols are generated:
[name].js.symbols - storing Wasm mapping[name].wasm.js.symbols - storing JS mapping
In other cases a single [name].js.symbols file is created.-s EXPORTED_FUNCTIONS=foo,bar--llvm-opts command line option. Any
arguments not processed by emcc will be passed through to clang directly
these days.sysconf now more closely match the definitions found in
header files and in upstream musl (#13713).DISABLE_EXCEPTION_CATCHING=2 is now deprecated since it can be inferred from
the presence of the EXCEPTION_CATCHING_ALLOWED list. This makes
DISABLE_EXCEPTION_CATCHING a simple binary option (0 or 1) which defaults to
0 which will be set to 1 internally if EXCEPTION_CATCHING_ALLOWED list is
specified.pathconf now match the definitions found in header files
and/or upstream musl:
_PC_LINK_MAX 3200 -> 8
_PC_SYNC_IO -1 -> 1
_PC_REC_INCR_XFER_SIZE -1 -> 4096
_PC_REC_MAX_XFER_SIZE -1 -> 4096
_PC_SYMLINK_MAX -1 -> 255master to main.newlocale (and new std::locale in C++) with arbitrary names will
now succeed. This is the behaviour of musl libc which emscripten had
previously inadvertently disabled.-g). This doesn't
affect release builds (builds without -g) but allows DWARF debugging of
types defined in system libraries such as C++ STL types (#13078).emscripten_GetProcAddress is now part of libGL. Normally the change is not
noticeable, unless you build in STRICT mode and do not already have -lGL
to link in that library. If not, add -lGL. (#13524)REVERSE_DEPS. This can be used to control how emscripten
decides which reverse dependencies to include. See settings.js for more
information. The default setting ('auto') is the traditional way emscripten
has worked in the past so there should be no change unless this options is
actually used. This option partially replaces the EMCC_ONLY_FORCED_STDLIBS
environment variable which (among other things) essentially had the effect of
setting REVERSE_DEPS to be 'all'.-fno-unroll-loops.Browser.safeSetInterval and Browser.safeCallback. These
had no callers in emscripten itself or any testing. If there are users of
these functions we could re-enable them with some testing.SDL2_ttf now uses upstream compiled with TTF_USE_HARFBUZ flag.-s AUTO_NATIVE_LIBRARIES=0 is used. This should not affect most builds
in any way since wasm-ld ignores unreferenced library files. Only users
of the --whole-archive linker flag (which is used when MAIN_MODULE=1 is
set) should be affected.emscripten/vr.h and other remnants of WebVR support removed. (#13210, which
is a followup to #10460)RelWithDebInfo will now include debug info (it did not
before, which appears to have been an error), and that Release will
use -O3 instead of -O2 (which is a better choice anyhow). (#13083)emcc -v no longer forces the running the sanity checks. Sanity checks
are always run on first use or can be forced with --check or by setting
EMCC_DEBUG is set in the environment.IMPORTED_MEMORY setting can be used to revert to the old behaviour.
Breaking change: This new setting is required if you provide a runtime
value for wasmMemory or INITIAL_MEMORY on the Module object.--sysroot argument to point clang at
it headers. This should not affect most projects but has a minor effect the
order of the system include paths: The root include path
(<emscripten_root>/system/include) is now always last in the include path.-lSDL2_mixer to just work. (Others like -lSDL2 always worked, but
for SDL2_mixer things were broken because we build multiple variations of
that library.) That link flag is now the same as -s USE_SDL2_MIXER=2.<emscripten/stack.h>:
__sig
specified in the library JavaScript file.MODULARIZE + WASM_ASYNC_COMPILATION=0, that is, modularize mode but with
async compilation turned off, so that startup is synchronous, now returns the
Module object from the factory function (as it would not make sense to return
a Promise without async startup). See #12647wasm-ld). When emcc is run with --post-link it will take a wasm file as
input that perform all the normal post link steps such as finalizing and
optimizing the wasm file and generating the JavaScript and/or html that will
run it.-s ASSERTIONS=2 now implies -s STACK_OVERFLOW_CHECK=2. Previously only
-s ASSERTIONS=1 implied -s STACK_OVERFLOW_CHECK=1.--arg=foo as well as --arg foo. For example
--js-library=file.js.-) to the
program bring run now requires a -- on the command line to signal the
end of emrun arguments. e.g:
emrun filename.html -- --arg-for-page
This is standard behaviour for command line parsing and simplifies the
emrun logic.wasm-emscripten-finalize just for C++ exceptions or longjmp. This
is an ABI change. (#12399)SAFE_HEAP on user JS code using a new Acorn pass, increasing the
coverage of those tests to all JS in the output (#12450).EM_LOG_DEMANGLE is now deprecated. Function names shown in wasm backtraces
are never mangled (they are either missing or demangled already) so demangled
is not possible anymore.em++ rather
than emcc. This matches the behaviour of gcc and clang.-s SUPPORT_LONGJMP=0 is passed to disable longjmp, do not run the LLVM
wasm backend path that handles longjmp. Before this only affected linking, and
now the flag gives you the ability to affect codegen at compile time too. This
is necessary if one does not want any invokes generated for longjmp at all.
(#12394)COMPILER_WRAPPER settings (with corresponding EM_COMPILER_WRAPPER
environment variable. This replaces the existing EMMAKEN_COMPILER
environment variable which is deprecated, but still works for the time being.
The main differences is that EM_COMPILER_WRAPPER only wraps the configured
version of clang rather than replacing it.WEBGL_multi_draw_instanced_base_vertex_base_instance bindings (#12282).getentropy in sys/random.h, and use that from libc++'s
random_device. This is more efficient, see #12240.ABORT_ON_WASM_EXCEPTIONS to work with the recent dynCall changes where
functions can be called via the WASM table directly, bypassing WASM exports
(#12269).ASYNCIFY_ADVISE to output which functions have been instrumented for
Asyncify mode, and why they need to be handled. (#12146)malloc and free by default. If you need access to them from
JS, you must export them manually using
-s EXPORTED_FUNCTIONS=['_malloc', ..].-O1. This makes -O1 builds a little
larger but they compile a lot faster, which makes more sense in a "compromise"
build (in between -O0 and higher optimization levels suitable for release
builds). (#12178)ERROR_ON_WASM_CHANGES_AFTER_LINK option that errors if we need to do
any work in wasm-emscripten-finalize or wasm-opt after linking. This
can verify the link is maximally fast and also does no DWARF rewriting.
(#12173)Breaking changes to calling Wasm function pointers from JavaScript:
It is no longer possible to directly call dynCall_sig(funcPtr, param) to call a function pointer from JavaScript code. As a result, JavaScript code outside all JS libraries (pre-js/post-js/EM_ASM/EM_JS/external JS code) can no longer call a function pointer via static signature matching dynCall_sig, but must instead use the dynamic binding function
dynCall(sig, ptr, args);
This carries a significant performance overhead. The function dynCall is not available in -s MINIMAL_RUNTIME=1 builds. 2. old syntax for calling a Wasm function pointer from a JS library file used to be
{{{ makeDynCall('sig') }}} (ptr, arg1, arg2);
This syntax will no longer work, and until Emscripten <2.0.9 causes a runtime error TypeError: WebAssembly.Table.get(): Argument 0 must be convertible to a valid number.
New syntax for calling Wasm function pointers from JS library files is
{{{ makeDynCall('sig', 'ptr') }}} (arg1, arg2);
See PR #12059 for details.
The native optimizer and the corresponding config setting
(EMSCRIPTEN_NATIVE_OPTIMIZER) have been removed (it was only relevant to
asmjs/fastcomp backend).
Remove ALLOC_DYNAMIC and deprecate dynamicAlloc. (#12057, which also
removes the internal DYNAMICTOP_PTR API.)
Add ABORT_ON_WASM_EXCEPTIONS which will abort when an unhandled WASM exception
is encountered. This makes the Emscripten program behave more like a native
program where the OS would terminate the process and no further code can be
executed when an unhandled exception (e.g. out-of-bounds memory access) happens.
Once the program aborts any exported function calls will fail with a "program
has already aborted" exception to prevent calls into code with a potentially
corrupted program state.
Use __indirect_function_table as the import name for the table, which is
what LLVM does.
Remove BINARYEN_SCRIPTS setting.
The default output format is now executable JavaScript. Previously we would
default to output objecting files unless, for example, the output name ended
in .js. This is contrary to behaviour of clang and gcc. Now emscripten
will always produce an executable unless the -c, -r or -shared flags
are given. This is true even when the name of the output file ends in .o.
e.g, emcc foo.c -o foo.o will produce a JavaScript file called foo.o.
This might surprise some users (although it matches the behavior of existing
toolchains) so we now produce a warning in this case.
file:// URLs, which
are not very useful for testing anyhow for other reasons (like not working
in chrome), and it made things more complex. The behavior has been changed
to be simpler and just leave the browser's error code as it is.--no-heap-copy file packager option by default, and remove the old
default behavior entirely. That is the behavior we should have had from the
beginning as it is more memory-efficient. (#12027)--no-entry is now required in STANDALONE_WASM mode when building a reactor
(application without a main function). Previously exporting a list of
functions that didn't include _main would imply this. Now the list of
EXPORTED_FUNCTIONS is not relevant in the deciding the type of application
to build. (#12020)__original_main using --inline-main. We used to do this
so that it didn't show up in stack traces (which could be confusing because
it is added by the linker - it's not in the source code). But this has had
several downsides, so we are stopping that now. This does not affect program
behavior, unless you look at the wasm internals. However, one noticeable
effect is that if you use ASYNCIFY_ADD or ASYNCIFY_ONLY then you may need
to add __original_main to there (since you are doing manual fine-tuning of
the list of functions, which depends on the wasm's internals). Note that this
should not matter in -O2+ anyhow as normal inlining generally removes
__original_main. (#11995)STACK_OVERFLOW_CHECK in builds with ASSERTIONS
from 2 to 1. This means that plain debug builds (-O0, which enables
ASSERTIONS) do not have the most expensive stack checks on by default. You
can still add them with -s STACK_OVERFLOW_CHECK=2.RESERVED_FUNCTION_POINTERS setting, which is no longer needed as
we have ALLOW_TABLE_GROWTH. The old option allowed a fixed number of
functions to be added to the table, while the new one allows an unlimited
number. (We needed the old option for fastcomp, which could not support
growth.) The old setting is mapped to the new one, so that building with
-s RESERVED_FUNCTION_POINTERS=K for any K > 0 will simply turn on
table growth. The only noticeable effect of this is that you will be able to
add an unlimited amount of functions and not just K.EM_CONFIG environment variable and --em-config command line option no
longer support a literal python string. Instead the name of a config file is
required. Since all config file settings are individually override-able using
EM_FOO this should be enough.-Wno-deprecated). Please update to
python3 as we hope to remove support completely in the next release.--save-bc command line option. This was specific to fastcomp,
which is deprecated, and for debugging purposes we already have EMCC_DEBUG
which saves all intermediate files.EXPORTED_FUNCTIONS list is
missing from the build (can be disabled via -Wno-undefined)
(ERROR_ON_UNDEFINED_SYMBOLS and WARN_ON_UNDEFINED_SYMBOLS no longer apply
to these symbols which are explicitly exported).WASM=0; #11505).emscripten/math.h to emscripten/em_math.h because if a user adds
emscripten/ as an include path with -I, that can override libc math.h,
which leads to very confusing errors.main mandatory by default (#11536). To build a
library ("reactor"), use --no-entry. The compiler will suggest that if
main is not present.-s and
the name of the setting. For example, -sEXPORT_ALL is now equivalent to
-s EXPORT_ALL.EXCEPTION_CATCHING_WHITELIST to EXCEPTION_CATCHING_ALLOWED. The
functionality is unchanged, and the old name will be allowed as an alias
for a few releases to give users time to migrate.ASYNCIFY_ADD to
add a function, ASYNCIFY_REMOVE to remove one (previously this was
called ASYNCIFY_BLACKLIST), and ASYNCIFY_ONLY to set a list of the
only functions to instrument and no others (previously this was called
ASYNCIFY_WHITELIST). The updated lists also handle indirect calls properly,
so that if you use ASYNCIFY_IGNORE_INDIRECT and then add (using either the
add-list or the only-list) all the functions that are on the stack when
pausing, then things will work (for more, see
https://github.com/WebAssembly/binaryen/pull/2913).LIBCXX_ABI_OPTIMIZED_FUNCTION which is an ABI change in libc++
(changing the layout of the std::function object) (#11403).WASM2C option that integrates with wabt's wasm2c tool in order to
compile everything into a single C file (#11213).~/.emscripten config file in the $HOME directory is still supported and
the sample config will still be written there in the case that the emscripten
root is read-only.cache/ports inside the emscripten source directory. This can be
controlled by setting the location of the cache directory, or for even more
fine grained control the EM_PORTS environment variable and the PORTS
config setting can be used.-Wno-fastcomp).EMTERPRETIFY settings. Emterpreter has largely
been replaced by asyncify and is fastcomp only so due for removing in
the near future anyway.Add Math C API for direct access to JavaScript Math object (#11151).
Address Sanitizer support now includes JavaScript as well, that is, memory
access of HEAP* arrays is checked by ASan. That allows errors to be found if
JS glue code does something wrong like forget to shift a pointer. To use this,
just build with ASan normally, -fsanitize=address at link (#11147).
Fix embind string conversions in multithreaded builds (#10844).
ALLOW_MEMORY_GROWTH used to silently disable ABORTING_MALLOC. It now
just changes the default, which means you can pass -s ABORTING_MALLOC=1 to
override the default, which was not possible before. (If you pass the flag
and don't want that behavior, stop passing the flag.) (#11131)
Change the factory function created by using the MODULARIZE build option to
return a Promise instead of the module instance. That is, beforehand
Module()
would return an instance (which was perhaps not ready yet if startup was
async). In the new model, that returns a Promise which you can do .then or
await on to get notified when the instance is ready, and the callback
receives the instance. Note that both before and after this change
doing Module() creates and runs an instance, so the only change is
the return value from that call.
This fixes some long-standing bugs with that option which have been reported
multiple times, but is a breaking change - sorry about that. To reduce the
risk of confusing breakage, in a build with ASSERTIONS we will show a clear
warning on common errors. For more, see detailed examples for the current
usage in src/settings.js on MODULARIZE. (#10697)
A new PRINTF_LONG_DOUBLE option allows printf to print long doubles at full
float128 precision. (#11130)
emscripten_async_queue_on_thread has been renamed to
emscripten_dispatch_to_thread which no longer implies that it is async -
the operation is in fact only async if it is sent to another thread, while it
is sync if on the same one. A new emscripten_dispatch_to_thread_async
function is added which is always async.
The emscripten cache now lives in a directory called cache at the root
of the emscripten tree by default. The CACHE config setting and the
EM_CACHE environment variable can be used to override this (#11126).
Honor CACHE setting in config file as an alternative to EM_CACHE
environment variable.
Remove --cache command line arg. The CACHE config setting and the
EM_CACHE environment variable can be used to control this.
Compiling to a file with no suffix will now generate an executable (JS) rather
than an object file. This means simple cases like emcc -o foo foo.c do the
expected thing and generate an executable.
System libraries such as libc and libc++ are now included by default at
link time rather than selectively included based on the symbols used in the
input object files. For small programs that don't use any system libraries
this might result in slightly slower link times with the old fastcomp
backend. In order to exclude these libraries build with -nostdlib and/or
-nostdlib++.
--extern-pre-js and --extern-post-js emcc flags. Files provided there
are prepended/appended to the final JavaScript output, after all other
work has been done, including optimization, optional MODULARIZE-ation,
instrumentation like SAFE_HEAP, etc. They are the same as prepending/
appending those files after emcc finishes running, and are just a convenient
way to do that. (For comparison, --pre-js and --post-js optimize that code
together with everything else, keep it in the same scope if running
MODULARIZE, etc.).FE_INEXACT and other floating point exception macros in libc,
since we don't support them. That also prevents musl from including code using
pragmas that don't make sense for wasm. Ifdef out other uses of those pragmas
as well, as tip of tree LLVM now fails to compile them on wasm. (#11087)BINARYEN_PASSES setting (#11057). We still have
BINARYEN_EXTRA_PASSES (the removed setting completely overrides the set
of passes from the command line, which doesn't make much sense as some of
them are mandatory like setting the sbrk ptr).MODULARIZE_INSTANCE build option (#11037). This was a seldom used
option that was complicating the logic for MODULARIZE. Module instances can
be created by using MODULARIZE and calling the factory function explicitly.
See the new --extern-post-js option added in this release, which can help
code that used MODULARIZE_INSTANCE (you can add an extern post js which
does Module = Module(); for example).EMTERPRETIFY which is soon to be removed.EMCC_LEAVE_INPUTS_RAW.
The two uses cases in our test code were covered by the -nostdlib option.CONFIGURE_CC. This could be used to override the underlying
compiler used in emcc/em++ but only during configure tests. There are other
ways to control/fake the detected configure features that don't require such
monkey patching. For example setting defaults via a site file:
https://www.gnu.org/software/autoconf/manual/autoconf-2.67/html_node/Site-Defaults.htmlCOMPILER_OPTS. This was
a global setting in the emscripten config file that would inject extra
compiler options.WASM_BIGINT flag. With
that the VM will use a JS BigInt for a wasm i64, avoiding the need for JS
legalization. See #10860.MAXIMUM_MEMORY to a
higher value (i.e. by default you do not get support for 2GB+ heaps).
See #10601--llvm-lto flag is now ignored when using the upstream llvm backend.
With the upstream backend LTO is controlled via -flto.python emcc no longer works.
However emcc, emcc.py and python emcc.py all continue to work.
The reason for this change is that #!/usr/bin/env python is no longer
portable since the python symlink was dropped from Ubuntu 20.04.fp$ and g$
accessors in main modules, possible in Binaryen thanks to ensuring function
table indexes are unique (#10741).JS_MATH option to use Math.* in JS instead of compiled musl (#10821).Module to Module callback functions like Module.preRun (#10777).ASYNCIFY_IMPORTS: it now contains only new imports
you add, and does not need to contain the list of default system imports like
emscripten_sleep. There is no harm in providing them, though, so this
is not a breaking change.-g, normal DWARF emitting happens,
and when linking with -g we preserve that and update it. This is a change
from before, where we assumed DWARF was unneeded and did not emit it, so this
can increase the size of debug builds (i.e. builds compiling and/or linking
with -g). This change is necessary for full debugging support, that is, to
be able to build with -g and use a debugger. Before this change only the
-gforce_dwarf flag enabled DWARF; that flag is now removed. If you want
the old behavior, build your object files with -gline-tables-only (that will
only add line table info, which is just enough for things like source maps and
does not include full debug info). For more info and background see #10325.memset handling, in particular, in the wasm backend,
completely remove the JS version of memset from the JS library and from
DEFAULT_LIBRARY_FUNCS_TO_INCLUDE. The regular C version will be linked in
from compiler_rt normally. A noticeable difference you may see is that
a JS library cannot add a __dep to memset - deps only work for JS
library functions, but now we only have the regular C version. If you hit that
issue, just add _memset to EXPORTED_FUNCTIONS (or adjust
deps_info.json).emscripten_atomic_exchange_u8,16,32,64 (#10657).TOTAL_MEMORY to INITIAL_MEMORY and WASM_MEM_MAX to MAXIMUM_MEMORY,
which are more accurate and match wasm conventions. The old names are still
supported as aliases.WASM_OBJECT_FILES setting. There are many standard ways to enable
bitcode objects (-flto, -flto=full, -flto=thin, -emit-llvm).ASSERTIONS that we do not have
compiled code on the stack when starting to rewind, which is dangerous.__invoke_* functions.-gforce_dwarf flag for now,
though (but that should be removed soon).npm install after
checking out emscripten if they want to use closure (--closure). emsdk users
are not affected because emsdk runs this as a post install step (#9989).EM_CACHE. This should not really be a user visible change although one
side effect is that once a given port is built, its headers are then
universally accessible, just like the library is universally available as
-l<name>.timestamp field from mouse, wheel, devicemotion and
deviceorientation events. The presence of a timestamp on these events was
slightly arbitrary, and populating this field caused a small profileable
overhead that all users might not care about. It is easy to get a timestamp of
an event by calling emscripten_get_now() or emscripten_performance_now()
inside the event handler function of any event.MIN_FIREFOX_VERSION, MIN_SAFARI_VERSION, MIN_IE_VERSION,
MIN_EDGE_VERSION, MIN_CHROME_VERSION. The existing LEGACY_VM_SUPPORT
option sets all of them to 0, that is, maximal backwards compatibility.
Note that going forward, we will use these settings in more places, so if
you do need very old legacy browser support, you may need to set either
LEGACY_VM_SUPPORT or the fine-grained options. For more details see #9937DISABLE_DEPRECATED_FIND_EVENT_TARGET_BEHAVIOR to 1. See #9895.
With this change the old deprecated HTML5 API event target lookup behavior is
disabled. There is no "Module.canvas" object, no magic "null" default handling,
and DOM element 'target' parameters are taken to refer to CSS selectors, instead
of referring to DOM IDs. For more information see:
https://groups.google.com/forum/#!msg/emscripten-discuss/xScZ_LRIByk/_gEy67utDgAJwasi_unstable to wasi_snapshot_preview1. This
is mostly an implementation detail, but if you use STANDALONE_WASM it means
that the output of emscripten now requires a runtime with
wasi_snapshot_preview1 support.SAFE_STACK has been removed, as it overlaps with STACK_OVERFLOW_CHECK.
Replace SAFE_STACK=1 with STACK_OVERFLOW_CHECK=2 (note the value is 2).
This also has the effect of enabling stack checking on upstream builds when
ASSERTIONS are enabled (as assertions enable STACK_OVERFLOW_CHECK=2).requestFullScreen method from library_browser.js, please
use requestFullscreen (without the capital S).requestFullScreen and cancelFullScreen from library_glut.jsrequestFullScreen and cancelFullScreen from library_glfw.jsERROR_ON_MISSING_LIBRARIES now also applies to internal symbols that start
with emscripten_. Prior to this change such missing symbols would result
in a runtime error, now they are reported at compile time.ALLOW_BLOCKING_ON_MAIN_THREAD is unset then the warning is an error.pthread_tryjoin_np, which is a POSIX API similar to pthread_join
but without blocking.emscripten_has_asyncify().-lnodefs.js, -lidbfs.js',
-lworkerfs.js, -lproxyfs.js. See #9645.emscripten config variables using environment
variables. Any config variable FOO can be overridden by EM_FOO in the
environment.-Werror now also turns warnings in the python driver code into errors.settings.js to settings_internal.js.
These are settings that are for internal use only and are not set-able from
the command line. If we misclassified any of these please open a bug.STANDALONE_WASM mode now supports setting up argv via wasi APIs.STANDALONE_WASM mode now supports running static constructors in _start.MAIN_THREAD_EM_ASM in wasm backend. #9560USE_FETCH_WORKER=0. This is useful for people who use FETCH, but don't
perform any synchronous fetches on the main thread. #9567EMCONFIGURE_JS. Since #6269 we have set it to "2" which means never
use native, always use JS.USE_FETCH_WORKER=0 is enforced). #9490-s ONLY_MY_CODE as we now have much better solutions
for that, like building to a wasm object file or using STANDALONE_WASM
etc. (see
https://github.com/emscripten-core/emscripten/wiki/WebAssembly-Standalone).COMPILER_ENGINE and JS_ENGINE options. We only support
node as the compiler engine so just use a single NODE_JS option for that.EXTRA_EXPORTED_RUNTIME_METHODS, and as with other such changes in
the past, forgetting to export it will show a clear error in ASSERTIONS mode.EMITTING_JS flag, and replace it with STANDALONE_WASM. That flag indicates
that we want the wasm to be as standalone as possible. We may still emit JS in
that case, but the JS would just be a convenient way to run the wasm on the Web
or in Node.js.ASYNCIFY_BLACKLIST and ASYNCIFY_WHITELIST now support simple '*' wildcard matchingBINARYEN_ROOT in .emscripten to it. See #9409noExitRuntime
instead of Module.noExitRuntime.ERROR_ON_MISSING_LIBRARIES setting (it's always on now)TOTAL_MEMORY. This means that -s TOTAL_MEMORY=1024*1024
will no longer work. This is done because the mechanism may result in
execution of arbitrary code via command line flags.__builtin_return_address now requires -s USE_OFFSET_CONVERTER=1 to work. (#9073)callMain is no longer exported by default on Module, to allow better JS
minification. You must add it to EXTRA_EXPORTED_RUNTIME_METHODS if you want
to call it on Module. (In assertions builds, an error with an explanation is
shown.)EM_ASM's arguments and prohibit
non-arithmetic arguments (e.g. pointers, functions, arrays, objects). (#9054)emcc on Windows now uses native newline byte sequence to get a line to
print for parse error reporting. (#9088)Module object during startup, like Module.arguments,
are now copied to a local (in order to avoid writing Module.* everywhere,
which wastes space). You can still provide them as always, but you can't
modify Module.arguments and other things after startup (which is now
after we've finished processing them). In a build with assertions enabled you
will get an error if you access those properties after startup. (#9072)__thread
and the C11/C++11 keyword thread_local. (#8976)Module.readAsync()/Module['readAsync']() to readAsync().
Note that read is also renamed to read_ (since "read" is an API call in
the SpiderMonkey shell). In builds with ASSERTIONS, an error message is
shown about the API change. This change allows better JS minification
(the names read, readAsync etc. can be minified, and if the variables are
not used they can be removed entirely). Defining these APIs on Module
(which was never documented or intended, but happened to work) is also
no longer allowed (but you can override read_ etc. from JS).emscripten_run_script_string now returns C NULL instead of the string null
or undefined when the result of the eval is JavaScript null or undefined.embuilder.py to build a specific library, the name may have
changed: for consistency, all library names are prefixed with lib now.embuilder.py now only builds the requested library, and not its dependencies
and certain system libraries that are always built. For example, running
embuilder.py build libc no longer builds libcompiler_rt if it hasn't be built.EMCC_FORCE_STDLIBS with a list of libraries, you must now use
the simplified names, for example, libmalloc and libpthreads instead of
libdlmalloc or libpthreads_stub. These names will link in the correct
version of the library: if the build is configured to use emmalloc, libmalloc
will mean libemmalloc, and if thread support is disabled, libpthreads will
mean libpthreads_stub. This allows you to say libmalloc or libpthreads without
worrying about which implementation is supposed to be used, and avoid duplicate
symbols if you used the wrong implementation.emcc -fsanitize=undefined to work. (#8651)-fsanitize-minimal-runtime) also works. (#8617)emscripten_return_address which implements the functionality of
gcc/clang's __builtin_return_address. (#8617)ino_t/off_t to 64-bits. (#8467)libbz2.a). (#8349)ERROR_ON_MISSING_LIBRARIES by default (#8461)-s EMTERPRETIFY_WHITELIST now accepts shell-style wildcards;
this allows matching static functions with conflicting names that
the linker distinguishes by appending a random suffix.library_browser.js. This changes the scroll
amount in SDL, GLFW, and GLUT. (#7968)EMCC_LOCAL_PORTS works, to be more usable. See #7963-s DISABLE_DEPRECATED_FIND_EVENT_TARGET_BEHAVIOR=1 that
changes the lookup semantics of DOM elements in html5.h event handler
callbacks and WebGL context creation. The new behavior is to use CSS selector
strings to look up DOM elements over the old behavior, which was somewhat
ad hoc constructed rules around default Emscripten uses. The old behavior
will be deprecated and removed in the future. Build with -s ASSERTIONS=1
to get diagnostics messages related to this transition.lib prefix. If you use
EMCC_FORCE_STDLIBS or EMCC_ONLY_FORCED_STDLIBS to select system libraries
you may need to add the lib prefix.pthread-main.js to NAME.worker.js, where NAME is the main
name of your application, that is, if you emit program.js then you'll get
program.worker.js (this allows more than one to exist in the same
directory, etc.).runPostSets function and replace with normal static
constructor function. See #7579strptime()'s handling of the "%c" to match that of strftime().
This is a breaking change for code which depends on the old definition of
"%c".tableBase/memoryBase to
__table_base/__memory_base (#7467)-s NO_X=1 as an alias for -s X=0 and vice versa, which
simplifies current settings with NO_-prefixed names. See #7151.EMULATED_FUNCTION_POINTER improvements. See #7108, #7128.ERROR_ON_UNDEFINED_SYMBOLS is now the default. See #7196-s WASM_OBJECT_FILES=1.
See #6875.size_t and friends from int to long. This may have
noticeable effects if you depend on the name mangling of a function that uses
size_t (like in EXPORTED_FUNCTIONS), and you must rebuild source files to
bitcode (so your bitcode is in sync with the system libraries after they are
rebuilt with this change). Otherwise this should not have any noticeable
effects for users. See #5916.Module.locateFile to resolve relative paths to *.wasm, *.mem and other
files relatively to the main JavaScript file rather than the current working
directory (see #5368).
prefix to Module.locateFile function that contains
the path to the JavaScript file where files are loaded from by default.Module.*PrefixURL APIs (use Module.locateFile instead).invoke_*()s. This may add noticeable
overhead to programs using C++ exceptions and (less likely) setjmp/longjmp -
please report any issues. See #6666 #6702src/struct_info.compiled.json: Make it a
normal cached thing like system libraries, not something checked into the
source tree.-s WASM=0 to
disable wasm and use asm.js if you want that (or use -s LEGACY_VM_SUPPORT=1, which emits output that can run in older browsers,
which includes a bunch of polyfills as well as disables wasm). (#6419)-s X=@file broke if the file contains a newline
(see #6436; fixed in 1.37.40)-s DISABLE_EXCEPTION_CATCHING=0 to enable them.addFunction is now supported on LLVM wasm backend, but when being used on
the wasm backend, you need to provide an additional second argument, a Wasm
function signature string. Each character within a signature string
represents a type. The first character represents the return type of a
function, and remaining characters are for parameter types.
ALLOC_* numeric constants by default. As
with previous changes, a warning will be shown in -O0 and when ASSERTIONS
are on if they are used.-O0 and when ASSERTIONS are on, which
will suggest either exporting the specific methods you need, or using
FORCE_FILESYSTEM which will auto export all the main filesystem methods.
Aside from using FS methods yourself, you may notice this change when using a
file package created standalone, that is, by running the file packager
directly and then loading it at run time (as opposed to telling emcc to
package the files for you, in which case it would be aware of them at compile
time); you should build with FORCE_FILESYSTEM to ensure filesystem support
for that case.Runtime object, and move all the useful methods
from it to simple top-level functions. Any usage of Runtime.func should be
changed to func.NO_EXIT_RUNTIME to 1 by default. This means that by
default we don't include code to shut down the runtime, flush stdio streams,
run atexits, etc., which is better for code size. When ASSERTIONS is on, we
warn at runtime if there is text buffered in the streams that should be
flushed, or atexits are used.ASSERTIONS warnings to help users), do not export the
following runtime methods by default: ccall, cwrap, allocate,
Pointer_stringify, AsciiToString, stringToAscii, UTF8ArrayToString,
UTF8ToString, stringToUTF8Array, stringToUTF8, lengthBytesUTF8, stackTrace,
addOnPreRun, addOnInit, addOnPreMain, addOnExit, addOnPostRun,
intArrayFromString, intArrayToString, writeStringToMemory,
writeArrayToMemory, writeAsciiToMemory.LEGACY_VM_SUPPORT option enables support for legacy
browsers. In ASSERTIONS mode, a warning is shown if a polyfill was needed,
suggesting using that option.Module then you
must export them by adding them to EXTRA_EXPORTED_RUNTIME_METHODS. In -O0
or when ASSERTIONS is on, a run-time error message explains that, if they
are attempted to be used incorrectly._mm_set_epi64x() function (#5103)llvm_powi_f*._Exit() function.SharedInt*Array
hierarchy no longer exists in the SharedArrayBuffer spec.glDrawBuffers(0, *); (#3890)i64* in side modules.sysconf(_SC_PHYS_PAGES) (#3405, 3442).safeSet*() operations.emscripten_idb_* API. (#3169)glGen*() when the GL context was lost might
throw a JS exception, instead a GL_INVALID_OPERATION is now recorded.