[llvm-lipo] Add docs for llvm-lipo

[alexander-shaposhnikov]

Summary

In this diff the file llvm-lipo.rst is added.

Test plan:
make -j8 sphinx
check that ./docs/html/CommandGuide/llvm-lipo.html is built correctly and looks okay.

[smeenai]

LGTM, but I'd wait for @mtrent.

docs/CommandGuide/llvm-lipo.rst

11 ↗

(On Diff #202317)

Nit: wrapping seems a bit weird here?

[alexander-shaposhnikov]

Minor update

[alexander-shaposhnikov]

Change wrapping

[alexander-shaposhnikov]

Ping) @mtrent @lhames

[mtrent]

I had trouble getting recommonmark.parser to install on my system, so I hacked at the patch to get the html and groff formatters to run. Should not be relevant to this review.

Please consider breaking apart the required commands from the optional options. This isn't important yet, but as soon as you add "-arch" you're going to have to deal with arguments that are optional and apply to more than one command, and arguments where one-and-only-one command is required. You can see an example in llvm-objdump.rst:

SYNOPSIS
     llvm-objdump [commands] [options] [filenames...]

DESCRIPTION
     The llvm-objdump utility prints stuff[...]

COMMANDS
     At least one of the following commands are required, and some commands can be combined with other commands:
[ ... ]

OPTIONS
     llvm-objdump supports the following options:
[ ... ]

Recent versions of the lipo man page also try to make this clear, although sometimes it's hard.

I rendered the CommandGuide as man and also as html, seemed ok.

docs/CommandGuide/llvm-lipo.rst

12 ↗

(On Diff #202322)

Serial comma is helpful in lists. "object files,"

"Report some information" is somewhat vague. Consider "report architectural information".

Consider "program can create universal binaries from [MDT? Mach-O?] files, extract regular object files from universal binaries, and display architecture information about both universal and regular files."

26 ↗

(On Diff #202322)

Only one arch is necessary. Consider -verify_arch <architecture 1> [<architecture 2> ...]

28 ↗

(On Diff #202322)

Verify that the specified architecture is present by doing what? Best to call out the command's exit status here.

Is it obvious what "architecture" means here? How would you describe that to someone?

The -verify_arch command only works on a single file (the Apple man page suggests otherwise, but AFAICT the code has never supported that). Do you need to mention that here?

[alexander-shaposhnikov]

Address @mtrent comments,

llvm-lipo.html5 KBDownload

[alexander-shaposhnikov]

the static html file (attached to my previous comments) contains some relative paths to various .css style sheets, so it needs to be placed into <your_build_dir>/docs/html/CommandGuide/ to be rendered correctly

[alexander-shaposhnikov]

docs/CommandGuide/llvm-lipo.rst

28 ↗

(On Diff #202322)

>Is it obvious what "architecture" means here?
no, it's not, honestly, I don't have a good explanation appropriate for docs other than "supported architecture name" with some popular examples, would you like me to add these bits here ?

[alexander-shaposhnikov]

[mtrent]

Thanks for making this!

docs/CommandGuide/llvm-lipo.rst

28 ↗

(On Diff #202322)

Looks like the major llvm tools (clang, lldb) just refer to "architecture" and leave it at that. llvm-objdump says "see version for available architectures" but the list is weird/incomplete. Let's leave it.

The opportunity of the man page / CommandGuide is to give some additional context that one can't infer from the command usage / -help. Considering lipo's job, this may be the best place in llvm.org to explain what these things are. All that said, that task isn't urgent, and it can wait for the rest of the functionality to come in. Having this file in place will help with that.

llvm/trunk/docs/CommandGuide/index.rst

.. toctree::
    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/trunk/docs/CommandGuide/llvm-lipo.rst

+llvm-lipo - LLVM tool for manipulating universal binaries
+=========================================================
+
+SYNOPSIS
+--------
+
+:program:`llvm-lipo` [*filenames...*] [*options*]
+
+DESCRIPTION
+-----------
+:program:`llvm-lipo` can create universal binaries from Mach-O files, extract regular object files from universal binaries, and display architecture information about both universal and regular files.
+
+COMMANDS
+--------
+:program:`llvm-lipo` supports the following mutually exclusive commands:
+
+.. option:: -help, -h
+
+  Display usage information and exit. 
+
+.. option:: -version
+
+  Display the version of this program. 
+
+.. option:: -verify_arch  <architecture 1> [<architecture 2> ...]
+
+  Take a single input file and verify the specified architectures are present in the file. 
+  If so then exit with a status of 0 else exit with a status of 1.
+
+BUGS
+----
+
+To report bugs, please visit <http://llvm.org/bugs/>.