Add a CommandGuide for llvm-objdump

[mtrent]

Summary

Add a CommandGuide for llvm-objdump summarizing its usage along with some
general context.

[Eugene.Zelenko]

docs/CommandGuide/llvm-objdump.rst

282

Probably doc should be used instead of manpage.

[mtrent]

docs/CommandGuide/llvm-objdump.rst

282

Can you explain? This file is written in the same style as all the other documents in llvm/docs, in rst which can be converted into html, man, epub or whatever you like.

[mtrent]

docs/CommandGuide/llvm-objdump.rst

282

Oh I see what you mean. I'll have a look.

[mtrent]

Specify a manpages_url so that CommandGuide references can be used both
as traditional UNIX man-page references and also as nicely hyperlinked
documentation.

[beanz]

Given how mach-o is radically different from ELF, it might make sense to sort or group ELF and mach-o specific options. Right now we only call out options that only work on Mach-o, but I assume some of the options only work on ELF and/or COFF. Might make sense to document that behavior correctly too.

Below I've marked out a few places where mach-o options are missing the annotation.

docs/CommandGuide/llvm-objdump.rst

28

Does this require -macho?

56

I assume this also requires -macho?

77

requires -macho?

106

requires -macho?

173

Maybe change "Mach-O-only" to "requires -macho" for consistency.

185

I assume this also requires -macho?

201

Side note for a separate conversation. Do we really need this flag? Is there a reason we can't just use the magic bits at the beginning of the file stream to set the mode?

[mtrent]

The short summary is "-macho" doesn't mean the target file is Mach-O. "-macho" means use the Mach-O specific file parser for walking the file contents, instead of using llvm-Object. When run in this way llvm-objdump will display information in a different way. Like it or hate it, it's what llvm-objdump does currently.

docs/CommandGuide/llvm-objdump.rst

28

No. The input file must be Mach-O (I assume) but you don't need to use the "-macho" specific binary parser.

56

No. The input file must be Mach-O (I assume) but you don't need to use the "-macho" specific binary parser.

77

No. The input file must be Mach-O (I assume) but you don't need to use the "-macho" specific binary parser.

106

No. The input file must be Mach-O (I assume) but you don't need to use the "-macho" specific binary parser.

173

Actually, looks like the -cfg option has been removed from newer objdumps, so I'll pull it from the CommandGuide.

201

This flag is basically magic sauce meaning "run llvm-objdump in a otool compatible way", affecting both how the data is consumed and how it is printed. You can verify this yourself by comparing the output of "llvm-objdump -r" and "llvm-objdump -r -macho". It's entirely possible that general purpose developer tools would like to have a common llvm-y way of describing object file details, such as for some kind of CI system or packaging automation. So the same way you should use the high-level llvm-Object API to return data for general files, you can use the high-level llvm-objdump CLI to return this same data.

As Mach-O specific features that were implemented using the llbm-Ojbect API, one could argue that those features should have been made in the Mach-O specific parser instead of llvm-Object. I am going to argue that changing the implementation of llvm-objdump is beyond the scope of my task, which is to make a CommandGuide describing llvm-objdump's current behavior. :)

[mtrent]

Remove the obsolete "-cfg" option, as called out during review feedback.

[beanz]

One last small fix

docs/CommandGuide/llvm-objdump.rst

277

I think what you want here is:

:program:`llvm-nm`

That should produce the correct link in both the online and manpage documentation.

[mtrent]

In D50034#1186327, @beanz wrote:

One last small fix

It turns out :program: does not make a hyperlink in the comman guide. Email with details sent.

The :manpage: Sphinx Role does one job beyond a basic style change, and that is let you carve up the man ref syntax <page>(<section>) and arrange it into a URL. I have modified the docs/conf.py file to do this for llvm.org in the first round of review feedback. So I believe with great confidence that :manpage: is the correct Sphinx Role to use for the “See Also” section of this (and all) CommandGuide pages. It may be the only job it is good for, but for this task, I haven’t seen anything better so far.

[beanz]

@mtrent and I talked offline, and he explained how the sphinx documentation covers the manpage and program directives, and I agree with his assertion that using manpage is correct.

docs/CommandGuide/index.rst

.. toctree::
    lli
    llvm-link
    llvm-ar
    llvm-lib
    llvm-nm
    llvm-config
    llvm-diff
    llvm-cov
+   llvm-objdump
    llvm-profdata
    llvm-stress
    llvm-symbolizer
    llvm-dwarfdump
    dsymutil
    llvm-mca
 
 Debugging Tools

docs/CommandGuide/llvm-objdump.rst

