[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 ↗

(On Diff #203582)

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 ↗

(On Diff #203582)

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

10 ↗

(On Diff #203582)

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 ↗

(On Diff #203582)

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 ↗

(On Diff #203582)

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 ↗

(On Diff #203582)

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 ↗

(On Diff #203582)

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 ↗

(On Diff #203883)

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

llvm/trunk/docs/CommandGuide/index.rst

.. 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/trunk/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/trunk/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/trunk/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/trunk/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
+a 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/trunk/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/trunk/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/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)