Add addToLibrary compile time helper function (emscripten-core#20044)

This function replaces the exists `mergeInto`, with something that is
more precise and self-describing.

The old `mergeInfo` function still exists for backwards compat.

ChangeLog.md

@@ -20,6 +20,10 @@ See docs/process.md for more on how version tagging works.
 
 3.1.45 (in development)
 -----------------------
+- The function used to add symbols the JS library has been renamed from
+  `mergeInto`, to the more specific `addToLibrary`.  This new function does not
+  require the passing of `LibraryManager.library` as a first argument.  The old
+  `mergeInto` continues to exist for backwards compat.
 
 3.1.44 - 07/25/23
 -----------------

site/source/docs/porting/connecting_cpp_and_javascript/Interacting-with-code.rst

@@ -412,15 +412,15 @@ If you add it to your own file, you should write something like
 
 .. code-block:: javascript
 
-   mergeInto(LibraryManager.library, {
+   addToLibrary({
      my_js: function() {
        alert('hi');
      },
    });
 
-``mergeInto`` just copies the properties on the second parameter onto the
-first, so this add ``my_js`` onto ``LibraryManager.library``, the global
-object where all JavaScript library code should be.
+``addToLibrary`` copies the properties of the input object into
+``LibraryManager.library`` (the global object where all JavaScript library code
+lives). In this case its adds a function called ``my_js`` onto this object.
 
 JavaScript limits in library files
 ----------------------------------
@@ -438,7 +438,7 @@ that you can't use a closure directly, for example, as ``toString``
 isn't compatible with that - just like when using a string to create
 a Web Worker, where you also can't pass a closure. (Note that this
 limitation is just for the values for the keys of the object
-passes to ``mergeInto`` in the JS library, that is, the toplevel
+passes to ``addToLibrary`` in the JS library, that is, the toplevel
 key-value pairs are special. Interior code inside a function can
 have arbitrary JS, of course).
 
@@ -453,7 +453,7 @@ initialization.
 
 .. code-block:: javascript
 
-   mergeInto(LibraryManager.library, {
+   addToLibrary({
 
      // Solution for bind or referencing other functions directly
      good_02__postset: '_good_02();',
@@ -511,7 +511,7 @@ various methods to the functions we actually want.
 
 .. code-block:: javascript
 
-  mergeInto(LibraryManager.library, {
+  addToLibrary({
     $method_support: {},
     $method_support__postset: [
       '(function() {                                  ',
@@ -554,7 +554,7 @@ a function,
 
 .. code-block:: javascript
 
-  mergeInto(LibraryManager.library, {
+  addToLibrary({
     $method_support__postset: 'method_support();',
     $method_support: function() {
       var SomeLib = function() {
@@ -601,7 +601,7 @@ See the `library_*.js`_ files for other examples.
      This is useful when all the implemented methods use a JavaScript
      singleton containing helper methods. See ``library_webgl.js`` for
      an example.
-   - The keys passed into `mergeInto` generate functions that are prefixed
+   - The keys passed into `addToLibrary` generate functions that are prefixed
      by ``_``. In other words ``my_func: function() {},`` becomes
      ``function _my_func() {}``, as all C methods in emscripten have a ``_`` prefix. Keys starting with ``$`` have the ``$``
      stripped and no underscore added.

src/embind/embind.js

@@ -3,7 +3,7 @@
 // University of Illinois/NCSA Open Source License.  Both these licenses can be
 // found in the LICENSE file.
 
-/*global LibraryManager, mergeInto*/
+/*global addToLibrary*/
 
 /*global Module, asm*/
 /*global _malloc, _free, _memcpy*/
@@ -2412,4 +2412,4 @@ var LibraryEmbind = {
   },
 };
 
-mergeInto(LibraryManager.library, LibraryEmbind);
+addToLibrary(LibraryEmbind);

src/embind/embind_shared.js

@@ -146,4 +146,4 @@ var LibraryEmbindShared = {
   }
 };
 
-mergeInto(LibraryManager.library, LibraryEmbindShared);
+addToLibrary(LibraryEmbindShared);

src/embind/embind_ts.js

@@ -539,4 +539,4 @@ var LibraryEmbind = {
 
 DEFAULT_LIBRARY_FUNCS_TO_INCLUDE.push('$embindEmitTypes');
 
-mergeInto(LibraryManager.library, LibraryEmbind);
+addToLibrary(LibraryEmbind);

src/embind/emval.js

@@ -13,7 +13,7 @@
 
 // -- jshint doesn't understand library syntax, so we need to mark the symbols exposed here
 /*global getStringOrSymbol, emval_handles, Emval, __emval_unregister, count_emval_handles, emval_symbols, __emval_decref, emval_newers*/
-/*global craftEmvalAllocator, emval_addMethodCaller, emval_methodCallers, LibraryManager, mergeInto, emval_allocateDestructors, global, emval_lookupTypes, makeLegalFunctionName*/
+/*global craftEmvalAllocator, emval_addMethodCaller, emval_methodCallers, addToLibrary, emval_allocateDestructors, global, emval_lookupTypes, makeLegalFunctionName*/
 /*global emval_get_global*/
 
 var LibraryEmVal = {
@@ -540,4 +540,4 @@ var LibraryEmVal = {
 #endif
 };
 
-mergeInto(LibraryManager.library, LibraryEmVal);
+addToLibrary(LibraryEmVal);

src/library.js

@@ -20,7 +20,7 @@
 // object. For convenience, the short name appears here. Note that if you add a
 // new function with an '_', it will not be found.
 
-mergeInto(LibraryManager.library, {
+addToLibrary({
   $ptrToString: (ptr) => {
 #if ASSERTIONS
     assert(typeof ptr === 'number');

src/library_addfunction.js

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: MIT
  */
 
-mergeInto(LibraryManager.library, {
+addToLibrary({
   // This gives correct answers for everything less than 2^{14} = 16384
   // I hope nobody is contemplating functions with 16384 arguments...
   $uleb128Encode: (n, target) => {

src/library_async.js

@@ -8,7 +8,7 @@
 // Async support via ASYNCIFY
 //
 
-mergeInto(LibraryManager.library, {
+addToLibrary({
   // error handling
 
   $runAndAbortIfError: (func) => {

src/library_autodebug.js

@@ -9,7 +9,7 @@
 #error "Should only be incldued in AUTODEBUG mode"
 #endif
 
-mergeInto(LibraryManager.library, {
+addToLibrary({
   $log_execution: (loc) => dbg('log_execution ' + loc),
   $get_i32: (loc, index, value) => {
     dbg('get_i32 ' + [loc, index, value]);

src/library_bootstrap.js

@@ -12,7 +12,7 @@ assert(false, "library_bootstrap.js only designed for use with BOOTSTRAPPING_STR
 #endif
 
 assert(Object.keys(LibraryManager.library).length === 0);
-mergeInto(LibraryManager.library, {
+addToLibrary({
   $callRuntimeCallbacks: () => {},
 
   $ExitStatus__docs: '/** @constructor */',

src/library_browser.js

@@ -1319,4 +1319,4 @@ var LibraryBrowser = {
 
 autoAddDeps(LibraryBrowser, '$Browser');
 
-mergeInto(LibraryManager.library, LibraryBrowser);
+addToLibrary(LibraryBrowser);

src/library_c_preprocessor.js

@@ -1,4 +1,4 @@
-mergeInto(LibraryManager.library, {
+addToLibrary({
   // Removes all C++ '//' and '/* */' comments from the given source string.
   // N.b. will also eat comments inside strings.
   $remove_cpp_comments_in_shaders: (code) => {

src/library_ccall.js

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: MIT
  */
 
-mergeInto(LibraryManager.library, {
+addToLibrary({
   // Returns the C function with a specified identifier (for C++, you need to do manual name mangling)
   $getCFunc: (ident) => {
     var func = Module['_' + ident]; // closure exported function

src/library_cyberdwarf.js

@@ -10,4 +10,4 @@ var LibraryCyberdwarf = {
   metadata_llvm_dbg_value_local: (a,b,c,d) => {}
 };
 
-mergeInto(LibraryManager.library, LibraryCyberdwarf);
+addToLibrary(LibraryCyberdwarf);

src/library_dylink.js

@@ -1258,4 +1258,4 @@ var LibraryDylink = {
   },
 };
 
-mergeInto(LibraryManager.library, LibraryDylink);
+addToLibrary(LibraryDylink);

src/library_egl.js

@@ -675,4 +675,4 @@ var LibraryEGL = {
 
 autoAddDeps(LibraryEGL, '$EGL');
 
-mergeInto(LibraryManager.library, LibraryEGL);
+addToLibrary(LibraryEGL);

src/library_eventloop.js

@@ -146,4 +146,4 @@ LibraryJSEventLoop = {
   },
 };
 
-mergeInto(LibraryManager.library, LibraryJSEventLoop);
+addToLibrary(LibraryJSEventLoop);

src/library_exceptions.js

@@ -422,4 +422,4 @@ for (let i = 2; i < 5; i++) {
 }
 #endif
 
-mergeInto(LibraryManager.library, LibraryExceptions);
+addToLibrary(LibraryExceptions);

src/library_exceptions_stub.js

@@ -29,4 +29,4 @@ var LibraryExceptions = {};
 #endif
 });
 
-mergeInto(LibraryManager.library, LibraryExceptions);
+addToLibrary(LibraryExceptions);

src/library_exports.js

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: MIT
  */
 
-mergeInto(LibraryManager.library, {
+addToLibrary({
   emscripten_get_exported_function__deps: ['$addFunction', '$UTF8ToString'],
   emscripten_get_exported_function: (name) => {
     name = UTF8ToString(name);

src/library_fetch.js

@@ -40,4 +40,4 @@ var LibraryFetch = {
   ]
 };
 
-mergeInto(LibraryManager.library, LibraryFetch);
+addToLibrary(LibraryFetch);

src/library_fetchfs.js

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: MIT
  */
 
-mergeInto(LibraryManager.library, {
+addToLibrary({
   $FETCHFS__deps: ['$stringToUTF8OnStack', 'wasmfs_create_fetch_backend'],
   $FETCHFS: {
     createBackend(opts) {

src/library_formatString.js

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: MIT
  */
 
-mergeInto(LibraryManager.library, {
+addToLibrary({
   $reallyNegative: (x) => x < 0 || (x === 0 && (1/x) === -Infinity),
 
   // Converts a value we have as signed, into an unsigned value. For

src/library_fs.js

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: MIT
  */
 
-mergeInto(LibraryManager.library, {
+addToLibrary({
   $FS__deps: ['$randomFill', '$PATH', '$PATH_FS', '$TTY', '$MEMFS',
     '$FS_createPreloadedFile',
     '$FS_modeStringToFlags',

src/library_fs_shared.js

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: MIT
  */
 
-mergeInto(LibraryManager.library, {
+addToLibrary({
   $preloadPlugins: "{{{ makeModuleReceiveExpr('preloadPlugins', '[]') }}}",
 
 #if !MINIMAL_RUNTIME

src/library_getvalue.js

@@ -74,4 +74,4 @@ var LibraryMemOps = {
 #endif
 };
 
-mergeInto(LibraryManager.library, LibraryMemOps);
+addToLibrary(LibraryMemOps);

src/library_glemu.js

@@ -3910,7 +3910,7 @@ if (LEGACY_GL_EMULATION) {
 
 recordGLProcAddressGet(LibraryGLEmulation);
 
-mergeInto(LibraryManager.library, LibraryGLEmulation);
+addToLibrary(LibraryGLEmulation);
 
 assert(!(FULL_ES2 && LEGACY_GL_EMULATION), 'cannot emulate both ES2 and legacy GL');
 assert(!(FULL_ES3 && LEGACY_GL_EMULATION), 'cannot emulate both ES3 and legacy GL');

src/library_glew.js

@@ -132,4 +132,4 @@ var LibraryGLEW = {
 };
 
 autoAddDeps(LibraryGLEW, '$GLEW');
-mergeInto(LibraryManager.library, LibraryGLEW);
+addToLibrary(LibraryGLEW);

src/library_glfw.js

@@ -1806,4 +1806,4 @@ var LibraryGLFW = {
 };
 
 autoAddDeps(LibraryGLFW, '$GLFW');
-mergeInto(LibraryManager.library, LibraryGLFW);
+addToLibrary(LibraryGLFW);

src/library_glut.js

@@ -640,4 +640,4 @@ var LibraryGLUT = {
 };
 
 autoAddDeps(LibraryGLUT, '$GLUT');
-mergeInto(LibraryManager.library, LibraryGLUT);
+addToLibrary(LibraryGLUT);

src/library_html5.js

@@ -2595,4 +2595,4 @@ var LibraryHTML5 = {
   }
 };
 
-mergeInto(LibraryManager.library, LibraryHTML5);
+addToLibrary(LibraryHTML5);

src/library_html5_webgl.js

@@ -595,4 +595,4 @@ handleWebGLProxying(LibraryHtml5WebGL);
 autoAddDeps(LibraryHtml5WebGL, '$GL');
 #endif
 
-mergeInto(LibraryManager.library, LibraryHtml5WebGL);
+addToLibrary(LibraryHtml5WebGL);

src/library_html5_webgpu.js

@@ -90,4 +90,4 @@ var LibraryHTML5WebGPU = {
 {{{ html5_gpu.makeImportExport('render_bundle_encoder', 'RenderBundleEncoder') }}}
 {{{ html5_gpu.makeImportExport('render_bundle', 'RenderBundle') }}}
 
-mergeInto(LibraryManager.library, LibraryHTML5WebGPU);
+addToLibrary(LibraryHTML5WebGPU);

src/library_icasefs.js

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: MIT
  */
 
-mergeInto(LibraryManager.library, {
+addToLibrary({
   $ICASEFS__deps: ['wasmfs_create_icase_backend'],
   $ICASEFS: {
     createBackend(opts) {

src/library_idbfs.js

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: MIT
  */
 
-mergeInto(LibraryManager.library, {
+addToLibrary({
   $IDBFS__deps: ['$FS', '$MEMFS', '$PATH'],
   $IDBFS__postset: () => {
     addAtExit('IDBFS.quit();');

src/library_idbstore.js

@@ -199,4 +199,4 @@ var LibraryIDBStore = {
 };
 
 autoAddDeps(LibraryIDBStore, '$IDBStore');
-mergeInto(LibraryManager.library, LibraryIDBStore);
+addToLibrary(LibraryIDBStore);

src/library_int53.js

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: MIT
  */
 
-mergeInto(LibraryManager.library, {
+addToLibrary({
 #if ASSERTIONS
   $writeI53ToI64__deps: ['$readI53FromI64', '$readI53FromU64'
 #if MINIMAL_RUNTIME

src/library_jsfilefs.js

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: MIT
  */
 
-mergeInto(LibraryManager.library, {
+addToLibrary({
   $JSFILEFS__deps: ['wasmfs_create_js_file_backend'],
   $JSFILEFS: {
     createBackend(opts) {

src/library_legacy.js

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: MIT
  */
 
-mergeInto(LibraryManager.library, {
+addToLibrary({
   $ALLOC_NORMAL: 0,  // Tries to use _malloc()
   $ALLOC_STACK: 1,  // Lives for the duration of the current function call
 

src/library_little_endian_heap.js

@@ -36,4 +36,4 @@ var LibraryLittleEndianHeap = {
     HEAP_DATA_VIEW.getFloat64(byteOffset, true),
 }
 
-mergeInto(LibraryManager.library, LibraryLittleEndianHeap);
+addToLibrary(LibraryLittleEndianHeap);

src/library_lz4.js

@@ -5,7 +5,7 @@
  */
 
 #if LZ4
-mergeInto(LibraryManager.library, {
+addToLibrary({
   $LZ4__deps: ['$FS', '$preloadPlugins'],
   $LZ4: {
     DIR_MODE: {{{ cDefs.S_IFDIR }}} | 511 /* 0777 */,

src/library_makeDynCall.js

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: MIT
  */
 
-mergeInto(LibraryManager.library, {
+addToLibrary({
   $createDyncallWrapper__deps: ['$generateFuncType', '$uleb128Encode', 'setTempRet0'],
   $createDyncallWrapper: (sig) => {
     var sections = [];