Create option for easy exception printing (#17219)

After #17064 and #17157 exception message printing is working, but it
still requires adding a lot of functions to `EXPORTED_FUNCTIONS` and
`DEFAULT_LIBRARY_FUNCS_TO_INLCLUDE`, which is difficult to use and
requires users to know unnecessary library internals:
https://github.com/emscripten-core/emscripten/blob/8c0fe77d8946a7ec2f73dfa74779ac957dd24530/tests/test_core.py#L1639-L1643

This adds `EXPORT_EXCEPTION_HANDLING_HELPERS` option, which adds                             
necessary symbols to those settings for easier use. This also exports
functions with which you can get the C++ tag and the thrown value from
`WebAssembly.Exception` object.

Author: aheejin

emcc.py

@@ -2613,6 +2613,18 @@ def get_full_import_name(name):
   if settings.WASM_EXCEPTIONS:
     settings.REQUIRED_EXPORTS += ['__trap']
 
+  # Make `getExceptionMessage` and other necessary functions available for use.
+  if settings.EXPORT_EXCEPTION_HANDLING_HELPERS:
+    # We also export refcount increasing and decreasing functions because if you
+    # catch an exception, be it an Emscripten exception or a Wasm exception, in
+    # JS, you may need to manipulate the refcount manually not to leak memory.
+    # What you need to do is different depending on the kind of EH you use
+    # (https://github.com/emscripten-core/emscripten/issues/17115).
+    settings.DEFAULT_LIBRARY_FUNCS_TO_INCLUDE += ['$getExceptionMessage', '$incrementExceptionRefcount', '$decrementExceptionRefcount']
+    settings.EXPORTED_FUNCTIONS += ['getExceptionMessage', '___get_exception_message']
+    if settings.WASM_EXCEPTIONS:
+      settings.EXPORTED_FUNCTIONS += ['___cpp_exception', '___cxa_increment_exception_refcount', '___cxa_decrement_exception_refcount', '___thrown_object_from_unwind_exception']
+
   apply_min_browser_versions(user_settings)
 
   return target, wasm_target

src/settings.js

@@ -686,6 +686,35 @@ var DISABLE_EXCEPTION_CATCHING = 1;
 // [compile+link] - affects user code at compile and system libraries at link
 var EXCEPTION_CATCHING_ALLOWED = [];
 
+// Make the exception message printing function, 'getExceptionMessage' available
+// in the JS library for use, by adding necessary symbols to EXPORTED_FUNCTIONS
+// and DEFAULT_LIBRARY_FUNCS_TO_INCLUDE.
+//
+// This works with both Emscripten EH and Wasm EH. When you catch an exception
+// from JS, that gives you a user-thrown value in case of Emscripten EH, and a
+// WebAssembly.Exception object in case of Wasm EH. 'getExceptionMessage' takes
+// the user-thrown value in case of Emscripten EH and the WebAssembly.Exception
+// object in case of Wasm EH, meaning in both cases you can pass a caught
+// exception directly to the function.
+//
+// When used with Wasm EH, this option additionally provides these functions in
+// the JS library:
+// - getCppExceptionTag: Returns the C++ tag
+// - getCppExceptionThrownObjectFromWebAssemblyException:
+//   Given an WebAssembly.Exception object, returns the actual user-thrown C++
+//   object address in Wasm memory.
+//
+// Setting this option also adds refcount increasing and decreasing functions
+// ('incrementExceptionRefcount' and 'decrementExceptionRefcount') in the JS
+// library because if you catch an exception from JS, you may need to manipulate
+// the refcount manually not to leak memory. What you need to do is different
+// depending on the kind of EH you use
+// (https://github.com/emscripten-core/emscripten/issues/17115).
+//
+// See test_EXPORT_EXCEPTION_HANDLING_HELPERS in tests/test_core.py for an
+// example usage.
+var EXPORT_EXCEPTION_HANDLING_HELPERS = false;
+
 // Internal: Tracks whether Emscripten should link in exception throwing (C++
 // 'throw') support library. This does not need to be set directly, but pass
 // -fno-exceptions to the build disable exceptions support. (This is basically

tests/test_core.py

@@ -1635,13 +1635,8 @@ def test_exceptions_rethrow_missing(self):
 
   @no_wasm64('MEMORY64 does not yet support exceptions')
   @with_both_eh_sjlj
-  def test_exception_message(self):
-    self.set_setting('DEFAULT_LIBRARY_FUNCS_TO_INCLUDE', ['$getExceptionMessage', '$incrementExceptionRefcount', '$decrementExceptionRefcount'])
-    self.set_setting('EXPORTED_FUNCTIONS', ['_main', 'getExceptionMessage', '___get_exception_message'])
-    if '-fwasm-exceptions' in self.emcc_args:
-      exports = self.get_setting('EXPORTED_FUNCTIONS')
-      self.set_setting('EXPORTED_FUNCTIONS', exports + ['___cpp_exception', '___cxa_increment_exception_refcount', '___cxa_decrement_exception_refcount', '___thrown_object_from_unwind_exception'])
-
+  def test_EXPORT_EXCEPTION_HANDLING_HELPERS(self):
+    self.set_setting('EXPORT_EXCEPTION_HANDLING_HELPERS')
     # FIXME Temporary workaround. See 'FIXME' in the test source code below for
     # details.
     if self.get_setting('DISABLE_EXCEPTION_CATCHING') == 0: