This is an archive of the discontinued LLVM Phabricator instance.

Differential D63719

[docs][llvm-readobj] Improve llvm-readobj documentation
ClosedPublic

Authored by jhenderson on Jun 24 2019, 7:59 AM.

Details

Reviewers
rupprecht
MaskRay
grimar
mtrent
peter.smith
pcc
atanasyan
Commits
rL364306: [docs][llvm-readobj] Improve llvm-readobj documentation
rGb96d9d8bdada: [docs][llvm-readobj] Improve llvm-readobj documentation
Summary

There were a number of issues with the llvm-readobj documentation. The following points were raised in https://bugs.llvm.org/show_bug.cgi?id=42255, and have been fixed in this patch:

  1. The description section claimed "The tool and its output is primarily designed for use in FileCheck-based tests" which is not really the case any more.
  2. The documentation used single-dash long options for option names, but references in the help text to other options exclusively used double-dashes. Fixed by standardising on double-dashes for all long-form options.
  3. The majority of options available and in the help text were not present in the documentation. This patch adds them.
  4. Several aliases, both long and short, were missing, e.g. --relocs.

Additionally, this patch improves the documentation by:

  1. Splitting the options into categories based on the file format they are specific to.
  2. Updating the Exit Status section to correctly mention that errors lead to a non-zero exit code.
  3. Adding a See Also section referencing other similar LLVM tools.
  4. Improving/correcting some of the descriptions of options that did not quite match up with what llvm-readobj does.

Diff Detail

Repository
rL LLVM

Event Timeline

jhenderson created this revision.Jun 24 2019, 7:59 AM
Herald added a project: Restricted Project. · View Herald TranscriptJun 24 2019, 7:59 AM
peter.smith added a comment.Jun 24 2019, 9:13 AM

Thanks for doing this, this is a big improvement. One mild suggestion, but no objections from me.

docs/CommandGuide/llvm-readobj.rst
26

It might be worth being less specific about what --all does due to the likelihood of it getting out of date as new options are added? I suspect that people wanting --all are those that want to dump all output to a text file in order to search interactively rather than need to know exactly what it does in order to parse it. Perhaps something like "Equivalent to adding the major output format options that are relevant to the file format."

I've not a strong opinion here, so feel free to ignore.

mtrent accepted this revision.Jun 24 2019, 3:23 PM
This revision is now accepted and ready to land.Jun 24 2019, 3:23 PM
MaskRay added inline comments.Jun 24 2019, 11:35 PM
docs/CommandGuide/llvm-readobj.rst
80

--sd if the intention is to standardize on double-dashes

(Say, at some point, for llvm-readelf alone, or both llvm-readelf and llvm-readobj, -sd becomes -s -d)

84

--sr

134

--dt

jhenderson updated this revision to Diff 206406.Jun 25 2019, 3:55 AM
jhenderson marked 4 inline comments as done.

Make two-letter options use double-dashes, make the --all description less fragile to new options, and standardise on "display" instead of "print" for consistency throughout the document.

MaskRay accepted this revision.Jun 25 2019, 4:17 AM
peter.smith added a comment.Jun 25 2019, 5:43 AM

Thanks for the update LGTM too.

Closed by commit rGb96d9d8bdada: [docs][llvm-readobj] Improve llvm-readobj documentation (authored by jhenderson). · Explain WhyJun 25 2019, 6:20 AM
This revision was automatically updated to reflect the committed changes.
MaskRay mentioned this in D106037: [llvm-readobj] Remove one-dash long options.Jul 15 2021, 10:28 AM
MaskRay mentioned this in rG3f9004c19c9b: [llvm-readelf/llvm-readobj] Remove one-dash long options.Jul 16 2021, 12:03 PM

Revision Contents

PathSize
docs/
CommandGuide/
263 lines

Diff 206216

docs/CommandGuide/llvm-readobj.rst

