Skip to content

Commit

Permalink
[Docs] Improve split/separate DWARF and other debugging docs (#20463)
Browse files Browse the repository at this point in the history
  • Loading branch information
connorjclark authored Oct 17, 2023
1 parent 99a5f81 commit 6870616
Show file tree
Hide file tree
Showing 3 changed files with 56 additions and 10 deletions.
5 changes: 5 additions & 0 deletions docs/emcc.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
53 changes: 43 additions & 10 deletions site/source/docs/porting/Debugging.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
8 changes: 8 additions & 0 deletions site/source/docs/tools_reference/emcc.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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``
Expand Down

0 comments on commit 6870616

Please sign in to comment.