Reorganize the debugging documentation #25018
Conversation
|
@kripken I'm a bit confused about the doc building failure (e.g. https://app.circleci.com/jobs/github/emscripten-core/emscripten/1000395). Do I need to update emcc.txt manually, or is that expected to be done by the CI? |
|
Oh, actually I think the answer must be "yes" (do it locally), but unfortunately it seems my local configuration must be slightly different than the one on CI because I'm getting different kinds of quote characters :/ |
|
Weird about those quotes... maybe a different sphinx version? |
|
Yeah... I don't think it is? I initially tried with whatever version was on my system and it complained. I installed everything into a pip env, and it worked then. So I'm not sure what's going on. |
| .. _debugging-emscripten-specific-issues: | ||
| When you want the fastest builds, you generally want to avoid generating large debug information | ||
| during compile, because it takes time to link into the final binary. It is still worthwhile to use | ||
| the ``--profiling`` (TODO gnames/g2?) |
There was a problem hiding this comment.
Example below doesn't use profiling?
There was a problem hiding this comment.
Yeah, this doc isn't yet consistent about recommending g2 vs profiling, hence the TODO and the question I raised in the other thread.
| only, while g1 is whitespace only. Is it really necessary to have both of these (i.e is | ||
| there any use for wasm names without JS whitespace?) | ||
| Can we just deprecate the profiling flags and recommend -g2 for profiling | ||
| (and maybe have --profiling be a legacy alias for -g2 --minify=0?) |
There was a problem hiding this comment.
I do think it's nice to have --profiling which is easy to remember for when you want profiling. But no opinions about the other questions here.
|
|
||
| To run the *AutoDebugger*, compile with the environment variable ``EMCC_AUTODEBUG=1`` set. For example: | ||
| - In asm.js, unaligned loads and stores can fail silently (i.e. access the wrong address). |
There was a problem hiding this comment.
Can remove the asm.js bit. Maybe add it at the end as a note about wasm2js
There was a problem hiding this comment.
With the asm.js bit gone, this just reduces to "unaligned loads can be slow" which... is kind of true already anyway? It's really only different from native for really old/small cores that don't support unaligned loads in hardware, but trap to the OS to implement. Which, doesn't seem very relevant for JS+Wasm engines that Emscripten targets. Maybe we should just remove this section entirely?
There was a problem hiding this comment.
I think it may be worth noting the general wasm property here, relevant only for older hardware. But I'm fine with removing it too.
|
|
||
|
|
||
| Emscripten has several other compiler settings that can be useful for catching errors at runtime. | ||
| These are set using the :ref:`emcc -s<emcc-s-option-value>` option, and will override any optimization flags (TODO is this true?). For example: |
There was a problem hiding this comment.
@kripken do you know if this is true? I think maybe not, other than ASSERTIONS disabling metadce?
| You can also set ``SAFE_HEAP_LOG`` to log ``SAFE_HEAP`` operations. | ||
| ``SAFE_HEAP=1`` adds additional memory access checks with a Binaryen pass, and will give clear | ||
| errors for problems like dereferencing 0 and memory alignment issues. | ||
| You can also set ``SAFE_HEAP_LOG`` to log ``SAFE_HEAP`` operations. (TODO: any advantages over ASan?) |
There was a problem hiding this comment.
@kripken IIRC ASan now supports sanitizing JS memory writes too, right? Is there any other reason a user might want to use SAFE_HEAP?
Most of the existing text is the same, but reorganized around use cases, with examples.
Incorporates some content from #20462