[docs] Add "GNU binutils Replacements" section to command guide

[rupprecht]

Summary

This splits out a section in the command guide for llvm tools that can be used as replacements for GNU tools. For pages that didn't exist, I added stub pages that can be individually filled in by followup patches.

Tested by running ninja docs-llvm-html and inspecting locally.

[MaskRay]

Change the title from GNU replacements to GNU binutils replacements?

[grimar]

llvm/docs/CommandGuide/index.rst

17

GNU 'as' is also a part of binutils:
https://en.wikipedia.org/wiki/GNU_Binutils

Should it also be moved?

[jhenderson]

Great! This looks good. I think we can iterate on improving the documents in due course, but this at least gives us a place to start.

llvm/docs/CommandGuide/index.rst

17

Is llvm-as intended to be a drop-in replacement yet? I have a feeling that it's not ready based on something @rupprecht said a while back.

llvm/docs/CommandGuide/llvm-readelf.md

11

It's not just different defaults though. Some of the switches are not the same either. Perhaps it would be better to say "with a command-line interface and output style more closely resembling GNU readelf"?

[smeenai]

llvm/docs/CommandGuide/index.rst

17

llvm-as converts textual IR to bitcode, so it's very different from GNU as. llvm-mc would be closer to the functionality of GNU as, but I believe e.g. it doesn't support macros, so it's definitely not a drop-in replacement.

[rupprecht]

• Clarify llvm-readelf compatibility

[rupprecht]

llvm/docs/CommandGuide/index.rst

17

Yes, we don't yet have a replacement for as, despite the same-sounding name of llvm-as.

[grimar]

LGTM

llvm/docs/CommandGuide/index.rst

17

Oh, right. I missed I am usually using llvm-mc + GNU as and not llvm-as + GNU as.

And llvm-mc is not mentioned at all in this file for some reason, not sure why.

[jhenderson]

LGTM, with one nit.

llvm/docs/CommandGuide/index.rst

17

And llvm-mc is not mentioned at all in this file for some reason, not sure why.

Probably because nobody's written documentation for it!

llvm/docs/CommandGuide/llvm-readelf.md

9–10

Nit "with command-line" -> "with a command-line"

llvm/docs/CommandGuide/index.rst

 LLVM Command Guide
 ------------------
 
 The following documents are command descriptions for all of the LLVM tools.
 These pages describe how to use the LLVM commands and what their options are.
 Note that these pages do not describe all of the options available for all
 tools. To get a complete listing, pass the ``--help`` (general options) or
 ``--help-hidden`` (general and debugging options) arguments to the tool you are
 interested in.
 
 Basic Commands
 ~~~~~~~~~~~~~~
 
 .. toctree::
    :maxdepth: 1
 
    llvm-as
    llvm-dis
    opt
    llc
    lli
    llvm-link
-   llvm-ar
    llvm-lib
    llvm-lipo
-   llvm-nm
-   llvm-objdump
    llvm-config
    llvm-cxxmap
    llvm-diff
    llvm-cov
    llvm-profdata
    llvm-stress
    llvm-symbolizer
-   llvm-addr2line
    llvm-dwarfdump
    dsymutil
    llvm-mca
    llvm-readobj
 
+GNU binutils replacements
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. toctree::
+   :maxdepth: 1
+
+   llvm-addr2line
+   llvm-ar
+   llvm-cxxfilt
+   llvm-nm
+   llvm-objcopy
+   llvm-objdump
+   llvm-ranlib
+   llvm-readelf
+   llvm-size
+   llvm-strings
+   llvm-strip
+
 Debugging Tools
 ~~~~~~~~~~~~~~~
 
 .. toctree::
    :maxdepth: 1
 
    bugpoint
    llvm-extract

llvm/docs/CommandGuide/llvm-cxxfilt.md

+# llvm-cxxfilt - a symbol demangler
+
+## SYNOPSIS
+
+**llvm-cxxfilt** [*options*]
+
+## DESCRIPTION
+
+**llvm-cxxfilt** is symbol demangler that can be used as a replacement for the
+GNU **c++filt** tool.

llvm/docs/CommandGuide/llvm-objcopy.md

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

llvm/docs/CommandGuide/llvm-ranlib.md

+# llvm-ranlib - generates an archive index
+
+## SYNOPSIS
+
+**llvm-ranlib** [*options*]
+
+## DESCRIPTION
+
+**llvm-ranlib** is an alias for the [llvm-ar](llvm-ar.html) tool that generates
+an index for an archive. It can be used as a replacement for GNU's **ranlib**
+tool.
+
+Running **llvm-ranlib** is equivalent to running **llvm-ar s**.
+
+## SEE ALSO
+
+Refer to [llvm-ar](llvm-ar.html) for additional information.

llvm/docs/CommandGuide/llvm-readelf.md

+# llvm-readelf - a drop-in replacement for readelf
+
+## SYNOPSIS
+
+**llvm-readelf** [*options*]
+
+## DESCRIPTION
+
+**llvm-readelf** is an alias for the [llvm-readobj](llvm-readobj.html) tool with
+command-line interface and output style more closely resembling GNU **readelf**.
+
+Here are some of those differences:
+
+* Uses `--elf-output-style=GNU` by default.
+
+* Allows single-letter grouped flags (e.g. `llvm-readelf -SW` is the same as
+  `llvm-readelf -S -W`).
+
+* Allows use of `-s` as an alias for `--symbols` (versus `--section-headers` in
+  **llvm-readobj**) for GNU **readelf** compatibility.
+
+* Prevents use of `-sr`, `-sd`, `-st` and `-dt` **llvm-readobj** aliases, to
+  avoid conflicting with standard GNU **readelf** grouped flags.
+
+## SEE ALSO
+
+Refer to [llvm-readobj](llvm-readobj.html) for additional information.

llvm/docs/CommandGuide/llvm-size.md

+# llvm-size - print segment sizes
+
+## SYNOPSIS
+
+**llvm-size** [*options*]
+
+## DESCRIPTION
+
+**llvm-size** is a tool that prints segment sizes in object files. The goal is
+to make it a drop-in replacement for GNU's **size**.

llvm/docs/CommandGuide/llvm-strings.md

+# llvm-strings - print strings
+
+## SYNOPSIS
+
+**llvm-strings** [*options*]
+
+## DESCRIPTION
+
+**llvm-strings** is a tool that prints strings in object files. The goal is to
+make it a drop-in replacement for GNU's **size**.

llvm/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)