[EH] Rename EH library modes and file names (#23452)

- This renames `NoExceptLibrary` to `ExceptionLibrary`

- This renames the `Exception.WASM` to `Exceptions.WASM_LEGACY`, given
that we plan to add a new mode that uses the standard EH proposal soon,
which will be named `Exceptions.WASM`. This PR does not add the new mode
yet; it just renames what we already have.

- This makes `SjLjLibrary` use `eh_mode` as in `ExceptionLibrary`
instead of the current `is_wasm` boolean switch, given that we will need
to add another mode that uses the standard EH proposal to it soon. Its
`eh_mode` can't be set to `Exceptions.NONE` though.

- Library file suffixes changed
  - `ExceptionLibrary`
    - `NONE`: `-noexcept` -> `-noexcept` (no change)
    - `EMSCRIPTEN`: `` -> `` (no change)
    - `WASM_LEGACY`: `-except` -> `-legacyexcept`
    - `WASM` (will be added later): X -> `-wasmexcept`
  - `SjLjLibrary`
    - `EMSCRIPTEN`: `` -> `` (no change)
    - `WASM_LEGACY`: `-wasm-sjlj` -> `-legacysjlj`
    - `WASM` (will be added later): X -> `-wasmsjlj`

We give the current default mode (`EMSCRIPTEN`) no suffix. We hope we
eventually change `WASM` to be the default, in which case we will give
it no suffix and give `EMSCRIPTEN` a suffix like `-emexcept`/`-emsjlj`.

Also I removed / didn't add a `-` within a single suffix, so it is
`-legacyexcept` rather than `-legacy-except`. The reason is if a library
inherits from multiple classes, it will have multiple `-`s in its file
name like `libc++abi-debug-legacyexcept.a`, and I think it is clearer if
`-` only acts like split points between different suffixes.

embuilder.py

@@ -31,22 +31,22 @@
 # Minimal subset of targets used by CI systems to build enough to be useful
 MINIMAL_TASKS = [
     'libcompiler_rt',
-    'libcompiler_rt-wasm-sjlj',
+    'libcompiler_rt-legacysjlj',
     'libcompiler_rt-ww',
     'libc',
     'libc-debug',
     'libc-ww-debug',
     'libc_optz',
     'libc_optz-debug',
     'libc++abi',
-    'libc++abi-except',
+    'libc++abi-legacyexcept',
     'libc++abi-noexcept',
     'libc++abi-debug',
-    'libc++abi-debug-except',
+    'libc++abi-debug-legacyexcept',
     'libc++abi-debug-noexcept',
     'libc++abi-debug-ww-noexcept',
     'libc++',
-    'libc++-except',
+    'libc++-legacyexcept',
     'libc++-noexcept',
     'libc++-ww-noexcept',
     'libal',
@@ -79,7 +79,7 @@
     'crt1',
     'crt1_proxy_main',
     'crtbegin',
-    'libunwind-except',
+    'libunwind-legacyexcept',
     'libnoexit',
     'sqlite3',
     'sqlite3-mt',

tools/ports/freetype.py

@@ -8,7 +8,7 @@
 TAG = 'VER-2-13-3'
 HASH = 'ce413487c24e689631d705f53b64725256f89fffe9aade7cf07bbd785a9cd49eb6b8d2297a55554f3fee0a50b17e8af78f505cdab565768afab833794f968c2f'
 
-variants = {'freetype-wasm-sjlj': {'SUPPORT_LONGJMP': 'wasm'}}
+variants = {'freetype-legacysjlj': {'SUPPORT_LONGJMP': 'wasm', 'WASM_LEGACY_EXCEPTIONS': 1}}
 deps = ['zlib']
 
 
@@ -18,7 +18,7 @@ def needed(settings):
 
 def get_lib_name(settings):
   if settings.SUPPORT_LONGJMP == 'wasm':
-    return 'libfreetype-wasm-sjlj.a'
+    return 'libfreetype-legacysjlj.a'
   else:
     return 'libfreetype.a'
 

tools/ports/libpng.py

@@ -11,8 +11,8 @@
 deps = ['zlib']
 variants = {
   'libpng-mt': {'PTHREADS': 1},
-  'libpng-wasm-sjlj': {'SUPPORT_LONGJMP': 'wasm'},
-  'libpng-mt-wasm-sjlj': {'PTHREADS': 1, 'SUPPORT_LONGJMP': 'wasm'},
+  'libpng-legacysjlj': {'SUPPORT_LONGJMP': 'wasm', 'WASM_LEGACY_EXCEPTIONS': 1},
+  'libpng-mt-legacysjlj': {'PTHREADS': 1, 'SUPPORT_LONGJMP': 'wasm', 'WASM_LEGACY_EXCEPTIONS': 1},
 }
 
 
@@ -25,7 +25,7 @@ def get_lib_name(settings):
   if settings.PTHREADS:
     suffix += '-mt'
   if settings.SUPPORT_LONGJMP == 'wasm':
-    suffix += '-wasm-sjlj'
+    suffix += '-legacysjlj'
   return f'libpng{suffix}.a'
 
 

tools/system_libs.py

@@ -769,21 +769,19 @@ class Exceptions(IntEnum):
   """
   This represents exception handling mode of Emscripten. Currently there are
   three modes of exception handling:
-  - None: Does not handle exceptions. This includes -fno-exceptions, which
+  - NONE: Does not handle exceptions. This includes -fno-exceptions, which
     prevents both throwing and catching, and -fignore-exceptions, which only
     allows throwing, but library-wise they use the same version.
-  - Emscripten: Emscripten provides exception handling capability using JS
+  - EMSCRIPTEN: Emscripten provides exception handling capability using JS
     emulation. This causes code size increase and performance degradation.
-  - Wasm: Wasm native exception handling support uses Wasm EH instructions and
-    is meant to be fast. You need to use a VM that has the EH support to use
-    this. This is not fully working yet and still experimental.
+  - WASM_LEGACY: Wasm native exception handling support (legacy)
   """
   NONE = auto()
   EMSCRIPTEN = auto()
-  WASM = auto()
+  WASM_LEGACY = auto()
 
 
-class NoExceptLibrary(Library):
+class ExceptionLibrary(Library):
   def __init__(self, **kwargs):
     self.eh_mode = kwargs.pop('eh_mode')
     super().__init__(**kwargs)
@@ -794,8 +792,9 @@ def get_cflags(self):
       cflags += ['-fno-exceptions']
     elif self.eh_mode == Exceptions.EMSCRIPTEN:
       cflags += ['-sDISABLE_EXCEPTION_CATCHING=0']
-    elif self.eh_mode == Exceptions.WASM:
+    elif self.eh_mode == Exceptions.WASM_LEGACY:
       cflags += ['-fwasm-exceptions']
+
     return cflags
 
   def get_base_name(self):
@@ -804,21 +803,21 @@ def get_base_name(self):
     # suffixes. Change the default to wasm exception later.
     if self.eh_mode == Exceptions.NONE:
       name += '-noexcept'
-    elif self.eh_mode == Exceptions.WASM:
-      name += '-except'
+    elif self.eh_mode == Exceptions.WASM_LEGACY:
+      name += '-legacyexcept'
     return name
 
   @classmethod
-  def variations(cls, **kwargs):  # noqa
+  def variations(cls):
     combos = super().variations()
     return ([dict(eh_mode=Exceptions.NONE, **combo) for combo in combos] +
             [dict(eh_mode=Exceptions.EMSCRIPTEN, **combo) for combo in combos] +
-            [dict(eh_mode=Exceptions.WASM, **combo) for combo in combos])
+            [dict(eh_mode=Exceptions.WASM_LEGACY, **combo) for combo in combos])
 
   @classmethod
   def get_default_variation(cls, **kwargs):
     if settings.WASM_EXCEPTIONS:
-      eh_mode = Exceptions.WASM
+      eh_mode = Exceptions.WASM_LEGACY
     elif settings.DISABLE_EXCEPTION_CATCHING == 1:
       eh_mode = Exceptions.NONE
     else:
@@ -828,15 +827,16 @@ def get_default_variation(cls, **kwargs):
 
 class SjLjLibrary(Library):
   def __init__(self, **kwargs):
-    # Whether we use Wasm EH instructions for SjLj support
-    self.is_wasm = kwargs.pop('is_wasm')
+    # Which EH method we use for SjLj support
+    self.eh_mode = kwargs.pop('eh_mode')
     super().__init__(**kwargs)
 
   def get_cflags(self):
     cflags = super().get_cflags()
-    if self.is_wasm:
-      # DISABLE_EXCEPTION_THROWING=0 is the default, which is for Emscripten
-      # EH/SjLj, so we should reverse it.
+    if self.eh_mode == Exceptions.EMSCRIPTEN:
+      cflags += ['-sSUPPORT_LONGJMP=emscripten',
+                 '-sDISABLE_EXCEPTION_THROWING=0']
+    elif self.eh_mode == Exceptions.WASM_LEGACY:
       cflags += ['-sSUPPORT_LONGJMP=wasm',
                  '-sDISABLE_EXCEPTION_THROWING',
                  '-D__WASM_SJLJ__']
@@ -846,18 +846,23 @@ def get_base_name(self):
     name = super().get_base_name()
     # TODO Currently emscripten-based SjLj is the default mode, thus no
     # suffixes. Change the default to wasm exception later.
-    if self.is_wasm:
-      name += '-wasm-sjlj'
+    if self.eh_mode == Exceptions.WASM_LEGACY:
+      name += '-legacysjlj'
     return name
 
   @classmethod
-  def vary_on(cls):
-    return super().vary_on() + ['is_wasm']
+  def variations(cls):
+    combos = super().variations()
+    return ([dict(eh_mode=Exceptions.EMSCRIPTEN, **combo) for combo in combos] +
+            [dict(eh_mode=Exceptions.WASM_LEGACY, **combo) for combo in combos])
 
   @classmethod
   def get_default_variation(cls, **kwargs):
-    is_wasm = settings.SUPPORT_LONGJMP == 'wasm'
-    return super().get_default_variation(is_wasm=is_wasm, **kwargs)
+    if settings.SUPPORT_LONGJMP == 'wasm':
+      eh_mode = Exceptions.WASM_LEGACY
+    else:
+      eh_mode = Exceptions.EMSCRIPTEN
+    return super().get_default_variation(eh_mode=eh_mode, **kwargs)
 
 
 class MuslInternalLibrary(Library):
@@ -1537,7 +1542,7 @@ def can_use(self):
     return super().can_use() and settings.SHARED_MEMORY
 
 
-class libcxxabi(NoExceptLibrary, MTLibrary, DebugLibrary):
+class libcxxabi(ExceptionLibrary, MTLibrary, DebugLibrary):
   name = 'libc++abi'
   cflags = [
       '-Oz',
@@ -1569,7 +1574,7 @@ def get_cflags(self):
       # The code used to interpret exceptions during terminate
       # is not compatible with emscripten exceptions.
       cflags.append('-DLIBCXXABI_SILENT_TERMINATE')
-    elif self.eh_mode == Exceptions.WASM:
+    elif self.eh_mode == Exceptions.WASM_LEGACY:
       cflags.append('-D__WASM_EXCEPTIONS__')
     return cflags
 
@@ -1595,7 +1600,7 @@ def get_files(self):
       filenames += ['cxa_noexception.cpp']
     elif self.eh_mode == Exceptions.EMSCRIPTEN:
       filenames += ['cxa_exception_emscripten.cpp']
-    elif self.eh_mode == Exceptions.WASM:
+    elif self.eh_mode == Exceptions.WASM_LEGACY:
       filenames += [
         'cxa_exception_storage.cpp',
         'cxa_exception.cpp',
@@ -1609,7 +1614,7 @@ def get_files(self):
         filenames=filenames)
 
 
-class libcxx(NoExceptLibrary, MTLibrary):
+class libcxx(ExceptionLibrary, MTLibrary):
   name = 'libc++'
 
   cflags = [
@@ -1649,12 +1654,12 @@ class libcxx(NoExceptLibrary, MTLibrary):
 
   def get_cflags(self):
     cflags = super().get_cflags()
-    if self.eh_mode == Exceptions.WASM:
+    if self.eh_mode == Exceptions.WASM_LEGACY:
       cflags.append('-D__WASM_EXCEPTIONS__')
     return cflags
 
 
-class libunwind(NoExceptLibrary, MTLibrary):
+class libunwind(ExceptionLibrary, MTLibrary):
   name = 'libunwind'
   # Because calls to _Unwind_CallPersonality are generated during LTO, libunwind
   # can't currently be part of LTO.
@@ -1672,7 +1677,7 @@ def __init__(self, **kwargs):
     super().__init__(**kwargs)
 
   def can_use(self):
-    return super().can_use() and self.eh_mode == Exceptions.WASM
+    return super().can_use() and self.eh_mode == Exceptions.WASM_LEGACY
 
   def get_cflags(self):
     cflags = super().get_cflags()
@@ -1683,7 +1688,7 @@ def get_cflags(self):
       cflags.append('-D_LIBUNWIND_HAS_NO_EXCEPTIONS')
     elif self.eh_mode == Exceptions.EMSCRIPTEN:
       cflags.append('-D__EMSCRIPTEN_EXCEPTIONS__')
-    elif self.eh_mode == Exceptions.WASM:
+    elif self.eh_mode == Exceptions.WASM_LEGACY:
       cflags.append('-D__WASM_EXCEPTIONS__')
     return cflags