UMD module wrapper is not robustly generated and is likely wrong

[cannam]

Our Makefile.inc currently builds two outputs for each Emscripten module.

One, ModuleName.js, is the output produced by Emscripten with its MODULARIZE option switched on.

The other, ModuleName.umd.js, is the result of taking ModuleName.js, stripping out the module wrapper, and wrapping with a UMD module wrapper instead.

Unfortunately the scrappy shell script to strip out the Emscripten module wrapper is very fragile, and appears to have been broken (on my system) by a recent Emscripten update which added another couple of lines of boilerplate to the end of its module wrapper.

Why did we do this in the first place? Because the Emscripten module output "seemed like" a sensible choice for use when including the module into a web page, while the UMD output "seemed like" a sensible choice for use in Node. But UMD is supposed to work in a web page as well, so we could presumably instead run Emscripten without the MODULARIZE option and just add a UMD wrapper to that output, producing a single module that we can use everywhere.

There is another problem with that, which is that our UMD wrapper appears to be incomplete -- it doesn't contain anything to check for a browser context and add the module to the window object as might be expected.

Alternatively, maybe Emscripten has some other option that we aren't using, that would make it produce something suitable for both browser and Node itself.

[cannam]

Well, I say "UMD is supposed to..." but there appear to be 9 different UMD module wrappers at https://github.com/umdjs/umd/tree/master/templates which I'm assuming is the canonical location. Hm. The one we have now looks like nodeAdapter.js.

[LucasThompson]

A bit more info and history:

MODULARIZE=1 wraps the output from Emscripten in a function which returns the module and then assigns that to a variable, named after the value set with the EXPORT_NAME flag.

When loading this into a browser, you interact with the Emscripten module using that global variable. Loading this script into node using require doesn't work, so we came up with a fix which dynamically figures out if the script is running in node and then assigns the function to module.exports, hence the following line in Makefile.inc.

It seems node module loading has now been fixed, but I am not sure if it is in a release of Emscripten yet. The additional lines you are seeing a likely due to a change adding a Promise-like API to the output of MODULARIZE.

The UMD pattern used currently in the Makefile comes from the output of the TypeScript compiler when using the UMD option, which seems to omit the clause regarding falling back to setting a global variable (as seen here). When editing this output I made a decision to export a single function named "createLibrary".

So, what are we trying to achieve?

We want to produce a module which can be loaded in both node and the browser, but also dynamically into an application (node or browser) - so using a pattern like AMD makes sense (and is used in ugly-duckling for loading remote plugins). Dynamic imports may also be a solution, but I feel there is no harm with sticking with AMD for now.

What is the fix?

I think we only need to output one .js file from the Makefile, a returnExports style UMD module as linked above. I think removing "createLibrary" and just exporting an anonymous function is fine.