Disable WASM_LEGACY_EXCEPTIONS by default

The Wasm committee and browser vendors would like legacy wasm exceptions
to be phased out ASAP.  To that end this change disables
`WASM_LEGACY_EXCEPTIONS` by default for users of `-fwasm-exceptions`.

User who need to target old browsers can obviously set
`-sWASM_LEGACY_EXCEPTIONS` still.

Running ./emcc -fwasm-exceptions with EMCC_DEBUG=1 shows the effect
this has on min browser versions:

```
feature_matrix:DEBUG: Enabling MIN_CHROME_VERSION=137 to accommodate Wasm exceptions (-fwasm-exceptions without sWASM_LEGACY_EXCEPTIONS)
feature_matrix:DEBUG: Enabling MIN_FIREFOX_VERSION=131 to accommodate Wasm exceptions (-fwasm-exceptions without WASM_LEGACY_EXCEPTIONS)
feature_matrix:DEBUG: Enabling MIN_SAFARI_VERSION=180400 to accommodate Wasm exceptions (-fwasm-exceptions without WASM_LEGACY_EXCEPTIONS)
feature_matrix:DEBUG: Enabling MIN_NODE_VERSION=241500 to accommodate Wasm exceptions (-fwasm-exceptions without WASM_LEGACY_EXCEPTIONS)
```

Author: sbc100

ChangeLog.md

