[Docs][llvm-strip] Add help text to llvm-strip rst doc

[mmpozulp]

Summary

Addresses https://bugs.llvm.org/show_bug.cgi?id=42383

[jhenderson]

Thanks for working on this! You're missing a number of aliases from the list. Please make sure they are included in the doc. Also, please use the text from the llvm-objcopy doc where the switch is common to the two tools.

llvm/docs/CommandGuide/llvm-strip.rst

2 ↗

(On Diff #212130)

Delete the trailing '=' here.

9 ↗

(On Diff #212130)

llvm-strip's usage is different to llvm-objcopy's. This follows llvm-objcopy's style. It should be something like :program:'llvm-strip' [*options*] *inputs...* (with back-ticks around llvm-strip instead of apostrophes, used due to not knowing how to escape them in Phabricator).

14 ↗

(On Diff #212130)

This description should mention what happens by default, what the meaning of '-' is for input file names, and what happens for archive inputs (see the llvm-objcopy doc).

27 ↗

(On Diff #212130)

This, and many of the other options use a more verbose/clearer description in the llvm-objcopy documentation for the same switch. I'd recommend you copy the text from llvm-objcopy's doc in each case, assuming it makes sense.

33–35 ↗

(On Diff #212130)

This should be in the "ELF-specific" section.

40 ↗

(On Diff #212130)

What about -h/--help?

47 ↗

(On Diff #212130)

This should say something about what happens if there are multiple input files.

49–51 ↗

(On Diff #212130)

Whilst not really ELF-specific, this is implemented only for ELF currently, so should be down in that section.

63 ↗

(On Diff #212130)

This needs extra mark-up. See llvm-objcopy's documentation.

71 ↗

(On Diff #212130)

This text isn't right. The switch has nothing to do with symbols. As with the other switches, use the text from llvm-objcopy.

81 ↗

(On Diff #212130)

This should be grouped with --enable-deterministic-archives, like -D for --disable-deterministic archives.

85 ↗

(On Diff #212130)

Also -V, right?

120 ↗

(On Diff #212130)

Also -K?

llvm/tools/llvm-objcopy/StripOpts.td

35–36 ↗

(On Diff #212130)

Do this in a separate change.

[mmpozulp]

In D65384#1604328, @jhenderson wrote:

Thanks for working on this! You're missing a number of aliases from the list. Please make sure they are included in the doc.

Happy to help :). Will do.

Also, please use the text from the llvm-objcopy doc where the switch is common to the two tools.

Yes, good idea. In fact, I'm going to move the common switches into a new file, say CommonOpts.td, and include "CommonOpts.td" at the top of ObjcopyOpts.td and StripOpts.td. That way we don't have the same switch in two different places each with different HelpText.

[mmpozulp]

Incorporate feedback from @jhenderson.

Move common help options from ObjcopyOpts.td and StripOpts.td
into CommonOpts.td and CommonAliases.td which are included
in the former files.

Add HelpText to aliases which did not already have it.

[jhenderson]

The tabelgen option changes should be in their own review. I haven't tried to review them here.

llvm/docs/CommandGuide/llvm-strip.rst

15 ↗

(On Diff #213313)

Perhaps rephrase this to make the behaviour clearer. E.g. "If no other stripping or remove options are specified, --strip-all will be enabled by default."

87 ↗

(On Diff #213313)

Change this to "remove all debug sections". Specifying other switches could mean that the "only" is invalid.

[jhenderson]

CC'ing @wolfgangp, due to D65787 adding a new switch. One of the two patches will need updating once the other lands.

[mmpozulp]

Incorporate feedback from @jhenderson.
Add new switch --strip-sections. Thanks, James.

[mmpozulp]

Also, I moved the tablegen changes to https://reviews.llvm.org/D65991

[jhenderson]

LGTM! Thanks.

llvm/trunk/docs/CommandGuide/llvm-strip.md

-# llvm-strip - object stripping tool
-
-## SYNOPSIS
-
-**llvm-strip** [*options*]
-
-## DESCRIPTION
-
-**llvm-strip** is a tool to strip sections and symbols from object files.
-
-The tool is still in active development, but in most scenarios it works as a
-drop-in replacement for GNU's **strip**.
-
-## SEE ALSO
-
-[llvm-objcopy](llvm-objcopy.html)

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

+llvm-strip - object stripping tool
+==================================
+
+.. program:: llvm-strip
+
+SYNOPSIS
+--------
+
+:program:`llvm-strip` [*options*] *inputs...*
+
+DESCRIPTION
+-----------
+
+:program:`llvm-strip` is a tool to strip sections and symbols from object files.
+If no other stripping or remove options are specified, :option:`--strip-all`
+will be enabled by default.
+
+The input files are modified in-place. If "-" is specified for the input file,
+the input is read from the program's standard input stream.
+
+If the input is an archive, any requested operations will be applied to each
+archive member individually.
+
+The tool is still in active development, but in most scenarios it works as a
+drop-in replacement for GNU's :program:`strip`.
+
+GENERIC AND CROSS-PLATFORM OPTIONS
+----------------------------------
+
+The following options are either agnostic of the file format, or apply to
+multiple file formats.
+
+.. option:: --disable-deterministic-archives, -U
+
+ Use real values for UIDs, GIDs and timestamps when updating archive member
+ headers.
+
+.. option:: --discard-all, -x
+
+ Remove most local symbols from the output. Different file formats may limit
+ this to a subset of the local symbols. For example, file and section symbols in
+ ELF objects will not be discarded.
+
+.. option::  --enable-deterministic-archives, -D
+
+ Enable deterministic mode when stripping archives, i.e. use 0 for archive member
+ header UIDs, GIDs and timestamp fields. On by default.
+
+.. option:: --help, -h
+
+ Print a summary of command line options.
+
+.. option::  --no-strip-all
+
+ Disable --strip-all.
+
+.. option::  -o <file>
+
+ Write output to <file>. Multiple input files cannot be used in combination
+ with -o.
+
+.. option:: --regex
+
+ If specified, symbol and section names specified by other switches are treated
+ as extended POSIX regular expression patterns.
+
+.. option:: --remove-section <section>, -R
+
+ Remove the specified section from the output. Can be specified multiple times
+ to remove multiple sections simultaneously.
+
+.. option:: --strip-all-gnu
+
+ Remove all symbols, debug sections and relocations from the output. This option
+ is equivalent to GNU :program:`strip`'s ``--strip-all`` switch.
+
+.. option:: --strip-all, -S
+
+ For ELF objects, remove from the output all symbols and non-alloc sections not
+ within segments, except for .gnu.warning sections and the section name table.
+
+ For COFF objects, remove all symbols, debug sections, and relocations from the
+ output.
+
+.. option:: --strip-debug, -g
+
+ Remove all debug sections.
+
+.. option:: --strip-sections
+
+ Remove all section headers and all sections not in segments.
+
+.. option:: --strip-symbol <symbol>, -N
+
+ Remove all symbols named ``<symbol>`` from the output. Can be specified
+ multiple times to remove multiple symbols.
+
+.. option:: --strip-unneeded
+
+ Remove all local or undefined symbols that are not required by relocations.
+
+.. option:: --version, -V
+
+  Display the version of this program.
+
+COFF-SPECIFIC OPTIONS
+---------------------
+
+The following options are implemented only for COFF objects. If used with other
+objects, :program:`llvm-strip` will either emit an error or silently ignore
+them.
+
+.. option:: --only-keep-debug
+
+ Remove the contents of non-debug sections from the output, but keep the section
+ headers.
+
+ELF-SPECIFIC OPTIONS
+--------------------
+
+The following options are implemented only for ELF objects. If used with other
+objects, :program:`llvm-strip` will either emit an error or silently ignore
+them.
+
+.. option:: --allow-broken-links
+
+ Allow llvm-strip to remove sections even if it would leave invalid section
+ references. Any invalid sh_link fields will be set to zero.
+
+.. option:: --discard-locals, -X
+
+ Remove local symbols starting with ".L" from the output.
+
+.. option:: --keep-file-symbols
+
+ Keep symbols of type `STT_FILE`, even if they would otherwise be stripped.
+
+ .. option:: --keep-section <section>
+
+ When removing sections from the output, do not remove sections named
+ ``<section>``. Can be specified multiple times to keep multiple sections.
+
+.. option:: --keep-symbol <symbol>, -K
+
+ Do not remove symbols named ``<symbol>``. Can be specified multiple times to
+ keep multiple symbols.
+
+.. option::  --preserve-dates, -p
+
+ Preserve access and modification timestamps.
+
+
+EXIT STATUS
+-----------
+
+:program:`llvm-strip` exits with a non-zero exit code if there is an error.
+Otherwise, it exits with code 0.
+
+BUGS
+----
+
+To report bugs, please visit <http://llvm.org/bugs/>.
+
+SEE ALSO
+--------
+
+:manpage:`llvm-objcopy(1)`