+llvm-objdump - LLVM's object file dumper
+========================================
+
+SYNOPSIS
+--------
+
+:program:`llvm-objdump` [*commands*] [*options*] [*filenames...*]
+
+DESCRIPTION
+-----------
+The :program:`llvm-objdump` utility prints the contents of object files and
+final linked images named on the command line. If no file name is specified,
+:program:`llvm-objdump` will attempt to read from *a.out*. If *-* is used as a
+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:: -archive-headers
+
+  Print archive headers for Mach-O archives (requires ``-macho``).
+
+.. option:: -bind
+
+  Display mach-o binding info.
+
+.. option:: -data-in-code
+
+  Print the data in code table for Mach-O objects (requires ``-macho``).
+
+.. option:: -disassemble
+
+  Display assembler mnemonics for the machine instructions.
+
+.. option:: -dwarf=<string>
+
+  Dump of dwarf debug sections:
+
+    .. option:: frames
+   
+      .debug_frame
+
+.. option:: -dylib-id
+
+  Print the shared library's id for the dylib Mach-O file (requires ``-macho``).
+
+.. option:: -dylibs-used
+
+  Print the shared libraries used for linked Mach-O files (requires ``-macho``).
+  
+.. option:: -exports-trie
+ 
+  Display mach-o exported symbols.
+
+.. option:: -fault-map-section
+
+  Display contents of faultmap section.
+
+.. option:: -help
+
+  Display usage information and exit. Does not stack with other commands.
+
+.. option:: -indirect-symbols
+
+  Print indirect symbol table for Mach-O objects (requires ``-macho``).
+
+.. option:: -info-plist
+
+  Print the info plist section as strings for Mach-O objects (requires
+  ``-macho``).
+
+.. option:: -lazy-bind
+
+  Display mach-o lazy binding info.
+
+.. option:: -link-opt-hints
+
+  Print the linker optimization hints for Mach-O objects (requires ``-macho``).
+
+.. option:: -objc-meta-data
+
+  Print the Objective-C runtime meta data for Mach-O files (requires
+  ``-macho``).
+
+.. option:: -private-header
+
+  Display only the first format specific file header.
+  
+.. option:: -private-headers
+
+  Display format specific file headers.
+
+.. option:: -r
+
+  Display the relocation entries in the file.
+
+.. option:: -raw-clang-ast
+
+  Dump the raw binary contents of the clang AST section.
+
+.. option:: -rebase
+
+  Display mach-o rebasing info.
+
+.. option:: -s
+
+  Display the content of each section.
+
+.. option:: -section=<string>
+
+  Operate on the specified sections only. With ``-macho`` dump segment,section.
+
+.. option:: -section-headers
+
+  Display summaries of the headers for each section.
+
+.. option:: -t
+
+  Display the symbol table.
+
+.. option:: -universal-headers
+
+  Print Mach-O universal headers (requires ``-macho``).
+
+.. option:: -unwind-info
+
+  Display unwind information.
+
+.. option:: -version
+
+  Display the version of this program. Does not stack with other commands.
+
+.. option:: -weak-bind
+
+  Display mach-o weak binding info.
+
+OPTIONS
+-------
+:program:`llvm-objdump` supports the following options:
+
+.. option:: -aarch64-neon-syntax
+
+  Choose style of NEON code to emit from AArch64 backend:
+
+    .. option:: generic
+    
+      Emit generic NEON assembly.
+      
+    .. option:: apple
+    
+      Emit Apple-style NEON assembly.
+
+.. option:: -arch=<architecture>
+
+  Specify the architecture to disassemble. see ``-version`` for available
+  architectures.
+
+.. option:: -arch-name=<string>
+
+  Target arch to disassemble for, see ``-version`` for available targets.
+
+.. option:: -archive-member-offsets
+
+  Print the offset to each archive member for Mach-O archives (requires
+  ``-macho`` and ``-archive-headers``).
+
+.. option:: -cfg
+
+  Create a CFG for every symbol in the object file and write it to a graphviz
+  file (Mach-O-only).
+
+.. option:: -color
+
+  Use colored syntax highlighting (default=autodetect).
+
+.. option:: -dis-symname=<string>
+
+  Disassemble just this symbol's instructions (requires ``-macho``).
+
+.. option:: -dsym=<string>
+
+  Use .dSYM file for debug info.
+
+.. option:: -full-leading-addr
+
+  Print full leading address.
+
+.. option:: -g
+
+  Print line information from debug info if available.
+
+.. option:: -line-numbers
+
+  Display source line numbers with disassembly. Implies disassemble object.
+
+.. option:: -macho
+
+  Use Mach-O specific object file parser.
+
+.. option:: -mattr=<a1,+a2,-a3,...>
+
+  Target specific attributes.
+  
+.. option:: -mc-x86-disable-arith-relaxation
+
+  Disable relaxation of arithmetic instruction for X86.
+
+.. option:: -mcpu=<cpu-name>
+
+  Target a specific cpu type (-mcpu=help for details)
+
+.. option:: -no-leading-addr
+
+  Print no leading address.
+  
+.. option:: -no-leading-headers
+
+  Print no leading headers.
+  
+.. option:: -no-show-raw-insn
+
+  When disassembling instructions, do not print the instruction bytes.
+  
+.. option:: -no-symbolic-operands
+
+  Do not symbolic operands when disassembling (requires ``-macho``).
+  
+.. option:: -non-verbose
+
+  Print the info for Mach-O objects in non-verbose or numeric form (requires
+  ``-macho``).
+  
+.. option:: -print-imm-hex
+
+  Use hex format for immediate values.
+  
+.. option:: -print-module-scope
+
+  When printing IR for ``print-[before|after]{-all}`` always print a module IR.
+
+.. option:: -start-address=<address>
+
+  Disassemble beginning at address.
+
+.. option:: -stats
+
+  Enable statistics output from program.
+
+.. option:: -stop-address=<address>
+
+  Stop disassembly at address.
+  
+.. option:: -triple=<string>
+
+  Target triple to disassemble for, see ``-version`` for available targets.
+  
+.. 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.
+
+BUGS
+----
+
+To report bugs, please visit <http://llvm.org/bugs/>.
+
+SEE ALSO
+--------
+
+:manpage:`llvm-nm(1)`

docs/conf.py

 #man_show_urls = False
 
 # FIXME: Define intersphinx configuration.
 intersphinx_mapping = {}
 
 # Pygment lexer are sometimes out of date (when parsing LLVM for example) or
 # wrong. Suppress the warning so the build doesn't abort.
 suppress_warnings = [ 'misc.highlighting_failure' ]
+
+# Direct html-ified man pages to llvm.org
+manpages_url = 'https://llvm.org/docs/CommandGuide/{page}.html'