rename

Author: sbc100

ChangeLog.md

@@ -20,6 +20,12 @@ See docs/process.md for more on how version tagging works.
 
 Current Trunk
 -------------
+- The WebAssembly memory used by emscripten programs is now, by default, created
+  in the wasm file and exported to JavaScript.  Previously we could create the
+  memory in JavaScript and import it into the wasm file.  The new
+  `IMPORTED_MEMORY` setting can be used to revert to the old behaviour.  This
+  can be useful, for example, if the wasm memory needs to be created at runtime
+  before wasm instantiation.
 
 2.0.9: 11/16/2020
 -----------------

emcc.py

@@ -1740,7 +1740,7 @@ def include_and_export(name):
       shared.Settings.LEGALIZE_JS_FFI = 0
 
     if shared.Settings.USE_PTHREADS or shared.Settings.RELOCATABLE or shared.Settings.ASYNCIFY_LAZY_LOAD_CODE:
-      shared.Settings.EXTERNAL_MEMORY = 1
+      shared.Settings.IMPORTED_MEMORY = 1
 
     if shared.Settings.WASM_BIGINT:
       shared.Settings.LEGALIZE_JS_FFI = 0

emscripten.py

@@ -536,7 +536,7 @@ def create_em_js(forwarded_json, metadata):
 
 
 def add_standard_wasm_imports(send_items_map):
-  if shared.Settings.EXTERNAL_MEMORY:
+  if shared.Settings.IMPORTED_MEMORY:
     memory_import = 'wasmMemory'
     if shared.Settings.MODULARIZE and shared.Settings.USE_PTHREADS:
       # Pthreads assign wasmMemory in their worker startup. In MODULARIZE mode, they cannot assign inside the

src/postamble_minimal.js

