Emscripten: Proposal: one EXPORTS setting to rule them all

[kripken]

Background: Right now to keep alive & export a compiled function one would use EXPORTED_FUNCTIONS, while to ensure a JS library function exists one would use DEFAULT_LIBRARY_FUNCS_TO_INCLUDE, and there is EXPORTED_RUNTIME_METHODS for exporting parts of the JS runtime. This is needlessly complex, and confusing since a C API may be implemented in either compiled code or a JS library, and currently you need to know which in order to properly include and export it.

Proposal:

• A new EXPORTS setting, which receives a list of things to ensure exist and are exported in the final output. These can be in compiled code, the JS library, or the JS runtime - the user doesn't need to know.
• Deprecate all the other relevant options (but still support them for backwards compatibility for a long time at least), namely EXPORTED_FUNCTIONS, DEFAULT_LIBRARY_FUNCS_TO_INCLUDE, EXPORTED_RUNTIME_METHODS.
• No _ prefixing, like EXPORTED_RUNTIME_METHODS etc., and unlike EXPORTED_FUNCTIONS. This moves us further along the path to get us rid of the old prefixing annoyance.

For example, -s EXPORTS=['main', 'emscripten_main_loop', 'AsciiToString'] would export a compiled function, a JS library function, and a runtime function, respectively (and note the lack of _ prefixes).

Thoughts?

cc @juj @sbc100 @jgravelle-google @sbc100 @dschuff

[curiousdannii]

Would the exported functions also lack the _? And if you use EMSCRIPTEN_KEEPALIVE could that also export without the _?

(I think this would be cleaner, but it does make backwards compatibility harder or bloatier.)

[jgravelle-google]

sgtm, from a UX perspective at least

[sbc100]

Sounds good, assuming the distinction isn't needs by any of our users.

@curiousdannii, I share your concern regarding maintaining backwards compat. For this kind of thing I'd like to see an eventual path to completely removal. In stages such as:

1) Disable the features in STRICT mode, and recommend that devs used STRICT whenever possible to stay up-to-date.
2) After N months, or N emscripten revisions show a warning when using the deprecated feature.
3) After another N, turn the warning into a hard error and remove all the supporting code

[dschuff]

IIUC it does sort of repurpose the meaning of what an "export" is. We've been thinking of it in the sense of being exported from the compiled module, whereas the others would be actually imported into wasm but "exported" from the Module object. Mostly users don't care about that distinction so this is probably a good idea (although, what about user-written JS library code?). Maybe at least for our own sanity, in code/comments (and maybe documentation) we should have more precise nomenclature, e.g. "Module exports" or something to mean exports from the emscripten package (EXPORTS as proposed here), "wasm exports/imports" to mean exports from the wasm module, and... something else?

[stale[bot]]

This issue has been automatically marked as stale because there has been no activity in the past year. It will be closed automatically if no further activity occurs in the next 7 days. Feel free to re-open at any time if this issue is still relevant.

[curiousdannii]

This still sounds like a good improvement if the details can be worked out.

[kripken]

@curiousdannii Agreed, yeah. I think this has to wait on removing fastcomp first, after that this will be much easier to do.