llvm-readobj - LLVM Object Reader llvm-readobj - LLVM Object Reader
================================= =================================
SYNOPSIS SYNOPSIS
-------- --------
:program:`llvm-readobj` [*options*] [*input...*] :program:`llvm-readobj` [*options*] [*input...*]
DESCRIPTION DESCRIPTION
----------- -----------
The :program:`llvm-readobj` tool displays low-level format-specific information The :program:`llvm-readobj` tool displays low-level format-specific information
about one or more object files. The tool and its output is primarily designed about one or more object files.
for use in FileCheck-based tests.
OPTIONS
-------
If ``input`` is "``-``" or omitted, :program:`llvm-readobj` reads from standard If ``input`` is "``-``" or omitted, :program:`llvm-readobj` reads from standard
input. Otherwise, it will read from the specified ``filenames``. input. Otherwise, it will read from the specified ``filenames``.
.. option:: -help GENERAL AND MULTI-FORMAT OPTIONS
--------------------------------
Print a summary of command line options. These options are applicable to more than one file format, or are unrelated to
file formats.
.. option:: --all
Equivalent to specifying :option:`--file-headers`, :option:`--program-headers`,
peter.smithUnsubmitted
Done
ReplyInline Actions

It might be worth being less specific about what --all does due to the likelihood of it getting out of date as new options are added? I suspect that people wanting --all are those that want to dump all output to a text file in order to search interactively rather than need to know exactly what it does in order to parse it. Perhaps something like "Equivalent to adding the major output format options that are relevant to the file format."

I've not a strong opinion here, so feel free to ignore.

peter.smith: It might be worth being less specific about what --all does due to the likelihood of it getting…
:option:`--sections`, :option:`--symbols`, :option:`--relocations`,
:option:`--dynamic-table`, :option:`--notes`, :option:`--version-info`,
:option:`--unwind`, :option:`--section-groups`, and
:option:`--elf-hash-histogram`. Note that some of these options are not
applicable to all file formats.
.. option:: -version .. option:: --addrsig
Display the version of this program Display the address-significance table.
.. option:: -file-headers, -h .. option:: --color
Use colors in the output for warnings and errors.
.. option:: --expand-relocs
When used with :option:`--relocations`, display each relocation in an expanded
multi-line format.
.. option:: --file-headers, -h
Display file headers. Display file headers.
.. option:: -sections, -s .. option:: --headers, -e
Display all sections. Equivalent to setting: :option:`--file-headers`, :option:`--program-headers`,
and :option:`--sections`.
.. option:: --help
Print a summary of command line options.
.. option:: -section-data, -sd .. option:: --help-list
When used with ``-sections``, display section data for each section shown. Print an uncategorized summary of command line options.
.. option:: -section-relocations, -sr .. option:: --hex-dump=<section[,section,...]>, -x
When used with ``-sections``, display relocations for each section shown. Print the specified section(s) as hexadecimal bytes. ``section`` may be a
section index or section name.
.. option:: -section-symbols, -st .. option:: --needed-libs
When used with ``-sections``, display symbols for each section shown. Display the needed libraries.
.. option:: -relocations, -r .. option:: --relocations, --relocs, -r
Display the relocation entries in the file. Display the relocation entries in the file.
.. option:: -symbols, -t .. option:: --sections, --section-headers, -s, -S
Display the symbol table. Display all sections.
.. option:: -dyn-symbols .. option:: --section-data, -sd
MaskRayUnsubmitted
Done
ReplyInline Actions

--sd if the intention is to standardize on double-dashes

(Say, at some point, for llvm-readelf alone, or both llvm-readelf and llvm-readobj, -sd becomes -s -d)