@@ -208,7 +208,7 @@ WebAssembly.instantiate(Module['wasm'], imports).then(function(output) {
   assert(wasmTable);
 #endif
 
-#if !EXTERNAL_MEMORY
+#if !IMPORTED_MEMORY
   wasmMemory = asm['memory'];
 #if ASSERTIONS
   assert(wasmMemory);

src/preamble.js

@@ -325,16 +325,16 @@ if (typeof SharedArrayBuffer === 'undefined' || typeof Atomics === 'undefined')
 #endif
 #endif
 
-#if EXTERNAL_MEMORY
+#if IMPORTED_MEMORY
 // In non-standalone/normal mode, we create the memory here.
 #include "runtime_init_memory.js"
-#else // EXTERNAL_MEMORY
+#else // IMPORTED_MEMORY
 #if ASSERTIONS
 // If memory is defined in wasm, the user can't provide it.
-assert(!Module['wasmMemory'], 'Use of `wasmMemory` detected.  Use -s EXTERNAL_MEMORY to define wasmMemory externally');
-assert(INITIAL_MEMORY == {{{INITIAL_MEMORY}}}, 'Detected runtime INITIAL_MEMORY setting.  Use -s EXTERNAL_MEMORY to define wasmMemory dynamically');
+assert(!Module['wasmMemory'], 'Use of `wasmMemory` detected.  Use -s IMPORTED_MEMORY to define wasmMemory externally');
+assert(INITIAL_MEMORY == {{{INITIAL_MEMORY}}}, 'Detected runtime INITIAL_MEMORY setting.  Use -s IMPORTED_MEMORY to define wasmMemory dynamically');
 #endif // ASSERTIONS
-#endif // EXTERNAL_MEMORY
+#endif // IMPORTED_MEMORY
 
 #include "runtime_init_table.js"
 #include "runtime_stack_check.js"
@@ -834,11 +834,11 @@ function createWasm() {
 
     Module['asm'] = exports;
 
-#if !EXTERNAL_MEMORY
+#if !IMPORTED_MEMORY
     wasmMemory = Module['asm']['memory'];
 #if ASSERTIONS
     assert(wasmMemory);
-    // This asserting doesn't hold went emscripten is run in --post-link
+    // This assertion doesn't hold when emscripten is run in --post-link
     // mode.
     // TODO(sbc): Read INITIAL_MEMORY out of the wasm file in post-link mode.
     //assert(wasmMemory.buffer.byteLength === {{{ INITIAL_MEMORY }}});

src/preamble_minimal.js

@@ -73,7 +73,7 @@ function updateGlobalBufferAndViews(b) {
   HEAPF64 = new Float64Array(b);
 }
 
-#if EXTERNAL_MEMORY
+#if IMPORTED_MEMORY
 if (!ENVIRONMENT_IS_PTHREAD) {
 #if ALLOW_MEMORY_GROWTH && MAXIMUM_MEMORY != -1
   var wasmMaximumMemory = {{{ MAXIMUM_MEMORY >>> 16 }}};
@@ -98,7 +98,7 @@ if (ENVIRONMENT_IS_WORKER) {
 #else
 updateGlobalBufferAndViews(wasmMemory.buffer);
 #endif
-#endif // EXTERNAL_MEMORY
+#endif // IMPORTED_MEMORY
 
 #include "runtime_stack_check.js"
 #include "runtime_assertions.js"

src/runtime_init_memory.js

@@ -4,9 +4,9 @@
  * SPDX-License-Identifier: MIT
  */
 
-// Create the wasm memory. (Note: this only applies if EXTERNAL_MEMORY is defined)
-#if !EXTERNAL_MEMORY
-assert(false, "should be be included when EXTERNAL_MEMORY is set");
+// Create the wasm memory. (Note: this only applies if IMPORTED_MEMORY is defined)
+#if !IMPORTED_MEMORY
+{{{ throw "this file should not be be included when IMPORTED_MEMORY is set"; }}}
 #endif
 
 #if USE_PTHREADS

src/settings.js

@@ -1638,7 +1638,7 @@ var PURE_WASI = 0;
 // - USE_PTHREADS
 // - RELOCATABLE
 // - ASYNCIFY_LAZY_LOAD_CODE
-var EXTERNAL_MEMORY = 0;
+var IMPORTED_MEMORY = 0;
 
 //===========================================
 // Internal, used for testing only, from here

tests/test_core.py

@@ -2087,7 +2087,7 @@ def test_aborting_new(self, args):
   @no_asan('ASan alters the memory size')
   def test_module_wasm_memory(self):
     self.emcc_args += ['--pre-js', path_from_root('tests', 'core', 'test_module_wasm_memory.js')]
-    self.set_setting('EXTERNAL_MEMORY')
+    self.set_setting('IMPORTED_MEMORY')
     self.do_runf(path_from_root('tests', 'core', 'test_module_wasm_memory.c'), 'success')
 
   def test_ssr(self): # struct self-ref

tests/test_other.py

@@ -6477,13 +6477,13 @@ def test_binaryen_warn_mem(self):
     # if user changes INITIAL_MEMORY at runtime, the wasm module may not accept the memory import if
     # it is too big/small
     create_test_file('pre.js', 'var Module = { INITIAL_MEMORY: 50 * 1024 * 1024 };\n')
-    self.run_process([EMCC, path_from_root('tests', 'hello_world.cpp'), '-s', 'INITIAL_MEMORY=' + str(16 * 1024 * 1024), '--pre-js', 'pre.js', '-s', 'WASM_ASYNC_COMPILATION=0', '-s', 'EXTERNAL_MEMORY'])
+    self.run_process([EMCC, path_from_root('tests', 'hello_world.cpp'), '-s', 'INITIAL_MEMORY=' + str(16 * 1024 * 1024), '--pre-js', 'pre.js', '-s', 'WASM_ASYNC_COMPILATION=0', '-s', 'IMPORTED_MEMORY'])
     out = self.run_js('a.out.js', assert_returncode=NON_ZERO)
     self.assertContained('LinkError', out)
     self.assertContained('Memory size incompatibility issues may be due to changing INITIAL_MEMORY at runtime to something too large. Use ALLOW_MEMORY_GROWTH to allow any size memory (and also make sure not to set INITIAL_MEMORY at runtime to something smaller than it was at compile time).', out)
     self.assertNotContained('hello, world!', out)
     # and with memory growth, all should be good
-    self.run_process([EMCC, path_from_root('tests', 'hello_world.cpp'), '-s', 'INITIAL_MEMORY=' + str(16 * 1024 * 1024), '--pre-js', 'pre.js', '-s', 'ALLOW_MEMORY_GROWTH=1', '-s', 'WASM_ASYNC_COMPILATION=0', '-s', 'EXTERNAL_MEMORY'])
+    self.run_process([EMCC, path_from_root('tests', 'hello_world.cpp'), '-s', 'INITIAL_MEMORY=' + str(16 * 1024 * 1024), '--pre-js', 'pre.js', '-s', 'ALLOW_MEMORY_GROWTH=1', '-s', 'WASM_ASYNC_COMPILATION=0', '-s', 'IMPORTED_MEMORY'])
     self.assertContained('hello, world!', self.run_js('a.out.js'))
 
   def test_binaryen_mem(self):

tools/building.py

@@ -478,7 +478,7 @@ def lld_flags_for_executable(external_symbol_list):
   else:
     cmd.append('--allow-undefined')
 
-  if Settings.EXTERNAL_MEMORY:
+  if Settings.IMPORTED_MEMORY:
     cmd.append('--import-memory')
 
   if Settings.USE_PTHREADS:
@@ -1138,7 +1138,7 @@ def metadce(js_file, wasm_file, minify_whitespace, debug_info):
       if export in user_requested_exports or Settings.EXPORT_ALL:
         item['root'] = True
   # in standalone wasm, always export the memory
-  if not Settings.EXTERNAL_MEMORY:
+  if not Settings.IMPORTED_MEMORY:
     graph.append({
       'export': 'memory',
       'name': 'emcc$export$memory',