Document link/compile/both options

[hugoam]

Generally, every time I'm looking up one of the required Emscripten options for either thing I'm trying to do, in either part of the documentation or wiki, I have generally no idea whether it's required at compile step, at the link step, or both.

Right now, specifically, I'm looking at -s SIDE_MODULE=1 and -s MAIN_MODULE=1, but this is basically the case for every single Emscripten option. It's virtually never specified at which step it's required, whereas ideally it would be always specified.

So the user ends up needing to fiddle with build scripts, do a full rebuild a bunch of time in order to determine that. If I want to correctly specify my build scripts, I basically am required to do three full rebuilds to determine at which step it was actually needed (and even then I still might not be entirely sure). This is really not ideal.

This is not the first time I'm deeply annoyed by this issue, so I thought I'd at least open an issue.

[VirtualTim]

These are documented in settings.js. But perhaps they could also be documented somewhere else?

[hugoam]

Well yes, actually, they definitely could 😄
I had no knowledge of this in-source documentation even existing (and to be honest except for a find in files in my emsdk folder I'm not sure how I could have found this myself).
This should at least translate to a proper documentation page on the official Emscripten docs.
Thanks for pointing me to this at the very least !

Then well, they are indeed documented, but they don't specify what I think they should specify: at which step they have an effect (link/compile/both).
A comment of @kripken in #9710 seems to mention that MAIN/SIDE_MODULE is needed at compilation step too, but I don't know if that's still the case. The only way to be sure would be to at least try to have the doc of the option mention this and try to keep it up-to-date.

But again, this holds for all the options documented there, not only this specific one. They should all specify at which step they are required. (And have an official existence in the emscripten docs, but I repeat myself now 😛 )

[VirtualTim]

Then well, they are indeed documented, but they don't specify what I think they should specify: at which step they have an effect (link/compile/both).

Most of them do. Look for [link] and [compile+link].
Also:

emscripten/src/settings.js

Lines 44 to 47 in 7952394

	// If not otherwise specified, a flag is [link]. Note that no flag is only
	// relevant during compile time, as during link we may do codegen for system
	// libraries and other support code, so all flags are either link or
	// compile+link.

But I do agree, at a minimum the documentation describing things like MAIN/SIDE_MODULE should describe whether it's a link of compile option, or point people to settings.js.

[kripken]

I believe for main/side module, they are link time, which is the default for flags - so I think the docs in settings.js are accurate (it says near the top that the default is link, if not specified otherwise).

[sbc100]

At some point I hope to start parsing the metadata (e.g. [compile+link]) and warning if you/when the options are used at the wrong time.

We perhaps should be extracting the settings.js comments in the docs page. Today we do link directly to the js file here: https://emscripten.org/docs/tools_reference/emcc.html

[stale]

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 30 days. Feel free to re-open at any time if this issue is still relevant.

[sbc100]

Lets keep this open until these are better documents and we generate runtime warnings when they are mis-used.

[stale]

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 30 days. Feel free to re-open at any time if this issue is still relevant.