llvm/docs/CommandGuide/llvm-dwarfutil.rst

   1 llvm-dwarfutil - A tool to copy and manipulate debug info
   2 =========================================================
   3
   4 .. program:: llvm-dwarfutil
   5
   6 SYNOPSIS
   7 --------
   8
   9 :program:`llvm-dwarfutil` [*options*] *input* *output*
  10
  11 DESCRIPTION
  12 -----------
  13
  14 :program:`llvm-dwarfutil` is a tool to copy and manipulate debug info.
  15
  16 In basic usage, it makes a semantic copy of the input to the output. If any
  17 options are specified, the output may be modified along the way, e.g.
  18 by removing unused debug info.
  19
  20 If "-" is specified for the input file, the input is read from the program's
  21 standard input stream. If "-" is specified for the output file, the output
  22 is written to the standard output stream of the program.
  23
  24 The tool is still in active development.
  25
  26 COMMAND-LINE OPTIONS
  27 --------------------
  28
  29 .. option:: --garbage-collection
  30
  31  Removes pieces of debug information related to discarded sections.
  32  When the linker does section garbage collection the abandoned debug info
  33  is left behind. Such abandoned debug info references address ranges using
  34  tombstone values. Thus, when this option is specified, the tool removes
  35  debug info which is marked with the tombstone value.
  36
  37  That option is enabled by default.
  38
  39 .. option:: --odr-deduplication
  40
  41  Remove duplicated types (if "One Definition Rule" is supported by source
  42  language). Keeps first type definition and removes other definitions,
  43  potentially significantly reducing the size of output debug info.
  44
  45  That option is enabled by default.
  46
  47 .. option:: --help, -h
  48
  49  Print a summary of command line options.
  50
  51 .. option:: --no-garbage-collection
  52
  53  Disable :option:`--garbage-collection`.
  54
  55 .. option:: --no-odr-deduplication
  56
  57  Disable :option:`--odr-deduplication`.
  58
  59 .. option:: --no-separate-debug-file
  60
  61  Disable :option:`--separate-debug-file`.
  62
  63 .. option:: --num-threads=<n>, -j
  64
  65  Specifies the maximum number (`n`) of simultaneous threads to use
  66  for processing.
  67
  68 .. option:: --separate-debug-file
  69
  70  Generate separate file containing output debug info. Using
  71  :program:`llvm-dwarfutil` with that option equals to the
  72  following set of commands:
  73
  74 .. code-block:: console
  75
  76  :program:`llvm-objcopy` --only-keep-debug in-file out-file.debug
  77  :program:`llvm-objcopy` --strip-debug in-file out-file
  78  :program:`llvm-objcopy` --add-gnu-debuglink=out-file.debug out-file
  79
  80 .. option:: --tombstone=<value>
  81
  82  <value> can be one of the following values:
  83
  84    - `bfd`: zero for all addresses and [1,1] for DWARF v4 (or less) address ranges and exec.
  85
  86    - `maxpc`: -1 for all addresses and -2 for DWARF v4 (or less) address ranges.
  87
  88    - `universal`: both `bfd` and `maxpc`.
  89
  90    - `exec`: match with address ranges of executable sections.
  91
  92    The value `universal` is used by default.
  93
  94 .. option:: --verbose
  95
  96  Enable verbose logging. This option disables multi-thread mode.
  97
  98 .. option:: --verify
  99
 100  Run the DWARF verifier on the output DWARF debug info.
 101
 102 .. option:: --version
 103
 104  Print the version of this program.
 105
 106 SUPPORTED FORMATS
 107 -----------------
 108
 109 The following formats are currently supported by :program:`llvm-dwarfutil`:
 110
 111 ELF
 112
 113 EXIT STATUS
 114 -----------
 115
 116 :program:`llvm-dwarfutil` exits with a non-zero exit code if there is an error.
 117 Otherwise, it exits with code 0.
 118
 119 BUGS
 120 ----
 121
 122 To report bugs, please visit <https://github.com/llvm/llvm-project/labels/tools:llvm-dwarfutil/>.