139 lines · plain
1DWARF Extensions2================3 4LLDB supports some DWARF extensions produced by Clang.5 6Clang ``-gmodules`` debug info7------------------------------8 9On Darwin platforms, including Apple macOS and iOS, Clang can emit10DWARF debug info for types found in `Clang11modules <https://clang.llvm.org/docs/Modules.html>`_ more efficiently.12 13From an on-disk storage perspective, Clang modules are precompiled14header files that contain serialized Clang ASTs of all the15declarations found in a Clang module. In traditional DWARF debug info,16two object files that were built from sources that imported the same17header file will both contain DWARF debug type info for types in that18header file. This can lead to a lot of redundant `debug19info <https://llvm.org/devmtg/2015-10/#talk19>`_.20 21When Clang compiles a Clang module or precompiled header with the22``-gmodules`` option, the precompiled header (``.pch``) or module23(``.pcm``) files become object file containers (on Darwin: Mach-O)24that hold a ``__clang_ast`` section with the serialized Clang AST and25various DWARF sections containing debug info for the type declarations26found in the header or module.27 28This allows Clang to omit these type definitions from the object29(``.o``) files and replace them with forward declarations to save30space. Type declarations in a Clang module are nested inside one31``DW_TAG_module``, or -- in the case of submodules -- multiple levels32of ``DW_TAG_module``. If a DWARF DIE needs to reference a type DIE33from another module, Clang emits a forward declaration of the34referenced DIE into a ``DW_TAG_module`` inside the same compile unit.35 36When a consumer sees a forward declaration that is nested inside a37``DW_TAG_module``, it knows that it can find the full type declaration38in an external ``.pcm`` or ``.pch`` file. To facilitate locating these39external dependencies, Clang emits skeleton CUs into each object file40that references external modules. Clang uses the same mechanism that41is used to locate external ``.dwo`` files on ELF-based platforms. The42``DW_AT_GNU_dwo_name`` contains the absolute path to the ``.pcm``43file, and the ``DW_AT_GNU_dwo_id`` is a hash of the contents that is44repeated in the ``DW_TAG_compile_unit`` of the ``.pcm`` file.45 46For example:47 48M.h49 50::51 52 struct A {53 int x;54 };55 56 57M.pcm58 59::60 61 DW_TAG_compile_unit62 DW_AT_GNU_dwo_id (0xabcdef)63 DW_TAG_module64 DW_AT_name "M"65 DW_TAG_structure66 DW_AT_name "A"67 DW_TAG_member68 DW_AT_name "x"69 70A.c71 72::73 74 A a;75 76A.o77 78::79 80 DW_TAG_compile_unit81 DW_TAG_module82 DW_AT_name "M"83 DW_TAG_structure84 DW_AT_name "A"85 DW_AT_declaration (true)86 DW_TAG_variable87 DW_AT_name "a"88 DW_AT_type (local ref to fwd decl "A")89 90 DW_TAG_compile_unit91 DW_AT_GNU_dwo_id (0xabcdef)92 DW_AT_GNU_dwo_name ("M.pcm")93 94The debug info inside a ``.pcm`` file may recursively reference95further external types that are defined in other ``.pcm`` files. Clang96generates external references (and debug info inside the modules) for97the following types:98 99C:100 101- ``struct``102- ``union``103- ``enum``104- ``typedef``105 106Objective-C:107 108- all the C types listed above109- ``@interface``110 111C++:112 113- all the C types listed above114- ``namespace``115- any explicit ``extern template`` specializations116 117LLDB supports this DWARF extension only when debugging from ``.o``118files. The ``dsymutil`` debug info linker also understands this format119and will resolve all module type references to point straight to the120underlying defining declaration. Because of this a ``.dSYM`` bundle121will never contain any ``-gmodules``-style references.122 123Apple SDK information124---------------------125 126Clang and the Swift compiler emit information about the Xcode SDK that127was used to build a translation unit into the ``DW_TAG_compile_unit``.128The ``DW_AT_LLVM_sysroot`` attribute points to the SDK root129(equivalent to Clang's ``-isysroot`` option). The ``DW_AT_APPLE_sdk``130attribute contains the name of the SDK, for example ``MacOSX.sdk``.131 132Objective-C runtime133-------------------134 135Clang emits the Objective-C runtime version into the136``DW_TAG_compile_unit`` using the137``DW_AT_APPLE_major_runtime_vers`` attribute. The value 2 stands138for Objective-C 2.0.139