Reorganize the debugging documentation #25018

dschuff · 2025-08-22T00:05:57Z

Most of the existing text is the same, but reorganized around use cases, with examples.

Incorporates some content from #20462

dschuff · 2025-08-22T18:21:45Z

@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?

dschuff · 2025-08-22T18:24:45Z

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 :/

kripken · 2025-08-22T20:49:12Z

Weird about those quotes... maybe a different sphinx version?

dschuff · 2025-08-22T21:08:51Z

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.

site/source/docs/porting/Debugging.rst

kripken · 2025-09-10T00:06:12Z

tools/link.py

@@ -1878,7 +1878,7 @@ def get_full_import_name(name):
  settings.PRE_JS_FILES = options.pre_js
  settings.POST_JS_FILES = options.post_js

-  settings.MINIFY_WHITESPACE = settings.OPT_LEVEL >= 2 and settings.DEBUG_LEVEL == 0 and not options.no_minify
+  settings.MINIFY_WHITESPACE = settings.OPT_LEVEL >= 2 and settings.DEBUG_LEVEL == 0 and not options.no_minify #shouldn't no_minify be equivalent to g1?


Is this intentional?

Oh, no it was more of a note-to-self when I found something surprising, I think I just intended to ask you about it. so... is minify=0 supposed to be different to what g1 does? I don't completely understand the implementation and AFAIK we don't have any tests that can tell the difference.

I think they should be the same. The docs say

"--minify 0" [same as -g1 if passed at compile time, otherwise applies at link] Identical to "-g1".

and I can't think of a difference.

OK. I think the thing I saw was there were places that DEBUG_LEVEL is referred to where no_minify wasn't, and thought maybe this can be simplified (e.g. removing settings.no_minify and just making it equivalent to g1), but that's not for this PR in any case.

site/source/docs/porting/Debugging.rst

Co-authored-by: Alon Zakai <[email protected]>

This reverts commit f7ba743.

site/source/docs/porting/Debugging.rst

aheejin · 2025-09-11T09:54:09Z

site/source/docs/tools_reference/emcc.rst


    -
      .. _emcc-g3:

-      ``-g3``: When compiling to object files, keep debug info, including JS whitespace, function names, and LLVM debug info (DWARF) if any (this is the same as :ref:`-g <emcc-g>`).
+      ``-g3``: Also keep LLVM debug info (DWARF) if there is any in the object files (this is the same as :ref:`-g <emcc-g>`).

 .. _emcc-profiling:

 ``--profiling``


I know it is preexisting, but it's not clear to me what this does.. (I also haven't used this myself)
It says it's similar to -g2, then what's the difference?
Also the name is similar to that of --profiling-funcs; are they related in any way? Is one is a subset of the other?

I believe --profiling-funcs is supposed to be a subset of --profiling yes.

I'd love to get rid of these two flags and replace --profiling-funcs with something like -gname-section which is basically what it does.

--profiling does all the optimizations that would affect speed (to make sure the profile execution is the same as the production one) but keeps function names in wasm and JS (i.e. no minification), so that the profile is actually useful. (--profiling-funcs enables the name section in the wasm binary but still minifies JS).

I'm not sure about the history of these profiling flags vs -g2. Currently AFAIK they are the same. In an earlier version of this PR I posed a similar question (see above)

I rewrote the description here to make it more accurate and clear.

@sbc100 regarding -gnames, see the discussion on #20462. We have -g2 (which is names+JS whitespace). If you want names only, I guess you can do -g2 --minify=0. I think it's an open question whether we want to make it easier still to get names only, and what the use case is. I can see how you might want names-only (or names + source maps but not minification) if you want full production build with function names and locations. But maybe we'll also have #25044 for that.

Yeah it looks we have too many flags that are subtly different from each other... It'd be nice if we can get rid of some of them at least..

test/test_other.py

aheejin · 2025-09-11T09:58:03Z

test/test_other.py

@@ -9261,6 +9262,9 @@ def test_binaryen_debug(self):
        (['-O2', '-g'],  False, True, False),
        (['-O2', '--closure=1'], True, False, True),
        (['-O2', '--closure=1', '-g1'], True, True,  True),
+        (['-O2', '--minify=0'], False, True, False),
+        (['-O2', '--profiling-funcs'], True, False, False),


What's "cleaned" JS and which tool does it? Reading the test suggests it lacks comments. Is that the only difference from the "normal" JS?

And do we have info on the JS optimizations? This test suggests we have at least three kinds of JS optimizations (minification, cleaning, and closure)

Yeah, what I know is basically what these test actually check for, i.e. comments (and presumably also optimizations?) vs whitespace. I assume that clean-but-with-whitespace is what you want for profiling, since you want the speed optimizations that the final product would have, but want useful function names in your profile and stack traces and readability. But I'm not sure which tool does what and where. Probably @kripken knows.

site/source/docs/porting/Debugging.rst

dschuff · 2025-09-11T21:03:47Z

