[docs][llvm-objdump] Improve llvm-objdump documentation

[jhenderson]

Summary

The llvm-objdump document was missing many options, and there were also some style issues with it. This patches fixes all but the first issue listed in https://bugs.llvm.org/show_bug.cgi?id=42249 by:

1. Adding missing options and commands.
2. Standardising on double dashes for long-options throughout.
3. Moving Mach-O specific options to a separate section.
4. Removing options that don't exist or aren't relevant to llvm-objdump.

[MaskRay]

Nice!

[MaskRay]

BTW, there is a manpage: llvm/docs/llvm-objdump.1. It'd be nice to check if it needs updates as well.

[mtrent]

In D63606#1553087, @MaskRay wrote:

BTW, there is a manpage: llvm/docs/llvm-objdump.1. It'd be nice to check if it needs updates as well.

Do we know why there is a separate llvm-objdump.1 instead of just generating the man page from the rst file with Sphinx? Seems unfortunate to maintain two files with the same logical contents ...

[MaskRay]

In D63606#1553126, @mtrent wrote:

In D63606#1553087, @MaskRay wrote:

BTW, there is a manpage: llvm/docs/llvm-objdump.1. It'd be nice to check if it needs updates as well.

Do we know why there is a separate llvm-objdump.1 instead of just generating the man page from the rst file with Sphinx? Seems unfortunate to maintain two files with the same logical contents ...

It was added in D54864 by @emaste. Also see https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=233437
Do you know how good rst is to generate the man page? If it is less ideal (mdoc is a complex format...), personally I think it is fine to stick with the current manually maintained manpage...

Many people prefer man llvm-objdump to an online document...

[jhenderson]

Do you know how good rst is to generate the man page? If it is less ideal (mdoc is a complex format...), personally I think it is fine to stick with the current manually maintained manpage...

I don't know about the quality, but there are build targets generated by cmake for creating man pages. I took a quick look and it looks like the current version of the man page is not in too bad a state. I'll see what happens when I try to build the docs.

[jhenderson]

I got the man pages building from the rst using ninja docs-llvm-man, and a set of man pages were built, including one for llvm-objdump that mirrors the html doc. I don't see any reason why this can't be used: it's built by the sphinx build bot (see http://lab.llvm.org:8011/builders/llvm-sphinx-docs/builds/32333 for an example build).

Aside: I couldn't get the man page build to work on my Windows VS-based build, but my Linux one was fine.

@emaste, is there anything stopping using the auto-built version of the man page of llvm-objdump instead of the hand-maintained one? If not, can we delete it?

llvm/trunk/docs/CommandGuide/llvm-objdump.rst

 file name, :program:`llvm-objdump` will process a file on its standard input
 stream.
 
 COMMANDS
 --------
 At least one of the following commands are required, and some commands can be
 combined with other commands:
 
-.. option:: -d, -disassemble
+.. option:: -a, --archive-headers
+
+  Display the information contained within an archive's headers.
+
+.. option:: -d, --disassemble
 
   Display assembler mnemonics for the machine instructions. Disassembles all
-  text sections found in the input file(s).
+  text sections found in the input file(s) by default.
 
-.. option:: -D, -disassemble-all
+.. option:: -D, --disassemble-all
 
   Display assembler mnemonics for the machine instructions. Disassembles all
-  sections found in the input file(s).
+  sections found in the input file(s) by default.
+  
+.. option:: --disassemble-functions=<func1[,func2,...]>
+
+  Disassemble only the specified symbols. Implies :option:`--disassemble`.
+
+.. option:: --dwarf=<value>
+
+  Dump the specified DWARF debug sections. The supported values are:
+
+  `frames` - .debug_frame
+
+.. option:: -f, --file-headers
+
+  Display the contents of the overall file header.
+
+.. option:: --fault-map-section
+
+  Display the content of the fault map section.
+
+.. option:: -h, --headers, --section-headers
+
+  Display summaries of the headers for each section.
 
