docs/CommandGuide/dsymutil.rst

   1 dsymutil - manipulate archived DWARF debug symbol files
   2 =======================================================
   3
   4 .. program:: dsymutil
   5
   6 SYNOPSIS
   7 --------
   8
   9 | :program:`dsymutil` [*options*] *executable*
  10
  11 DESCRIPTION
  12 -----------
  13
  14 :program:`dsymutil` links the DWARF debug information found in the object files
  15 for an executable *executable* by using debug symbols information contained in
  16 its symbol table. By default, the linked debug information is placed in a
  17 ``.dSYM`` bundle with the same name as the executable.
  18
  19 OPTIONS
  20 -------
  21 .. option:: --arch=<arch>
  22
  23  Link DWARF debug information only for specified CPU architecture types.
  24  Architectures may be specified by name. When using this option, an error will
  25  be returned if any architectures can not be properly linked.  This option can
  26  be specified multiple times, once for each desired architecture. All CPU
  27  architectures will be linked by default and any architectures that can't be
  28  properly linked will cause :program:`dsymutil` to return an error.
  29
  30 .. option:: --dump-debug-map
  31
  32  Dump the *executable*'s debug-map (the list of the object files containing the
  33  debug information) in YAML format and exit. Not DWARF link will take place.
  34
  35 .. option:: -f, --flat
  36
  37  Produce a flat dSYM file. A ``.dwarf`` extension will be appended to the
  38  executable name unless the output file is specified using the -o option.
  39
  40 .. option:: -z, --minimize
  41
  42  When used when creating a dSYM file, this option will suppress the emission of
  43  the .debug_inlines, .debug_pubnames, and .debug_pubtypes sections since
  44  dsymutil currently has better equivalents: .apple_names and .apple_types. When
  45  used in conjunction with --update option, this option will cause redundant
  46  accelerator tables to be removed.
  47
  48 .. option:: --no-odr
  49
  50  Do not use ODR (One Definition Rule) for uniquing C++ types.
  51
  52 .. option:: --no-output
  53
  54  Do the link in memory, but do not emit the result file.
  55
  56 .. option:: --no-swiftmodule-timestamp
  57
  58  Don't check the timestamp for swiftmodule files.
  59
  60 .. option:: -j <n>, --num-threads=<n>
  61
  62  Specifies the maximum number (``n``) of simultaneous threads to use when
  63  linking multiple architectures.
  64
  65 .. option:: -o <filename>
  66
  67  Specifies an alternate ``path`` to place the dSYM bundle. The default dSYM
  68  bundle path is created by appending ``.dSYM`` to the executable name.
  69
  70 .. option:: --oso-prepend-path=<path>
  71
  72  Specifies a ``path`` to prepend to all debug symbol object file paths.
  73
  74 .. option:: --papertrail
  75
  76  When running dsymutil as part of your build system, it can be desirable for
  77  warnings to be part of the end product, rather than just being emitted to the
  78  output stream. When enabled warnings are embedded in the linked DWARF debug
  79  information.
  80
  81 .. option:: -s, --symtab
  82
  83  Dumps the symbol table found in *executable* or object file(s) and exits.
  84
  85 .. option:: --toolchain
  86
  87  Embed the toolchain in the dSYM bundle's property list.
  88
  89 .. option:: -u, --update
  90
  91  Update an existing dSYM file to contain the latest accelerator tables and
  92  other DWARF optimizations. This option will rebuild the '.apple_names' and
  93  '.apple_types' hashed accelerator tables.
  94
  95 .. option:: -v, --verbose
  96
  97  Display verbose information when linking.
  98
  99 .. option:: --version
 100
 101  Display the version of the tool.
 102
 103 .. option:: -y
 104
 105  Treat *executable* as a YAML debug-map rather than an executable.
 106
 107 EXIT STATUS
 108 -----------
 109
 110 :program:`dsymutil` returns 0 if the DWARF debug information was linked
 111 successfully. Otherwise, it returns 1.
 112
 113 SEE ALSO
 114 --------
 115
 116 :manpage:`llvm-dwarfdump(1)`