@kripken @sbc100 the doc building step is failing here (https://app.circleci.com/pipelines/github/emscripten-core/emscripten/45613/workflows/3565df1d-01e6-4365-a540-0be846a3a4c3/jobs/1022087) because apparently when I run it locally I'm getting fancy quote characters and different dashes in some cases (when generating emcc.txt). Any idea what might be going on here?

sbc100 · 2025-09-11T21:08:44Z

@kripken @sbc100 the doc building step is failing here (https://app.circleci.com/pipelines/github/emscripten-core/emscripten/45613/workflows/3565df1d-01e6-4365-a540-0be846a3a4c3/jobs/1022087) because apparently when I run it locally I'm getting fancy quote characters and different dashes in some cases (when generating emcc.txt). Any idea what might be going on here?

Do you have the exact version of sphinx installed from requirements-dev.txt?

dschuff · 2025-09-11T21:15:39Z

Do you have the exact version of sphinx installed from requirements-dev.txt?

Yes. but nevermind I blew away the build directory and reran the build in my pip env and it worked again.

dschuff · 2025-09-11T21:17:28Z

But since I've now @-ed you all... let's do the thing where we bikeshed how many columns I should wrap all this text to :)

kripken · 2025-09-11T21:27:05Z

I am always in favor of more columns but I always lose the debate 😄 I don't feel strongly.

dschuff · 2025-09-11T21:30:10Z

Yeah I had been thinking that we settled on something larger than 80 but more than "ALL the columns" but maybe I'm misremembering.

dschuff · 2025-09-11T22:40:41Z

Since basically the whole file is touched in this PR anyway, I just re-wrapped the whole thing.

aheejin · 2025-09-11T23:18:08Z

LGTM but it'd be nice to have some documentation on JS optimizations too (as a followup, when you have time): #25018 (comment)

dschuff added 3 commits August 19, 2025 22:22

first draft and debugging update

03af9ef

quality pass

3c7cad0

add examples, remove overview, add tests

4f27d9f

dschuff mentioned this pull request Aug 22, 2025

Support optimized builds with source maps #20462

Closed

dschuff added 4 commits August 22, 2025 16:55

more tweaks

804f405

update emcc.txt

bd13b53

add note

23ab645

Merge branch 'main' into debug_doc

75a4176

kripken reviewed Aug 22, 2025

View reviewed changes

site/source/docs/porting/Debugging.rst Outdated Show resolved Hide resolved

site/source/docs/porting/Debugging.rst Outdated Show resolved Hide resolved

site/source/docs/porting/Debugging.rst Outdated Show resolved Hide resolved

dschuff added 3 commits August 29, 2025 22:33

tweak, fix some todos

a2c6ec4

resolve some TODOS

69ed6de

update emcc.rst

9a5ce4a

dschuff commented Sep 6, 2025

View reviewed changes

site/source/docs/porting/Debugging.rst Outdated Show resolved Hide resolved

dschuff commented Sep 6, 2025

View reviewed changes

site/source/docs/porting/Debugging.rst Outdated Show resolved Hide resolved

dschuff added 2 commits September 8, 2025 21:55

tweaks, remove TODOs

0da8473

Merge branch 'main' into debug_doc

1dbd9e5

dschuff marked this pull request as ready for review September 8, 2025 21:58

Merge branch 'main' into debug_doc

70e67e8

kripken reviewed Sep 10, 2025

View reviewed changes

dschuff and others added 2 commits September 10, 2025 14:17

Apply suggestions from code review

25c0156

Co-authored-by: Alon Zakai <[email protected]>

remove TODOs move example block

37546a7

kripken approved these changes Sep 10, 2025

View reviewed changes

dschuff added 2 commits September 10, 2025 21:42

fix more tests using source maps + names

f7ba743

Revert "fix more tests using source maps + names"

00921ab

This reverts commit f7ba743.

aheejin reviewed Sep 11, 2025

View reviewed changes

dschuff added 4 commits September 11, 2025 19:37

apply review suggestions

082502c

review comments

1813d54

remove test changes

8b82b21

Merge branch 'main' into debug_doc

5277385

fix text build

626168f

wrap Debugging.rst at 80 col

695db77

aheejin approved these changes Sep 11, 2025

View reviewed changes

dschuff merged commit 0743e64 into emscripten-core:main Sep 12, 2025
31 checks passed

Reorganize the debugging documentation #25018

Reorganize the debugging documentation #25018

Conversation

dschuff commented Aug 22, 2025

Uh oh!

dschuff commented Aug 22, 2025

Uh oh!

dschuff commented Aug 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

kripken commented Aug 22, 2025

Uh oh!

dschuff commented Aug 22, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dschuff Sep 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dschuff Sep 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

dschuff commented Sep 11, 2025

Uh oh!

sbc100 commented Sep 11, 2025

Uh oh!

dschuff commented Sep 11, 2025

Uh oh!

dschuff commented Sep 11, 2025

Uh oh!

kripken commented Sep 11, 2025

Uh oh!

dschuff commented Sep 11, 2025

Uh oh!

dschuff commented Sep 11, 2025

Uh oh!

aheejin commented Sep 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

dschuff commented Aug 22, 2025 •

edited

Loading

dschuff Sep 11, 2025 •

edited

Loading

dschuff Sep 11, 2025 •

edited

Loading

aheejin commented Sep 11, 2025 •

edited

Loading