Document debugging sections

[RReverser]

Several toolchains have supported sourceMappingURL custom section for years to encode source map URLs. Also nowadays Emscripten uses external_debug_info custom section to encode URL of the external DWARF info.

The Wasm debugging story is still in flux, but perhaps we should start documenting at least the custom sections and conventions already used in the wild, so that other tools can understand and parse those. cc @kripken @dschuff

[kripken]

Good idea. I'm actually not sure how much of this is temporary and how much is intended to be long term. (Or should we document things regardless, and update later?)

cc @pfaffe

[RReverser]

I think at the very least we could start a document with sourceMappingURL which has been around for years, and then, yeah figure out which ones of the newer additions are meant to stay around.

In general, if something is around for a while, I think it's better to document it regardless, since there is already a set of tools that rely on a shared representation that is just undocumented otherwise. If it becomes obsolete, we can always mark it as such later down the road.

[kripken]

I opened #149 now with info about DWARF and external_debug_info.

I did not add docs for sourceMappingURL since I think we want to remove that very soon. (Also, I am not entirely sure what it does - so I might not be the best person to document it anyhow, if we do want to.)

[RReverser]

I think we want to remove that very soon

Well it's supported in several browsers and toolchains (e.g. it's currently the only option for AssemblyScript - I think adding DWARF there will require quite a bit more effort and time), so I think it's still useful to document.

Also, I am not entirely sure what it does - so I might not be the best person to document it anyhow, if we do want to.

Sure, happy to add myself.

[RReverser]

@kripken As a next step, we'd probably need to document .debug_* custom sections as well. I don't think we need to go into DWARF details or even list all the names, just a section to cover them all together as a wildcard.

[kripken]

@RReverser Wouldn't that duplicate section 1.1 in @yurydelendik 's document? We link to there already.

[RReverser]

Hmm that's true, although same could be said about external_debug_info. I think just mentioning section names here and linking to that doc for details would be sufficient.

[kripken]

I'm not opposed, if you see value in it.

[RReverser]

Ouch, I accidentally committed from the Github UI instead of creating a PR: https://github.com/WebAssembly/tool-conventions/commit/faf81318d8b233746eeb3c61e087dfeb9e40d413#diff-7ab4dad0c749e83db84252b8efa31ce713135e4329e4f4772b93f21ca7b2c081

[kripken]

@RReverser post-commit lgtm