Remove legacy library symbols: $ALLOC_NORMAL, $ALLOC_STACK, $allocate (emscripten-core#27378)

Remove `$ALLOC_NORMAL`, `$ALLOC_STACK`, and `$allocate` from
`liblegacy.js` and `extraLibraryFuncs` in `libcore.js`.

These symbols were moved to `library_legacy.js` when the file was first
created in July 2022 (emscripten-core#17390). They have produced `-Wdeprecated`
warnings on usage since February 2024 (emscripten-core#21357), over 2 years ago, giving
external users plenty time to transition.

The `test_legacy_exported_runtime_numbers` test in `test_core.py` is
also removed since it specifically tested `$ALLOC_STACK`. The error
messages checked by that test are covered elsewhere in `test_other.py`:
- "was not exported" is covered by `test_warn_module_out_err` and
  `test_exported_runtime_methods_from_js_library`.
- "is a library symbol and not included by default" is covered by
  `test_removed_runtime_function` and `test_legacy_runtime`.

Author: sbc100

ChangeLog.md

@@ -22,6 +22,8 @@ See docs/process.md for more on how version tagging works.
 ----------------------
 - Legacy support for ancient vendor-prefixed DOM APIs was removed (#27341,
   #27339, #27338, #27340, #27347)
+- Removed legacy JS library symbols symbols: `$ALLOC_NORMAL`, `$ALLOC_STACK`,
+  and `$allocate`. (#27378)
 
 6.0.3 - 07/13/26
 ----------------

site/source/docs/api_reference/preamble.js.rst

@@ -425,17 +425,11 @@ types. The views for accessing different types of memory are listed below.
 
 
 .. COMMENT (not rendered) : The following methods are explicitly not part of the public API and not documented. Note that in some case referred to by function name, other cases by Module assignment.
-
-  function allocate(slab, types, allocator, ptr) — Internal and use is discouraged. Documentation can remain in source code but not here.
-    associated constants ALLOC_NORMAL, ALLOC_STACK
-
   function addOnPreRun
   function addOnInit
   function addOnPreMain
   function addOnExit
   function addOnPostRun
-  Module['ALLOC_NORMAL'] = ALLOC_NORMAL;
-  Module['ALLOC_STACK'] = ALLOC_STACK;
   Module['HEAP'] = HEAP;
   Module['IHEAP'] = IHEAP;
   function demangle(func)

src/lib/libcore.js

@@ -2455,9 +2455,6 @@ function autoAddDeps(lib, name) {
 extraLibraryFuncs.push(
   '$addFunction',
   '$removeFunction',
-  '$allocate',
-  '$ALLOC_NORMAL',
-  '$ALLOC_STACK',
   '$AsciiToString',
   '$stringToAscii',
   '$UTF16ToString',

src/lib/liblegacy.js

@@ -15,38 +15,6 @@
  */
 
 legacyFuncs = {
-  $ALLOC_NORMAL: 0,  // Tries to use _malloc()
-  $ALLOC_STACK: 1,  // Lives for the duration of the current function call
-
-  /**
-   * allocate(): This function is no longer used by emscripten but is kept around to avoid
-   *             breaking external users.
-   *             You should normally not use allocate(), and instead allocate
-   *             memory using _malloc()/stackAlloc(), initialize it with
-   *             setValue(), and so forth.
-   * @param {(Uint8Array|Array<number>)} slab: An array of data.
-   * @param {number=} allocator : How to allocate memory, see ALLOC_*
-   */
-  $allocate__deps: ['$ALLOC_STACK', 'malloc', '$stackAlloc'],
-  $allocate: (slab, allocator) => {
-    var ret;
-  #if ASSERTIONS
-    assert(typeof allocator == 'number', 'allocate no longer takes a type argument')
-    assert(typeof slab != 'number', 'allocate no longer takes a number as arg0')
-  #endif
-
-    if (allocator == ALLOC_STACK) {
-      ret = stackAlloc(slab.length);
-    } else {
-      ret = _malloc(slab.length);
-    }
-
-    if (!slab.subarray && !slab.slice) {
-      slab = new Uint8Array(slab);
-    }
-    HEAPU8.set(slab, ret);
-    return ret;
-  },
 
   // Deprecated: This function should not be called because it is unsafe and
   // does not provide a maximum length limit of how many bytes it is allowed to

system/include/emscripten/em_macros.h

@@ -31,10 +31,10 @@
  * setting.
  *
  * For example, if your code contains an EM_ASM or EM_JS block that make use of
- * the allocate and stackSave JS library functions then you might write this in
+ * the stringToNewUTF8 and stackSave JS library functions then you might write this in
  * your library source code:
  *
- *   EM_JS_DEPS(mylib_dep, "$allocate,$stackSave");
+ *   EM_JS_DEPS(mylib_dep, "$stringToNewUTF8,$stackSave");
  *
  * The emscripten linker will then pick this up and make sure those symbols get
  * included in the JS support library.

test/codesize/test_codesize_hello_O0.json

@@ -1,10 +1,10 @@
 {
-  "a.out.js": 23661,
-  "a.out.js.gz": 8600,
+  "a.out.js": 23627,
+  "a.out.js.gz": 8586,
   "a.out.nodebug.wasm": 15115,
   "a.out.nodebug.wasm.gz": 7464,
-  "total": 38776,
-  "total_gz": 16064,
+  "total": 38742,
+  "total_gz": 16050,
   "sent": [
     "fd_write"
   ],

test/codesize/test_unoptimized_code_size.json

@@ -1,6 +1,6 @@
 {
-  "hello_world.js": 56342,
-  "hello_world.js.gz": 17727,
+  "hello_world.js": 56293,
+  "hello_world.js.gz": 17712,
   "hello_world.wasm": 15115,
   "hello_world.wasm.gz": 7464,
   "no_asserts.js": 25511,
@@ -11,6 +11,6 @@
   "strict.js.gz": 16711,
   "strict.wasm": 15115,
   "strict.wasm.gz": 7461,
-  "total": 177756,
-  "total_gz": 64046
+  "total": 177707,
+  "total_gz": 64031
 }

test/core/legacy_exported_runtime_numbers.cpp

@@ -7302,40 +7302,6 @@ def test(output_prefix='', args=None, assert_returncode=0):
     self.set_setting('EXPORTED_RUNTIME_METHODS', ['FS_createDataFile'])
     test(args=['-sFORCE_FILESYSTEM'])
 
-  @no_modularize_instance('uses Module object directly')
-  @no_strict('This test verifies legacy behavior that does not apply to -sSTRICT builds.')
-  def test_legacy_exported_runtime_numbers(self):
-    # these used to be exported, but no longer are by default
-    def test(expected, args=None, assert_returncode=0):
-      self.do_runf('core/legacy_exported_runtime_numbers.cpp', expected,
-                   assert_returncode=assert_returncode, cflags=args)
-
-    # Without assertion indirect usages (via Module) result in `undefined` and direct usage
-    # generates a builtin (not very helpful) JS error.
-    self.set_setting('ASSERTIONS', 0)
-    self.set_setting('LEGACY_RUNTIME', 0)
-    test('|undefined|')
-    test('ALLOC_STACK is not defined', args=['-DDIRECT'], assert_returncode=NON_ZERO)
-
-    # When assertions are enabled direct and indirect usage both abort with a useful error message.
-    not_exported = "'ALLOC_STACK' was not exported. add it to EXPORTED_RUNTIME_METHODS (see the Emscripten FAQ)"
-    not_included = "`ALLOC_STACK` is a library symbol and not included by default; add it to your library.js __deps or to DEFAULT_LIBRARY_FUNCS_TO_INCLUDE on the command line (e.g. -sDEFAULT_LIBRARY_FUNCS_TO_INCLUDE='$ALLOC_STACK')"
-    self.set_setting('ASSERTIONS')
-    test(not_exported, assert_returncode=NON_ZERO)
-    test(not_included, args=['-DDIRECT'])
-
-    # Adding the symbol to DEFAULT_LIBRARY_FUNCS_TO_INCLUDE should allow direct usage, but
-    # Module usage should continue to fail.
-    self.cflags += ['-Wno-deprecated']
-    self.set_setting('DEFAULT_LIBRARY_FUNCS_TO_INCLUDE', ['$ALLOC_STACK'])
-    test(not_exported, assert_returncode=NON_ZERO)
-    test('1', args=['-DDIRECT'])
-
-    # Adding the symbols to EXPORTED_RUNTIME_METHODS should make both usage patterns work.
-    self.set_setting('EXPORTED_RUNTIME_METHODS', ['ALLOC_STACK'])
-    test('|1|')
-    test('|1|', args=['-DDIRECT'])
-
   def test_linker_response_file(self):
     objfile = 'response_file.o'
     out_js = self.output_name('response_file')