Move LEGALIZE_JS_FFI to legacy settings list

ChangeLog.md

@@ -27,6 +27,11 @@ See docs/process.md for more on how version tagging works.
   level- and edge-triggered modes, `EPOLLONESHOT`, `EPOLLEXCLUSIVE`,
   `EPOLLRDHUP`, nesting, and blocking waits under `PROXY_TO_PTHREAD`,
   `ASYNCIFY`, and `JSPI`. (#27207)
+- The deprecated `LEGALIZE_JS_FFI` setting was completely removed and moved to
+  legacy settings.  This behaviour of lowering away i64 values at the
+  Wasm bounary is still used when `WASM_BIGINT` is disabled.  However
+  disabling of `WASM_BIGINT` itself should only be needed under `-sWASM=0`
+  (where it is automatically disabled). (#27568)
 
 6.0.7 - 08/17/26
 ----------------

site/source/docs/tools_reference/settings_reference.rst

@@ -2183,20 +2183,6 @@ Emits emscripten license info in the JS output.
 
 Default value: false
 
-.. _legalize_js_ffi:
-
-LEGALIZE_JS_FFI
-===============
-
-Whether to lower i64 parameters and return values for function
-imports/exports.  This is done by lowering them to pairs of i32 and should
-only be needed on JS engines that do not have Wasm/BigInt integration.
-This is automatically enabled when WASM_BIGINT is disabled.
-
-.. note:: This setting is deprecated
-
-Default value: false
-
 .. _use_sdl:
 
 USE_SDL
@@ -3553,7 +3539,6 @@ these settings please open a bug (or reply to one of the existing bugs).
 
  - ``RUNTIME_LINKED_LIBS``: you can simply list the libraries directly on the commandline now
  - ``CLOSURE_WARNINGS``: use -Wclosure/-Wno-closure instead
- - ``LEGALIZE_JS_FFI``: to disable JS type legalization use `-sWASM_BIGINT` or `-sSTANDALONE_WASM`
  - ``ASYNCIFY_EXPORTS``: please use JSPI_EXPORTS instead
  - ``LINKABLE``: under consideration for removal (https://github.com/emscripten-core/emscripten/issues/25262)
  - ``EXPORT_EXCEPTION_HANDLING_HELPERS``: 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.
@@ -3653,3 +3638,4 @@ for backwards compatibility with older versions:
  - ``RELOCATABLE``: No longer supported (Valid values: [0])
  - ``WASM_JS_TYPES``: No longer supported (Valid values: [0])
  - ``DETERMINISTIC``: No longer supported (Valid values: [0])
+ - ``LEGALIZE_JS_FFI``: legacy JS FFI legalization is no longer supported (Valid values: [0])

src/settings.js

@@ -1521,14 +1521,6 @@ var EMIT_PRODUCERS_SECTION = false;
 // [link]
 var EMIT_EMSCRIPTEN_LICENSE = false;
 
-// Whether to lower i64 parameters and return values for function
-// imports/exports.  This is done by lowering them to pairs of i32 and should
-// only be needed on JS engines that do not have Wasm/BigInt integration.
-// This is automatically enabled when WASM_BIGINT is disabled.
-// [link]
-// [deprecated]
-var LEGALIZE_JS_FFI = false;
-
 // Ports
 
 // Specify the SDL version that is being linked against.

test/test_other.py

@@ -8574,17 +8574,17 @@ def test_exported_runtime_methods_metadce(self):
       self.assertContained(f'Module["{export}"]', js)
 
   @parameterized({
-    'legal_side_O1': (['-sLEGALIZE_JS_FFI=1', '-sSIDE_MODULE', '-O1'], True),
-    'nolegal_side_O1': (['-sLEGALIZE_JS_FFI=0', '-sSIDE_MODULE', '-O1'], False),
-    'nolegal_side_O0': (['-sLEGALIZE_JS_FFI=0', '-sSIDE_MODULE', '-O0'], False),
-    'legal_O0': (['-sLEGALIZE_JS_FFI=1', '-sWARN_ON_UNDEFINED_SYMBOLS=0', '-O0'], True),
-    'nolegal_O0': (['-sLEGALIZE_JS_FFI=0', '-sWARN_ON_UNDEFINED_SYMBOLS=0', '-O0'], False),
+    'legal_side_O1': (['-sSIDE_MODULE', '-O1', '-sWASM_BIGINT=0'], True),
+    'nolegal_side_O1': (['-sSIDE_MODULE', '-O1', '-sWASM_BIGINT=1'], False),
+    'nolegal_side_O0': (['-sSIDE_MODULE', '-O0', '-sWASM_BIGINT=1'], False),
+    'legal_O0': (['-sWARN_ON_UNDEFINED_SYMBOLS=0', '-O0', '-sWASM_BIGINT=0'], True),
+    'nolegal_O0': (['-sWARN_ON_UNDEFINED_SYMBOLS=0', '-O0', '-sWASM_BIGINT=1'], False),
   })
   def test_legalize_js_ffi(self, args, js_ffi):
-    # test disabling of JS FFI legalization when not using bigint
+    # test disabling of JS FFI legalization when using bigint
     print(args)
     delete_file('a.out.wasm')
-    cmd = [EMCC, test_file('other/test_legalize_js_ffi.c'), '-g', '-o', 'a.out.wasm', '-sWASM_BIGINT=0'] + args
+    cmd = [EMCC, test_file('other/test_legalize_js_ffi.c'), '-g', '-o', 'a.out.wasm'] + args
     print(' '.join(cmd))
     self.run_process(cmd)
     text = self.get_wasm_text('a.out.wasm')
@@ -8608,13 +8608,13 @@ def test_legalize_js_ffi(self, args, js_ffi):
       assert not e_i64_i32, 'i64 converted to i32 in exports'
 
   def test_legalize_js_ffi_cpp(self):
-    for legalizing in (0, 1):
+    for bigint in (0, 1):
       # test minimal JS FFI legalization for invoke and dyncalls
-      args = ['-sMAIN_MODULE=2', '-O3', '-sDISABLE_EXCEPTION_CATCHING=0', '-g', '-sWASM_BIGINT=0']
-      args.append(f'-sLEGALIZE_JS_FFI={legalizing}')
+      args = ['-sMAIN_MODULE=2', '-O3', '-sDISABLE_EXCEPTION_CATCHING=0', '-g', f'-sWASM_BIGINT={bigint}']
       self.run_process([EMXX, test_file('other/test_legalize_js_ffi_cpp.cpp')] + args)
       text = self.get_wasm_text('a.out.wasm')
       # Verify that legalization either did, or did not, occur
+      legalizing = not bigint
       self.assertContainedIf('$legalimport', text, legalizing)
       self.assertContainedIf('$legalstub', text, legalizing)
 

tools/emscripten.py

@@ -533,7 +533,7 @@ def finalize_wasm(infile, outfile, js_syms):
     # to force wasm-emscripten-finalize not to do any legalization at all.
     args.append('--bigint')
   else:
-    if settings.LEGALIZE_JS_FFI:
+    if not settings.WASM_BIGINT:
       # When we dynamically link our JS loader adds functions from wasm modules to
       # the table. It must add the original versions of them, not legalized ones,
       # so that indirect calls have the right type, so export those.

tools/link.py

@@ -345,7 +345,7 @@ def get_binaryen_passes():
     passes += ['--instrument-locals']
     passes += ['--log-execution']
     passes += ['--instrument-memory']
-    if settings.LEGALIZE_JS_FFI:
+    if not settings.WASM_BIGINT:
       # legalize it again now, as the instrumentation may need it
       passes += ['--legalize-js-interface']
       passes += building.js_legalization_pass_flags()
@@ -1639,9 +1639,6 @@ def limit_incoming_module_api():
     # module names buys nothing and would break that rewrite.
     settings.MINIFY_WASM_IMPORTED_MODULES = not settings.WASM_ESM_INTEGRATION
 
-  if not settings.WASM_BIGINT:
-    default_setting('LEGALIZE_JS_FFI', 1)
-
   if settings.SINGLE_FILE and settings.GENERATE_SOURCE_MAP:
     diagnostics.warning('emcc', 'SINGLE_FILE disables source map support (which requires a .map file)')
     settings.GENERATE_SOURCE_MAP = 0
@@ -1652,7 +1649,7 @@ def limit_incoming_module_api():
   if settings.AUTODEBUG:
     settings.REQUIRED_EXPORTS += ['_emscripten_tempret_set']
 
-  if settings.LEGALIZE_JS_FFI:
+  if not settings.WASM_BIGINT:
     settings.REQUIRED_EXPORTS += ['__get_temp_ret', '__set_temp_ret']
 
   if settings.SPLIT_MODULE:

tools/settings.py

@@ -109,7 +109,6 @@
 DEPRECATED_SETTINGS = {
     'RUNTIME_LINKED_LIBS': 'you can simply list the libraries directly on the commandline now',
     'CLOSURE_WARNINGS': 'use -Wclosure/-Wno-closure instead',
-    'LEGALIZE_JS_FFI': 'to disable JS type legalization use `-sWASM_BIGINT` or `-sSTANDALONE_WASM`',
     'ASYNCIFY_EXPORTS': 'please use JSPI_EXPORTS instead',
     'LINKABLE': 'under consideration for removal (https://github.com/emscripten-core/emscripten/issues/25262)',
     'EXPORT_EXCEPTION_HANDLING_HELPERS': '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.',
@@ -265,6 +264,7 @@
     ['RELOCATABLE', [0], 'No longer supported'],
     ['WASM_JS_TYPES', [0], 'No longer supported'],
     ['DETERMINISTIC', [0], 'No longer supported'],
+    ['LEGALIZE_JS_FFI', [0], 'legacy JS FFI legalization is no longer supported'],
 ]
 
 user_settings: dict[str, str] = {}