MaskRay: `--sd` if the intention is to standardize on double-dashes (Say, at some point, for llvm…
Display the dynamic symbol table (only for ELF object files). When used with :option:`--sections`, display section data for each section shown.
.. option:: -unwind, -u .. option:: --section-relocations, -sr
MaskRayUnsubmitted
Done
ReplyInline Actions

--sr

MaskRay: `--sr`
Display unwind information. When used with :option:`--sections`, display relocations for each section shown.
.. option:: -expand-relocs .. option:: --section-symbols, -st
When used with ``-relocations``, display each relocation in an expanded When used with :option:`--sections`, display symbols for each section shown.
multi-line format.
.. option:: -dynamic-table .. option:: --stackmap
Display the ELF .dynamic section table (only for ELF object files). Display contents of the stackmap section.
.. option:: -needed-libs .. option:: --string-dump=<section[,section,...]>, -p
Display the needed libraries (only for ELF object files). Display the specified section(s) as a list of strings. ``section`` may be a
section index or section name.
.. option:: -program-headers .. option:: --symbols, --syms, -t
Display the ELF program headers (only for ELF object files). Display the symbol table.
.. option:: -elf-section-groups, -g .. option:: --unwind, -u
Display section groups (only for ELF object files). Display unwind information.
.. option:: -demangle, -C .. option:: --version
Print demangled symbol names in the output. Display the version of this program.
.. option:: @<FILE> .. option:: @<FILE>
Read command-line options from response file `<FILE>`. Read command-line options from response file `<FILE>`.
ELF SPECIFIC OPTIONS
--------------------
The following options are implemented only for the ELF file format.
.. option:: --arm-attributes
Display the ARM attributes section. Only applicable for ARM architectures.
.. option:: --demangle, -C
Print demangled symbol names in the output.
.. option:: --dyn-relocations
Display the dynamic relocation entries.
.. option:: --dyn-symbols, --dyn-syms, -dt
MaskRayUnsubmitted
Done
ReplyInline Actions

--dt

MaskRay: `--dt`
Display the dynamic symbol table.
.. option:: --dynamic-table, --dynamic, -d
Display the dynamic table.
.. option:: --elf-cg-profile
Display the callgraph profile section.
.. option:: --elf-hash-histogram, --histogram, -I
Display a bucket list histogram for dynamic symbol hash tables.
.. option:: --elf-linker-options
Display the linker options section.
.. option:: --elf-output-style=<value>
Specify the style to dump ELF information in. Valid options are ``LLVM`` and
``GNU``. ``LLVM`` output (the default) is an expanded and structured format,
whilst ``GNU`` output mimics the equivalent GNU :program:`readelf` output.
.. option:: --elf-section-groups, --section-groups, -g
Display section groups.
.. option:: --gnu-hash-table
Display the GNU hash table for dynamic symbols.
.. option:: --hash-symbols
Display the dynamic symbols derived from the hash table.
.. option:: --hash-table
Display the hash table for dynamic symbols.
.. option:: --notes, -n
Display all notes.
.. option:: --program-headers, --segments, -l
Display the program headers.
.. option:: --raw-relr
Do not decode relocations in RELR relocation sections when displaying them.
.. option:: --section-mapping
Display the section to segment mapping.
.. option:: --version-info, -V
Display version sections.
MACH-O SPECIFIC OPTIONS
-----------------------
The following options are implemented only for the Mach-O file format.
.. option:: --macho-data-in-code
Display the Data in Code command.
.. option:: --macho-dsymtab
Display the Dsymtab command.
.. option:: --macho-indirect-symbols
Display indirect symbols.
.. option:: --macho-linker-options
Display the Mach-O-specific linker options.
.. option:: --macho-segment
Display the Segment command.
.. option:: --macho-version-min
Display the version min command.
PE/COFF SPECIFIC OPTIONS
------------------------
The following options are implemented only for the PE/COFF file format.
.. option:: --codeview
Display CodeView debug information.
.. option:: --codeview-ghash
Enable global hashing for CodeView type stream de-duplication.
.. option:: --codeview-merged-types
Display the merged CodeView type stream.
.. option:: --codeview-subsection-bytes
Dump raw contents of CodeView debug sections and records.
.. option:: --coff-basereloc
Display the .reloc section.
.. option:: --coff-debug-directory
Display the debug directory.
.. option:: --coff-directives
Display the .drectve section.
.. option:: --coff-exports
Display the export table.
.. option:: --coff-imports
Display the import table.
.. option:: --coff-load-config
Display the load config.
.. option:: --coff-resources
Display the .rsrc section.
EXIT STATUS EXIT STATUS
----------- -----------
:program:`llvm-readobj` returns 0. :program:`llvm-readobj` returns 0 under normal operation. It returns a non-zero
exit code if there were any errors.
SEE ALSO
--------
:manpage:`llvm-nm(1)`, :manpage:`llvm-objdump(1)`, :manpage:`llvm-readelf(1)`