@@ -24,6 +24,11 @@ See docs/process.md for more on how version tagging works.
   `WebAssembly.instantiateStreaming()` (via `Blob.stream()` and a `tee()`'d
   network body respectively), so enabling the flag no longer loses the
   download/compile overlap of the standard streaming path. (#27609)
+- `WASM_LEGACY_EXCEPTIONS` now defaults to `false`. When `-fwasm-exceptions` is
+  used, Emscripten now emits instructions for the standardized WebAssembly
+  exception handling proposal by default. Users targeting older engines can
+  still opt in to the legacy exception handling proposal with
+  `-sWASM_LEGACY_EXCEPTIONS`. (#27575)
 
 6.0.8 - 08/20/26
 ----------------

site/source/docs/tools_reference/settings_reference.rst

@@ -1175,7 +1175,7 @@ https://github.com/WebAssembly/exception-handling/blob/main/proposals/exception-
 
 .. note:: Applicable during both linking and compilation
 
-Default value: true
+Default value: false
 
 .. _asyncify:
 

src/settings.js

@@ -796,7 +796,7 @@ var EXCEPTION_STACK_TRACES = false;
 // If false, emit instructions for the standardized exception handling proposal:
 // https://github.com/WebAssembly/exception-handling/blob/main/proposals/exception-handling/Exceptions.md
 // [compile+link]
-var WASM_LEGACY_EXCEPTIONS = true;
+var WASM_LEGACY_EXCEPTIONS = false;
 
 // Whether to support async operations in the compiled code. This makes it
 // possible to call JS functions from synchronous-looking code in C/C++.

test/test_codesize.py

@@ -366,7 +366,7 @@ def test_codesize_minimal_pthreads(self, args):
     # exceptions does not pull in demangling by default, which increases code size
     'mangle':   (['-O2', '-fexceptions', '-sEXPORTED_FUNCTIONS=_main,_free,___cxa_demangle', '-Wno-deprecated'],),
     # Wasm EH's code size increase is smaller than that of Emscripten EH
-    'except_wasm': (['-O2', '-fwasm-exceptions', '-sWASM_LEGACY_EXCEPTIONS=0'],),
+    'except_wasm': (['-O2', '-fwasm-exceptions'],),
     'except_wasm_legacy': (['-O2', '-fwasm-exceptions', '-sWASM_LEGACY_EXCEPTIONS'],),
     # eval_ctors 1 can partially optimize, but runs into getenv() for locale
     # code. mode 2 ignores those and fully optimizes out the ctors

test/test_other.py

@@ -8820,7 +8820,7 @@ def test_lto(self, args):
   @parameterized({
     'noexcept': (),
     'except_emscripten': ('-sDISABLE_EXCEPTION_CATCHING=0',),
-    'except_wasm': ('-fwasm-exceptions', '-sWASM_LEGACY_EXCEPTIONS=0'),
+    'except_wasm': ('-fwasm-exceptions',),
     'except_wasm_legacy': ('-fwasm-exceptions', '-sWASM_LEGACY_EXCEPTIONS'),
   })
   def test_lto_libcxx(self, *args):
@@ -12682,11 +12682,11 @@ def test_SUPPORT_LONGJMP_wasm(self):
     # automatically sets DISABLE_EXCEPTION_THROWING to 1, which is 0 by default,
     # because Emscripten EH and Wasm SjLj cannot be used at the same time.
     self.run_process([EMCC, test_file('core/test_longjmp.c'), '-c', '-sSUPPORT_LONGJMP=wasm', '-o', 'a.o'])
-    self.assertContained('try', self.get_wasm_text('a.o'))
+    self.assertContained('try_table', self.get_wasm_text('a.o'))
 
-    # If -sWASM_LEGACY_EXCEPTIONS=0 is provided, it uses the standard Wasm EH.
-    self.run_process([EMCC, test_file('core/test_longjmp.c'), '-c', '-sSUPPORT_LONGJMP=wasm', '-sWASM_LEGACY_EXCEPTIONS=0', '-o', 'b.o'])
-    self.assertContained('try_table', self.get_wasm_text('b.o'))
+    # If -sWASM_LEGACY_EXCEPTIONS is provided, it uses the legacy Wasm EH.
+    self.run_process([EMCC, test_file('core/test_longjmp.c'), '-c', '-sSUPPORT_LONGJMP=wasm', '-sWASM_LEGACY_EXCEPTIONS', '-o', 'b.o'])
+    self.assertContained('try', self.get_wasm_text('b.o'))
 
   @parameterized({
     '': ([],),
@@ -15303,7 +15303,7 @@ def test_SUPPORT_BIG_ENDIAN(self):
     'noexcept': ('-fno-exceptions',),
     'default': (),
     'except': ('-sDISABLE_EXCEPTION_CATCHING=0',),
-    'except_wasm': ('-fwasm-exceptions', '-sWASM_LEGACY_EXCEPTIONS=0'),
+    'except_wasm': ('-fwasm-exceptions',),
     'except_wasm_legacy': ('-fwasm-exceptions', '-sWASM_LEGACY_EXCEPTIONS'),
   })
   def test_std_promise_link(self, *args):

tools/feature_matrix.py

@@ -261,11 +261,11 @@ def apply_min_browser_versions():
     enable_feature(Feature.WORKER_ES6_MODULES, 'EXPORT_ES6 with -sWASM_WORKERS')
   if settings.OFFSCREENCANVAS_SUPPORT:
     enable_feature(Feature.OFFSCREENCANVAS_SUPPORT, 'OFFSCREENCANVAS_SUPPORT')
-  if settings.WASM_EXCEPTIONS or settings.SUPPORT_LONGJMP == 'wasm': # Wasm longjmp support will lean on Wasm (Legacy) EH
+  if settings.WASM_EXCEPTIONS or settings.SUPPORT_LONGJMP == 'wasm':
     if settings.WASM_LEGACY_EXCEPTIONS:
-      enable_feature(Feature.WASM_LEGACY_EXCEPTIONS, 'Wasm Legacy exceptions (-fwasm-exceptions with -sWASM_LEGACY_EXCEPTIONS=1)')
+      enable_feature(Feature.WASM_LEGACY_EXCEPTIONS, 'Wasm Legacy exceptions (-fwasm-exceptions with WASM_LEGACY_EXCEPTIONS)')
     else:
-      enable_feature(Feature.WASM_EXCEPTIONS, 'Wasm exceptions (-fwasm-exceptions with -sWASM_LEGACY_EXCEPTIONS=0)')
+      enable_feature(Feature.WASM_EXCEPTIONS, 'Wasm exceptions (-fwasm-exceptions without WASM_LEGACY_EXCEPTIONS)')
   if settings.GROWABLE_ARRAYBUFFERS == 2:
     enable_feature(Feature.GROWABLE_ARRAYBUFFERS, 'GrowableSharedArrayBuffer')
 

tools/system_libs.py

@@ -807,7 +807,7 @@ def get_cflags(self):
       case Exceptions.WASM_LEGACY:
         cflags += ['-fwasm-exceptions', '-sWASM_LEGACY_EXCEPTIONS']
       case Exceptions.WASM:
-        cflags += ['-fwasm-exceptions', '-sWASM_LEGACY_EXCEPTIONS=0']
+        cflags += ['-fwasm-exceptions']
 
     return cflags
 
@@ -865,7 +865,6 @@ def get_cflags(self):
                    '-D__WASM_SJLJ__']
       case Exceptions.WASM:
         cflags += ['-sSUPPORT_LONGJMP=wasm',
-                   '-sWASM_LEGACY_EXCEPTIONS=0',
                    '-sDISABLE_EXCEPTION_THROWING',
                    '-D__WASM_SJLJ__']
     return cflags