1DWARF Extensions supported by LLDB 2================================== 3 4LLDB supports some DWARF extensions produced by Clang. 5 6Clang ``-gmodules`` debug info 7------------------------------ 8 9On Darwin platforms, including Apple macOS and iOS, Clang can emit 10DWARF debug info for types found in `Clang 11modules <https://clang.llvm.org/docs/Modules.html>`_ more efficiently. 12 13From an on-disk storage perspective, Clang modules are precompiled 14header files that contain serialized Clang ASTs of all the 15declarations found in a Clang module. In traditional DWARF debug info, 16two object files that were built from sources that imported the same 17header file will both contain DWARF debug type info for types in that 18header file. This can lead to a lot of redundant `debug 19info <https://llvm.org/devmtg/2015-10/#talk19>`_. 20 21When Clang compiles a Clang module or precompiled header with the 22``-gmodules`` option, the precompiled header (``.pch``) or module 23(``.pcm``) files become object file containers (on Darwin: Mach-O) 24that hold a ``__clang_ast`` section with the serialized Clang AST and 25various DWARF sections containing debug info for the type declarations 26found in the header or module. 27 28This allows Clang to omit these type definitions from the object 29(``.o``) files and replace them with forward declarations to save 30space. Type declarations in a Clang module are nested inside one 31``DW_TAG_module``, or -- in the case of submodules -- multiple levels 32of ``DW_TAG_module``. If a DWARF DIE needs to reference a type DIE 33from another module, Clang emits a forward declaration of the 34referenced DIE into a ``DW_TAG_module`` inside the same compile unit. 35 36When a consumer sees a forward declaration that is nested inside a 37``DW_TAG_module``, it knows that it can find the full type declaration 38in an external ``.pcm`` or ``.pch`` file. To facilitate locating these 39external dependencies, Clang emits skeleton CUs into each object file 40that references external modules. Clang uses the same mechanism that 41is used to locate external ``.dwo`` files on ELF-based platforms. The 42``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 is 44repeated in the ``DW_TAG_compile_unit`` of the ``.pcm`` file. 45 46For example: 47 48M.h 49 50:: 51 52 struct A { 53 int x; 54 }; 55 56 57M.pcm 58 59:: 60 61 DW_TAG_compile_unit 62 DW_AT_GNU_dwo_id (0xabcdef) 63 DW_TAG_module 64 DW_AT_name "M" 65 DW_TAG_structure 66 DW_AT_name "A" 67 DW_TAG_member 68 DW_AT_name "x" 69 70A.c 71 72:: 73 74 A a; 75 76A.o 77 78:: 79 80 DW_TAG_compile_unit 81 DW_TAG_module 82 DW_AT_name "M" 83 DW_TAG_structure 84 DW_AT_name "A" 85 DW_AT_declaration (true) 86 DW_TAG_variable 87 DW_AT_name "a" 88 DW_AT_type (local ref to fwd decl "A") 89 90 DW_TAG_compile_unit 91 DW_AT_GNU_dwo_id (0xabcdef) 92 DW_AT_GNU_dwo_name ("M.pcm") 93 94The debug info inside a ``.pcm`` file may recursively reference 95further external types that are defined in other ``.pcm`` files. Clang 96generates external references (and debug info inside the modules) for 97the following types: 98 99C: 100 101- ``struct`` 102- ``union`` 103- ``enum`` 104- ``typedef`` 105 106Objective-C: 107 108- all the C types listed above 109- ``@interface`` 110 111C++: 112 113- all the C types listed above 114- ``namespace`` 115- any explicit ``extern template`` specializations 116 117LLDB supports this DWARF extension only when debugging from ``.o`` 118files. The ``dsymutil`` debug info linker also understands this format 119and will resolve all module type references to point straight to the 120underlying defining declaration. Because of this a ``.dSYM`` bundle 121will never contain any ``-gmodules``-style references. 122 123Apple SDK information 124--------------------- 125 126Clang and the Swift compiler emit information about the Xcode SDK that 127was used to build a translation unit into the ``DW_TAG_compile_unit``. 128The ``DW_AT_LLVM_sysroot`` attribute points to the SDK root 129(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 runtime 133------------------- 134 135Clang emits the Objective-C runtime version into the 136``DW_TAG_compile_unit`` using the 137``DW_AT_APPLE_major_runtime_version`` attribute. The value 2 stands 138for Objective-C 2.0. 139