-.. option:: -help
+.. option:: --help
 
   Display usage information and exit. Does not stack with other commands.
 
-.. option:: -r
+.. option:: -p, --private-headers
+
+  Display format-specific file headers.
+
+.. option:: -r, --reloc
 
   Display the relocation entries in the file.
 
-.. option:: -s
+.. option:: -R, --dynamic-reloc
 
-  Display the content of each section.
+  Display the dynamic relocation entries in the file.
 
-.. option:: -section-headers
+.. option:: --raw-clang-ast
 
-  Display summaries of the headers for each section.
+  Dump the raw binary contents of the clang AST section.
+
+.. option:: -s, --full-contents
 
-.. option:: -t
+  Display the contents of each section.
+
+.. option:: -t, --syms
 
   Display the symbol table.
 
-.. option:: -version
+.. option:: -u, --unwind-info
+
+  Display the unwind info of the input(s).
+
+.. option:: --version
 
   Display the version of this program. Does not stack with other commands.
 
+.. option:: -x, --all-headers
+
+  Display all available header information. Equivalent to specifying
+  :option:`--archive-headers`, :option:`--file-headers`,
+  :option:`--private-headers`, :option:`--reloc`, :option:`--section-headers`,
+  and :option:`--syms`.
+
 OPTIONS
 -------
 :program:`llvm-objdump` supports the following options:
 
-.. option:: -arch=<architecture>
+.. option:: --adjust-vma=<offset>
 
-  Specify the architecture to disassemble. see ``-version`` for available
-  architectures.
+  Increase the displayed address in disassembly or section header printing by
+  the specified offset.
 
-.. option:: -cfg
+.. option:: --arch-name=<string>
 
-  Create a CFG for every symbol in the object file and write it to a graphviz
-  file (Mach-O-only).
+  Specify the target architecture when disassembling. Use :option:``--version``
+  for a list of available targets.
 
-.. option:: -dsym=<string>
+.. option:: -C, --demangle
 
-  Use .dSYM file for debug info.
+  Demangle symbol names in the output.
 
-.. option:: -g
+.. option:: -j, --section=<section1[,section2,...]>
 
-  Print line information from debug info if available.
+  Perform the specified command(s) on the specified section(s) only. For Mach-O
+  use `segment,section` to specify the section name.
 
-.. option:: -m, -macho
+.. option:: -l, --line-numbers
 
-  Use Mach-O specific object file parser. Commands and other options may behave
-  differently when used with ``-macho``.
+  When disassembling, display source line numbers with disassembly. Implies
+  :option:`--disassemble`.
+
+.. option:: -M, --disassembler-options=<opt1[,opt2,...]>
+
+  Pass target-specific disassembler options. Currently supported for ARM targets
+  only. Available options are ``reg-names-std`` and ``reg-names-raw``.
+
+.. option:: --mcpu=<cpu-name>
+
+  Target a specific CPU type for disassembly. Specify ``--mcpu=help`` to display
+  available CPUs.
+
+.. option:: --mattr=<a1,+a2,-a3,...>
+
+  Enable/disable target-specific attributes. Specify ``--mcpu=help`` to display
+  the available attributes.
+
+.. option:: --no-leading-addr
+
+  When disassembling, do not print the leading address in the disassembly
+  output.
+
+.. option:: --no-show-raw-insn
+
+  When disassembling instructions, do not print the raw bytes of the
+  instruction.
+
+.. option:: --print-imm-hex
+
+  Use hex format when printing immediate values in disassembly output.
 
-.. option:: -mattr=<a1,+a2,-a3,...>
+.. option:: -S, --source
 
-  Target specific attributes.
+  When disassembling, display source inlined with the disassembly.
+  Implies :option:`--disassemble`.
 
-.. option:: -mc-x86-disable-arith-relaxation
+.. option:: --show-lma
 
-  Disable relaxation of arithmetic instruction for X86.
+  Display the LMA column when dumping ELF section headers. Defaults to off
+  unless any section has different VMA and LMAs.
 
-.. option:: -stats
+.. option:: --start-address=<address>
 
-  Enable statistics output from program.
+  When disassembling, only disassemble from the specified address.
 
-.. option:: -triple=<string>
+  When printing relocations, only print the relocations patching offsets from at least ``address``.
 
-  Target triple to disassemble for, see ``-version`` for available targets.
+  When printing symbols, only print symbols with a value of at least ``address``.
 
-.. option:: -x86-asm-syntax=<style>
+.. option:: --stop-address=<address>
 
-  When used with the ``-disassemble`` option, choose style of code to emit from
+  When disassembling, only disassemble up to, but not including the specified address.
+
+  When printing relocations, only print the relocations patching offsets up to ``address``.
+
+  When printing symbols, only print symbols with a value up to ``address``.
+
+.. option:: --triple=<string>
+
+  Target triple to disassemble for, see ``--version`` for available targets.
+
+.. option:: -w, --wide
+
+  Ignored for compatibility with GNU objdump.
+
+.. option:: --x86-asm-syntax=<style>
+
+  When used with the ``--disassemble`` option, choose style of code to emit from
   X86 backend. Supported values are:
 
    .. option:: att
 
     AT&T-style assembly
 
    .. option:: intel
 
     Intel-style assembly
 
 
   The default disassembly style is **att**.
 
+.. option:: -z, --disassemble-zeroes
+
+  Do not skip blocks of zeroes when disassembling.
+
+MACH-O ONLY OPTIONS AND COMMANDS
+--------------------------------
+
+.. option:: --arch=<architecture>
+
+  Specify the architecture to disassemble. see ``--version`` for available
+  architectures.
+
+.. option:: --archive-member-offsets
+
+  Print the offset to each archive member for Mach-O archives (requires
+  :option:`--archive-headers`).
+
+.. option:: --bind
+
+  Display binding info
+
+.. option:: --cfg
+
+  Create a CFG for every symbol in the object file and write it to a graphviz
+  file.
+
+.. option:: --data-in-code
+
+  Display the data in code table.
+
+.. option:: --dis-symname=<name>
+
+  Disassemble just the specified symbol's instructions.
+
+.. option:: --dylibs-used
+
+  Display the shared libraries used for linked files.
+
+.. option:: --dsym=<string>
+
+  Use .dSYM file for debug info.
+
+.. option:: --dylib-id
+
+  Display the shared library's ID for dylib files.
+
+.. option:: --exports-trie
+
+  Display exported symbols.
+
+.. option:: -g
+
+  Print line information from debug info if available.
+
+.. option:: --full-leading-addr
+
+  Print the full leading address when disassembling.
+
+.. option:: --indirect-symbols
+
+  Display the indirect symbol table.
+
+.. option:: --info-plist
+
+  Display the info plist section as strings.
+
+.. option:: --lazy-bind
+
+  Display lazy binding info.
+
+.. option:: --link-opt-hints
+
+  Display the linker optimization hints.
+
+.. option:: -m, --macho
+
+  Use Mach-O specific object file parser. Commands and other options may behave
+  differently when used with ``--macho``.
+
+.. option:: --no-leading-headers
+
+  Do not print any leading headers.
+
+.. option:: --no-symbolic-operands
+
+  Do not print symbolic operands when disassembling.
+
+.. option:: --non-verbose
+
+  Display the information for Mach-O objects in non-verbose or numeric form.
+
+.. option:: --objc-meta-data
+
+  Display the Objective-C runtime meta data.
+
+.. option:: --private-header
+
+  Display only the first format specific file header.
+
+.. option:: --rebase
+
+  Display rebasing information.
+
+.. option:: --universal-headers
+
+  Display universal headers.
+
+.. option:: --weak-bind
+
+  Display weak binding information.
+
 BUGS
 ----
 
 To report bugs, please visit <http://llvm.org/bugs/>.
 
 SEE ALSO
 --------
 
-:manpage:`llvm-nm(1)`
+:manpage:`llvm-nm(1)`, :manpage:`llvm-readobj(1)`