DSYMUTIL(1)

📦
version 16.0.6 · 3 versions
, in ubuntu noble

💖 DSYMUTIL(1) — the LLVM manual, but make it make sense 💖

okay bestie, gather round, because we're about to talk about dsymutil, and honestly? she's iconic. this is section 1 of the LLVM manual set, so like, command-line-tool territory. buckle up 🎀

✨ NAME ✨

dsymutil — manipulate archived DWARF debug symbol files 🦋

✨ SYNOPSIS ✨

dsymutil [options] executable

✨ DESCRIPTION ✨

so here's the tea, bestie 🍓 dsymutil links up all the DWARF debug info it can find in the object files for an executable, and it does that by using the debug symbols info sitting inside that executable's symbol table. no cap.

and where does that linked debug info go by default? into a .dSYM bundle, named the exact same thing as the executable. slay. 💅

✨ OPTIONS ✨

  • --accelerator=<accelerator type> — pick which flavour of accelerator table you want. the valid options are ‘Apple’, ‘Dwarf’, ‘Default’ and ‘None’. choose wisely 👑
  • --arch <arch> — only link DWARF debug info for the CPU architecture types you name. you can specify architectures by name, and fr fr, if any of the architectures can't be properly linked you get an error back. you can drop this option multiple times, once per architecture you want. by default all CPU architectures get linked, and any that can't be properly linked will make dsymutil return an error. 😭
  • --dump-debug-map — dumps the executable's debug-map (that's the list of object files holding the debug info) in YAML format, and then it dips. no DWARF link happens at all. periodt.
  • --flat, -f — produce a flat dSYM file. a .dwarf extension gets appended to the executable name, unless you specified the output file with the -o option. 🧚
  • --gen-reproducer — generate a reproducer made of the input object files. it's an alias for –reproducer=GenerateOnExit.
  • --help, -h — print this help output. the classic.
  • --keep-function-for-static — makes a static variable keep the enclosing function, even if it would've been omitted otherwise. keeping the family together 🫶
  • --minimize, -z — when you use this while creating a dSYM file, it suppresses the emission of the .debug_inlines, .debug_pubnames, and .debug_pubtypes sections, because dsymutil currently has better equivalents: .apple_names and .apple_types. and when you use it together with the --update option, it will cause redundant accelerator tables to be removed. two birds, one stone 💅
  • --no-odr — do not use ODR (One Definition Rule) for uniquing C++ types.
  • --no-output — do the link in memory, but do not emit the result file. all vibes, no files ✨
  • --no-swiftmodule-timestamp — don't check the timestamp for swiftmodule files.
  • --num-threads <threads>, -j <threads> — specifies the maximum number (n) of simultaneous threads to use when linking multiple architectures. multitasking queen 👑
  • --object-prefix-map <prefix=remapped> — remap object file paths (but no source paths) before processing. use this for Clang objects where the module cache location was remapped using -fdebug-prefix-map, to help dsymutil find the Clang module cache. iykyk 🔥
  • --oso-prepend-path <path> — specifies a path to prepend to all debug symbol object file paths.
  • --out <filename>, -o <filename> — specifies an alternate path to place the dSYM bundle. the default dSYM bundle path is created by appending .dSYM to the executable name. main character energy, choosing your own destination 💖
  • --papertrail — when you're running dsymutil as part of your build system, it can be desirable for warnings to be part of the end product, rather than just being emitted to the output stream. when enabled, warnings are embedded in the linked DWARF debug information. leaving a lil trail 🌸
  • --remarks-output-format <format> — specify the format to be used when serializing the linked remarks.
  • --remarks-prepend-path <path> — specify a directory to prepend the paths of the external remark files.
  • --reproducer <mode> — specify the reproducer generation mode. valid options are ‘GenerateOnExit’, ‘GenerateOnCrash’, ‘Use’, ‘Off’. 🎀
  • --statistics — print statistics about the contribution of each object file to the linked debug info. this prints a table after linking with the object file name, the size of the debug info in the object file (in bytes) and the size contributed (in bytes) to the linked dSYM. the table is sorted by the output size, listing the object files with the largest contribution first. numbers girlies rise 🔥
  • --symbol-map <bcsymbolmap> — update the existing dSYMs inplace using the symbol map specified.
  • -s, --symtab — dumps the symbol table found in executable or object file(s) and exits.
  • -S — output textual assembly instead of a binary dSYM companion file. old school, love that for us ✨
  • --toolchain <toolchain> — embed the toolchain in the dSYM bundle's property list.
  • -u, --update — update an existing dSYM file to contain the latest accelerator tables and other DWARF optimizations. this option will rebuild the .apple_names and .apple_types hashed accelerator tables. glow-up time 💅
  • --use-reproducer <path> — use the object files from the given reproducer path. it's an alias for –reproducer=Use.
  • --verbose — display verbose information when linking. she's chatty and we love her 😭
  • --verify — run the DWARF verifier on the linked DWARF debug info. trust but verify, bestie 🫶
  • -v, --version — display the version of the tool.
  • -y — treat executable as a YAML debug-map rather than an executable. plot twist 🌈

✨ EXIT STATUS ✨

dsymutil returns 0 if the DWARF debug information was linked successfully. otherwise, it returns 1. so like, 0 = ate, 1 = not ate. 💀

✨ SEE ALSO ✨

✨ AUTHOR ✨

maintained by the LLVM Team (https://llvm.org/). 🫶

2003-2024, LLVM Project

okay that's the whole thing, bestie, and you absolutely understood all of it, i know you did 💖 this was version 15, dated 2024-04-14, brought to you by the LLVM crew — go forth and link that DWARF debug info, you've got this 🦋✨👑

📦 where this page comes from