1dsymutil - manipulate archived DWARF debug symbol files
2=======================================================
3
4.. program:: dsymutil
5
6SYNOPSIS
7--------
8
9| :program:`dsymutil` [*options*] *executable*
10
11DESCRIPTION
12-----------
13
14:program:`dsymutil` links the DWARF debug information found in the object files
15for an executable *executable* by using debug symbols information contained in
16its symbol table. By default, the linked debug information is placed in a
17``.dSYM`` bundle with the same name as the executable.
18
19OPTIONS
20-------
21.. option:: --accelerator=<accelerator type>
22
23 Specify the desired type of accelerator table. Valid options are 'Apple',
24 'Dwarf', 'Default' and 'None'.
25
26.. option:: --arch <arch>
27
28 Link DWARF debug information only for specified CPU architecture types.
29 Architectures may be specified by name. When using this option, an error will
30 be returned if any architectures can not be properly linked.  This option can
31 be specified multiple times, once for each desired architecture. All CPU
32 architectures will be linked by default and any architectures that can't be
33 properly linked will cause :program:`dsymutil` to return an error.
34
35.. option:: --dump-debug-map
36
37 Dump the *executable*'s debug-map (the list of the object files containing the
38 debug information) in YAML format and exit. No DWARF link will take place.
39
40.. option:: --flat, -f
41
42 Produce a flat dSYM file. A ``.dwarf`` extension will be appended to the
43 executable name unless the output file is specified using the ``-o`` option.
44
45.. option:: --gen-reproducer
46
47 Generate a reproducer consisting of the input object files. Alias for
48 --reproducer=GenerateOnExit.
49
50.. option:: --help, -h
51
52 Print this help output.
53
54.. option:: --keep-function-for-static
55
56 Make a static variable keep the enclosing function even if it would have been
57 omitted otherwise.
58
59.. option:: --minimize, -z
60
61 When used when creating a dSYM file, this option will suppress the emission of
62 the .debug_inlines, .debug_pubnames, and .debug_pubtypes sections since
63 dsymutil currently has better equivalents: .apple_names and .apple_types. When
64 used in conjunction with ``--update`` option, this option will cause redundant
65 accelerator tables to be removed.
66
67.. option:: --no-odr
68
69 Do not use ODR (One Definition Rule) for uniquing C++ types.
70
71.. option:: --no-output
72
73 Do the link in memory, but do not emit the result file.
74
75.. option:: --no-swiftmodule-timestamp
76
77 Don't check the timestamp for swiftmodule files.
78
79.. option:: --num-threads <threads>, -j <threads>
80
81 Specifies the maximum number (``n``) of simultaneous threads to use when
82 linking multiple architectures.
83
84.. option:: --object-prefix-map <prefix=remapped>
85
86 Remap object file paths (but no source paths) before processing.  Use
87 this for Clang objects where the module cache location was remapped using
88 ``-fdebug-prefix-map``; to help dsymutil find the Clang module cache.
89
90.. option:: --oso-prepend-path <path>
91
92 Specifies a ``path`` to prepend to all debug symbol object file paths.
93
94.. option:: --out <filename>, -o <filename>
95
96 Specifies an alternate ``path`` to place the dSYM bundle. The default dSYM
97 bundle path is created by appending ``.dSYM`` to the executable name.
98
99.. option:: --papertrail
100
101 When running dsymutil as part of your build system, it can be desirable for
102 warnings to be part of the end product, rather than just being emitted to the
103 output stream. When enabled warnings are embedded in the linked DWARF debug
104 information.
105
106.. option:: --remarks-output-format <format>
107
108 Specify the format to be used when serializing the linked remarks.
109
110.. option:: --remarks-prepend-path <path>
111
112 Specify a directory to prepend the paths of the external remark files.
113
114.. option:: --reproducer <mode>
115
116 Specify the reproducer generation mode. Valid options are 'GenerateOnExit',
117 'GenerateOnCrash', 'Use', 'Off'.
118
119.. option:: --statistics
120
121 Print statistics about the contribution of each object file to the linked
122 debug info. This prints a table after linking with the object file name, the
123 size of the debug info in the object file (in bytes) and the size contributed
124 (in bytes) to the linked dSYM. The table is sorted by the output size listing
125 the object files with the largest contribution first.
126
127.. option:: --symbol-map <bcsymbolmap>
128
129 Update the existing dSYMs inplace using symbol map specified.
130
131.. option:: -s, --symtab
132
133 Dumps the symbol table found in *executable* or object file(s) and exits.
134
135.. option:: -S
136
137 Output textual assembly instead of a binary dSYM companion file.
138
139.. option:: --toolchain <toolchain>
140
141 Embed the toolchain in the dSYM bundle's property list.
142
143.. option:: -u, --update
144
145 Update an existing dSYM file to contain the latest accelerator tables and
146 other DWARF optimizations. This option will rebuild the '.apple_names' and
147 '.apple_types' hashed accelerator tables.
148
149.. option:: --use-reproducer <path>
150
151 Use the object files from the given reproducer path. Alias for
152 --reproducer=Use.
153
154.. option:: --verbose
155
156 Display verbose information when linking.
157
158.. option:: --verify
159
160 Run the DWARF verifier on the linked DWARF debug info.
161
162.. option:: -v, --version
163
164 Display the version of the tool.
165
166.. option:: -y
167
168 Treat *executable* as a YAML debug-map rather than an executable.
169
170EXIT STATUS
171-----------
172
173:program:`dsymutil` returns 0 if the DWARF debug information was linked
174successfully. Otherwise, it returns 1.
175
176SEE ALSO
177--------
178
179:manpage:`llvm-dwarfdump(1)`
180