[Docs] Improve split/separate DWARF and other debugging docs (#20463)

Author: connorjclark

docs/emcc.txt

@@ -173,6 +173,11 @@ Options that are modified or new in *emcc* are listed below:
    customize that location (this is useful if you want to host it on a
    different server, for example).
 
+"-gsplit-dwarf"
+   Enable debug fission, which creates split DWARF object files
+   alongside the wasm object files. This option must be used together
+   with "-c".
+
 "-gsource-map"
    [link] Generate a source map using LLVM debug information (which
    must be present in object files, i.e., they should have been

site/source/docs/porting/Debugging.rst

@@ -19,16 +19,49 @@ This article describes the main tools and settings provided by Emscripten for de
 
 .. _debugging-debug-information-g:
 
-Debug information
-=================
-
-:ref:`Emcc <emccdoc>` strips out most of the debug information from :ref:`optimized builds <Optimizing-Code>` by default. The higher the optimization level, the more degraded the quality of DWARF debug information is, so we recommend using :ref:`-O0 <emcc-O0>` or :ref:`-O1 <emcc-O1>` for debugging purposes. :ref:`-O1 <emcc-O1>` and above also disable runtime :ref:`ASSERTIONS <debugging-ASSERTIONS>` checks. From optimization level :ref:`-O2 <emcc-O2>` the JavaScript code is minified by the :term:`Closure Compiler` and becomes virtually unreadable.
-
-The *emcc* :ref:`-g flag <emcc-g>` can be used to preserve debug information in the compiled output. By default, this option includes Clang / LLVM debug information in a DWARF format in the generated WebAssembly code and preserves white-space, function names and variable names in the generated JavaScript code.
-
-The flag can also be specified with an integer level: :ref:`-g0 <emcc-g0>`, :ref:`-g1 <emcc-g1>`, :ref:`-g2 <emcc-g2>`, and :ref:`-g3 <emcc-g3>` (default level when setting ``-g``). Each level builds on the last to provide progressively more debug information in the compiled output. See :ref:`Compiler debug information flags <emcc-gN>` for more details.
-
-The :ref:`-gsource-map <emcc-gsource-map>` option is similar to ``-g2`` but also generates source maps that allow you to view and debug the *C/C++ source code* in your browser's debugger. Source maps are not as powerful as DWARF which was mentioned earlier (they contain only source location info), but they are currently more widely supported.
+Debugging in the browser
+========================
+
+:ref:`Emcc <emccdoc>` can ouptut debug information in two formats, either as
+DWARF symbols or as source maps. Both allow you to view and debug the
+*C/C++ source code* in a browser's debugger. DWARF offers the most precise and
+detailed debugging experience and is supported as an experiment in Chrome 88
+with an `extension <https://goo.gle/wasm-debugging-extension>`. See
+`here <https://developer.chrome.com/blog/wasm-debugging-2020/>` for a detailed
+usage guide. Source maps are more widely supported in Firefox, Chrome, and
+Safari, but unlike DWARF they cannot be used to inspect variables, for example.
+
+:ref:`Emcc <emccdoc>` strips out most of the debug information from
+:ref:`optimized builds <Optimizing-Code>` by default. DWARF can be produced with
+the *emcc* :ref:`-g flag <emcc-g>`, and source maps can be emitted with the
+:ref:`-gsource-map <emcc-gsource-map>` option. Be aware that optimisation levels
+:ref:`-O1 <emcc-O1>` and above increasingly remove LLVM debug information, and
+also disable runtime :ref:`ASSERTIONS <debugging-ASSERTIONS>` checks. Passing a
+``-g`` flag also affects the generated JavaScript code and preserves
+white-space, function names, and variable names,
+
+.. tip:: Even for medium-sized projects, DWARF debug information can be of
+  substantial size and negatively impact the page performance, particularly
+  compiling and loading of the module. Debug information can also be emitted in
+  a file on the side instead with the
+  :ref:`-gseparate-dwarf <emcc-gseparate-dwarf>` option! The debug information
+  size also affects the linking time, because the debug information in all
+  object files needs to be linked as well. Passing the
+  :ref:`-gsplit-dwarf <emcc-gsplit-dwarf>` option can help here, which causes
+  clang to leave debug information scattered across object files. That debug
+  information needs to be linked into a DWARF package file (``.dwp``) using the
+  ``emdwp`` tool then, but that could happen in parallel to the linking of
+  the compiled output! When running it
+  after linking, it's as simple as ``emdwp -e foo.wasm -o foo.wasm.dwp``, or
+  ``emdwp -e foo.debug.wasm -o foo.debug.wasm.dwp`` when used together with
+  ``-gseparate-dwarf`` (the dwp file should have the same file name as the main
+  symbol file with an extra ``.dwp`` extension).
+
+The ``-g`` flag can also be specified with an integer levels:
+:ref:`-g0 <emcc-g0>`, :ref:`-g1 <emcc-g1>`, :ref:`-g2 <emcc-g2>` (default with
+``-gsource-map``), and :ref:`-g3 <emcc-g3>` (default with ``-g``). Each level
+builds on the last to provide progressively more debug information in the
+compiled output.
 
 .. note:: Because Binaryen optimization degrades the quality of DWARF info further, ``-O1 -g`` will skip running the Binaryen optimizer (``wasm-opt``) entirely unless required by other options. You can also throw in ``-sERROR_ON_WASM_CHANGES_AFTER_LINK`` option if you want to ensure the debug info is preserved. See `Skipping Binaryen <https://developer.chrome.com/blog/faster-wasm-debugging/#skipping-binaryen>`_ for more details.
 

site/source/docs/tools_reference/emcc.rst

@@ -149,6 +149,8 @@ Options that are modified or new in *emcc* are listed below:
     adds DWARF debug information to the object files.
   - When linking, this is equivalent to :ref:`-g3 <emcc-g3>`.
 
+.. _emcc-gseparate-dwarf:
+
 ``-gseparate-dwarf[=FILENAME]``
   [same as -g3 if passed at compile time, otherwise applies at link]
   Preserve debug information, but in a separate file on the side. This is the
@@ -160,6 +162,12 @@ Options that are modified or new in *emcc* are listed below:
   ``-sSEPARATE_DWARF_URL=URL`` to customize that location (this is useful if
   you want to host it on a different server, for example).
 
+.. _emcc-gsplit-dwarf:
+
+``-gsplit-dwarf``
+  Enable debug fission, which creates split DWARF object files alongside the
+  wasm object files. This option must be used together with ``-c``.
+
 .. _emcc-gsource-map:
 
 ``-gsource-map``