diff --git a/docs/emcc.txt b/docs/emcc.txt index 04a8401a5db55..49d4376c19572 100644 --- a/docs/emcc.txt +++ b/docs/emcc.txt @@ -161,6 +161,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" When linking, generate a source map using LLVM debug information (which must be present in object files, i.e., they should have been diff --git a/site/source/docs/porting/Debugging.rst b/site/source/docs/porting/Debugging.rst index 06f61398b94f1..af7c2f4ad21e8 100644 --- a/site/source/docs/porting/Debugging.rst +++ b/site/source/docs/porting/Debugging.rst @@ -19,18 +19,55 @@ This article describes the main tools and settings provided by Emscripten for de .. _debugging-debug-information-g: -Debug information -================= - -:ref:`Emcc ` strips out most of the debug information from :ref:`optimized builds ` by default. Optimisation levels :ref:`-O1 ` and above remove LLVM debug information, and also disable runtime :ref:`ASSERTIONS ` checks. From optimization level :ref:`-O2 ` the code is minified by the :term:`Closure Compiler` and becomes virtually unreadable. - -The *emcc* :ref:`-g flag ` 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 `, :ref:`-g1 `, :ref:`-g2 `, and :ref:`-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 ` for more details. - -The :ref:`-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. - -.. note:: Some optimizations may be disabled when used in conjunction with the debug flags. For example, if you compile with ``-O3 -g`` some of the normal ``-O3`` optimizations will be disabled in order to provide the requested debugging information, such as name minification. +Debugging in the browser +======================== + +:ref:`Emcc ` 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 `. See +`here ` 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 ` strips out most of the debug information from +:ref:`optimized builds ` by default. DWARF can be produced with +the *emcc* :ref:`-g flag `, and source maps can be emitted with the +:ref:`-gsource-map ` option. Be aware that optimisation levels +:ref:`-O1 ` and above increasingly remove LLVM debug information, and +also disable runtime :ref:`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 ` 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 ` 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 + ``llvm-dwp`` tool then, but that could happen in parallel to the linking of + the compiled output! A compatible version should be part of your emscripten + distribution, for example in ``$EMSDK/upstream/bin/llvm-dwp``. When running it + after linking, it's as simple as ``llvm-dwp -e foo.wasm -o foo.wasm.dwp``, or + ``llvm-dwp -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 `, :ref:`-g1 `, :ref:`-g2 ` (default with +``-gsource-map``), and :ref:`-g3 ` (default with ``-g``). Each level +builds on the last to provide progressively more debug information in the +compiled output. + +.. note:: Some optimizations may be disabled when used in conjunction with the + debug flags. For example, if you compile with ``-O3 -g`` some of the normal + ``-O3`` optimizations will be disabled in order to provide the requested + debugging information, such as name minification. .. _debugging-EMCC_DEBUG: diff --git a/site/source/docs/tools_reference/emcc.rst b/site/source/docs/tools_reference/emcc.rst index eedeadae6e0c9..be966652a000b 100644 --- a/site/source/docs/tools_reference/emcc.rst +++ b/site/source/docs/tools_reference/emcc.rst @@ -136,6 +136,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-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 @@ -147,6 +149,12 @@ Options that are modified or new in *emcc* are listed below: ``-s SEPARATE_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``