diff --git a/docs/emcc.txt b/docs/emcc.txt index a9eabf21993f6..e43316ba124fe 100644 --- a/docs/emcc.txt +++ b/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 diff --git a/site/source/docs/porting/Debugging.rst b/site/source/docs/porting/Debugging.rst index a4b872aec8829..d766f32022fad 100644 --- a/site/source/docs/porting/Debugging.rst +++ b/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 ` strips out most of the debug information from :ref:`optimized builds ` by default. The higher the optimization level, the more degraded the quality of DWARF debug information is, so we recommend using :ref:`-O0 ` or :ref:`-O1 ` for debugging purposes. :ref:`-O1 ` and above also disable runtime :ref:`ASSERTIONS ` checks. From optimization level :ref:`-O2 ` the JavaScript 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. +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 + ``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 `, :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:: 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 `_ for more details. diff --git a/site/source/docs/tools_reference/emcc.rst b/site/source/docs/tools_reference/emcc.rst index e784a277441da..472818e262101 100644 --- a/site/source/docs/tools_reference/emcc.rst +++ b/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-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``