Deprecate export of module handlers via EXPORTED_RUNTIME_METHODS (#…

…17955)

`print` / `printErr` are handlers that can be overridden by the user
on the incoming module (just like `onAbort`) and not runtime elements
that can be exported. Deprecate the export of `print` / `printErr`
via `EXPORTED_RUNTIME_METHODS` in favor of `out` / `err`.

ChangeLog.md

@@ -20,6 +20,9 @@ See docs/process.md for more on how version tagging works.
 
 3.1.25 (in development)
 -----------------------
+- Exporting `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)
 
 3.1.24 - 10/11/22
 -----------------
@@ -394,7 +397,7 @@ See docs/process.md for more on how version tagging works.
    `isFunctionDef`, `isPossiblyFunctionType`, `isFunctionType`, `getReturnType`,
    `splitTokenList`, `_IntToHex`, `IEEEUnHex`, `Compiletime.isPointerType`,
    `Compiletime.isStructType`, `Compiletime.INT_TYPES`, `isType`.
-- The example `shell.html` and `shell_minimal.html` templaces no longer override
+- The example `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 effects application that use the

src/modules.js

@@ -311,6 +311,11 @@ function addMissingLibraryStubs() {
 function exportRuntime() {
   const EXPORTED_RUNTIME_METHODS_SET = new Set(EXPORTED_RUNTIME_METHODS);
 
+  const legacyRuntimeElements = new Map([
+    ['print', 'out'],
+    ['printErr', 'err'],
+  ]);
+
   // optionally export something.
   // in ASSERTIONS mode we show a useful error if it is used without
   // being exported. how we show the message depends on whether it's
@@ -323,10 +328,8 @@ function exportRuntime() {
       if (isFSPrefixed(exported)) {
         // this is a filesystem value, FS.x exported as FS_x
         exported = 'FS.' + exported.substr(3);
-      } else if (exported === 'print') {
-        exported = 'out';
-      } else if (exported === 'printErr') {
-        exported = 'err';
+      } else if (legacyRuntimeElements.has(exported)) {
+        exported = legacyRuntimeElements.get(exported);
       }
       return `Module["${name}"] = ${exported};`;
     }
@@ -361,8 +364,8 @@ function exportRuntime() {
     'registerFunctions',
     'prettyPrint',
     'getCompilerSetting',
-    'print',
-    'printErr',
+    'out',
+    'err',
     'callMain',
     'abort',
     'keepRuntimeAlive',
@@ -413,6 +416,15 @@ function exportRuntime() {
     }
   }
 
+  // Only export legacy runtime elements when explicitly
+  // requested.
+  for (const name of EXPORTED_RUNTIME_METHODS_SET) {
+    if (legacyRuntimeElements.has(name)) {
+      const newName = legacyRuntimeElements.get(name);
+      warn(`deprecated item in EXPORTED_RUNTIME_METHODS: ${name} use ${newName} instead.`);
+      runtimeElements.push(name);
+    }
+  }
 
   // Add JS library elements such as FS, GL, ENV, etc. These are prefixed with
   // '$ which indicates they are JS methods.

test/pthread/emscripten_thread_sleep.c

@@ -1,5 +1,6 @@
 #include <pthread.h>
 #include <emscripten.h>
+#include <emscripten/console.h>
 #include <emscripten/threading.h>
 #include <assert.h>
 #include <stdio.h>
@@ -16,7 +17,7 @@ void Sleep(double msecs)
 
 void *thread_main(void *arg)
 {
-	EM_ASM(Module.print('hello from thread!'));
+	_emscripten_out("hello from thread!");
 
 	Sleep(1);
 	Sleep(10);

test/test_browser.py

@@ -4904,7 +4904,7 @@ def test_unicode_html_shell(self):
   # Tests the functionality of the emscripten_thread_sleep() function.
   @requires_threads
   def test_emscripten_thread_sleep(self):
-    self.btest_exit(test_file('pthread/emscripten_thread_sleep.c'), args=['-sUSE_PTHREADS', '-sEXPORTED_RUNTIME_METHODS=[print]'])
+    self.btest_exit(test_file('pthread/emscripten_thread_sleep.c'), args=['-sUSE_PTHREADS'])
 
   # Tests that Emscripten-compiled applications can be run from a relative path in browser that is different than the address of the current page
   def test_browser_run_from_different_directory(self):

test/test_other.py

@@ -7132,7 +7132,7 @@ def test(contents):
     self.run_process([EMXX, 'src.cpp', '-O2']) # optimized, so no assertions
     self.assertNotContained(error, read_file('a.out.js'))
 
-  def test_warn_module_print_err(self):
+  def test_warn_module_out_err(self):
     error = 'was not exported. add it to EXPORTED_RUNTIME_METHODS (see the FAQ)'
 
     def test(contents, expected, args=[], assert_returncode=0):  # noqa
@@ -7147,12 +7147,15 @@ def test(contents, expected, args=[], assert_returncode=0):  # noqa
       self.assertContained(expected, self.run_js('a.out.js', assert_returncode=assert_returncode))
 
     # error shown (when assertions are on)
-    test("Module.print('x')", error, assert_returncode=NON_ZERO)
-    test("Module['print']('x')", error, assert_returncode=NON_ZERO)
-    test("Module.printErr('x')", error, assert_returncode=NON_ZERO)
-    test("Module['printErr']('x')", error, assert_returncode=NON_ZERO)
+    test("Module.out('x')", error, assert_returncode=NON_ZERO)
+    test("Module['out']('x')", error, assert_returncode=NON_ZERO)
+    test("Module.err('x')", error, assert_returncode=NON_ZERO)
+    test("Module['err']('x')", error, assert_returncode=NON_ZERO)
 
     # when exported, all good
+    test("Module['out']('print'); Module['err']('err'); ", 'print\nerr', ['-sEXPORTED_RUNTIME_METHODS=out,err'])
+
+    # test backwards compatibility
     test("Module['print']('print'); Module['printErr']('err'); ", 'print\nerr', ['-sEXPORTED_RUNTIME_METHODS=print,printErr'])
 
   def test_warn_unexported_main(self):