WebAssembly / tool-conventions

Conventions supporting interoperatibility between tools working with WebAssembly.
Artistic License 2.0
302 stars 67 forks source link

Document debugging sections #148

Closed RReverser closed 3 years ago

RReverser commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

@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 commented 3 years ago

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

RReverser commented 3 years ago

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 commented 3 years ago

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

RReverser commented 3 years ago

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

kripken commented 3 years ago

@RReverser post-commit lgtm