[Docs] Generate the LLDB man page with Sphinx

[JDevlieghere]

Summary

This patch replaces the existing out-of-date man page for lldb and
replaces it with an RST file from which sphinx generates the actual
troff file. This is similar to how man pages are generated for the rest
of the LLVM utilities.

The man page is generated by building the docs-lldb-man target.

[JDevlieghere]

Here's what the output looks like: https://reviews.llvm.org/P8170

$ ninja docs-lldb-man
[1/1] Generating man Sphinx documentation for lldb into "/Volumes/Jonas/llvm/build-ra/tools/lldb/docs/man"
$ nroff -man  /Volumes/Jonas/llvm/build-ra/tools/lldb/docs/man/LLDB.1 | col -bx

[JDevlieghere]

Fix inconsistent newlines.

[aprantl]

Very nice!

lldb/docs/man/lldb.rst

17

While this is technically correct, as an end-user this makes me wonder if I picked the wrong command when I'm looking for the debugger.

How about:

lldb is a fully featured debugger. It is a command line interface to the LLDB debugger library.

291

CONFIGURATION FILES ?

[JDevlieghere]

Address Adrian's comments.

[jingham]

lldb/docs/man/lldb.rst

306

This isn't quite right. The actual rule is:

If the lldb library is loaded into an executable called Foo, lldb will first look for ~/.lldbinit-Foo, and if that exists will load and otherwise it will fall back on ~/.lldbinit. That goes for any executable.

Also, if we find ~/.lldbinit-<EXECUTABLE> we don't read the ~/.lldbinit.

There is special handling for Xcode, because when using Xcode the lldb library is actually loaded into a binary called lldb-rpc-server. So there's a little hack where IF the program happens to be lldb-rpc-server, we try .lldbinit-Xcode.

[JDevlieghere]

Update configuration file section.

[jingham]

lldb/docs/man/lldb.rst

81

This is probably wrong in the lldb help too - copy paste most likely. But the value of -one-line-on-crash is a command not a file...

[JDevlieghere]

Fix description for one-line-on-crash

[labath]

LGTM. Unless you're interested in tablegening the command line option list, that is. :)

[JDevlieghere]

In D70514#1754690, @labath wrote:

LGTM. Unless you're interested in tablegening the command line option list, that is. :)

I considered it, but maybe that's something for the thanksgiving break ;-)

lldb/docs/CMakeLists.txt

         remove_directory ${CMAKE_CURRENT_BINARY_DIR}/html)
       add_dependencies(docs-lldb-html clean-lldb-html)
     endif()
+
+    if (${SPHINX_OUTPUT_MAN})
+      add_sphinx_target(man lldb)
+    endif()
   endif()
 endif()

lldb/docs/conf.py

 
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
-man_pages = []
+man_pages = [('man/lldb', 'LLDB', u'LLDB Documentation', [u'LLVM project'], 1)]
 
 # If true, show URL addresses after external links.
 #man_show_urls = False

lldb/docs/lldb.1

-.Dd December 16, 2015   \" DATE
-.Dt LLDB 1           \" Program name and manual section number
-.Os
-.Sh NAME             \" Section Header - required - do not modify
-.Nm lldb
-.Nd The debugger
-.Sh SYNOPSIS         \" Section Header - required - do not modify
-.Nm lldb
-.Op Fl hvdexw
-.Op Fl a Ar arch
-.Op Fl c Ar core-file
-.Op Fl l Ar script-language
-.Op Fl s Ar lldb-commands
-.Op Fl n Ar process-name
-.Op Fl p Ar pid
-.Ar [[--] <PROGRAM-ARG1> <PROGRAM-ARG2> ...]
-.Sh DESCRIPTION      \" Section Header - required - do not modify
-.Nm
-is the command line interface for the LLDB debugger library.
-.Nm
-can debug C, C++, Objective-C, and Objective-C++ programs.
-.Pp
-The following options are available:
-.Bl -tag -width indent
-.It Fl h, -help
-Prints out the usage information for the
-.Nm
-debugger.
-The
-.Fl -help
-text may be more up-to-date and
-authoritative than the command line options described in this man
-page.
-.It Fl v, -version
-Prints out the version number of the
-.Nm
-debugger.
-.It Fl a, -arch Ar arch
-Specifies which architecture
-.Nm
-will use when launching the specified program (assuming the provided
-executable is built for multiple architectures.)
-.It Fl f, -file Ar filename
-Specifies the executable file that
-.Nm
-will be launching / attaching to.
-.It Fl n, -attach-name Ar process-name
-Specifies the name of a currently-running process to attach to.
-(or the name of a process to wait for if
-.Fl w
-is used.)
-.It Fl w, -wait-for
-When used in concert with
-.Fl n Ar process-name ,
-indicates that
-.Nm
-should wait for a new process of that name to be started -- and attach
-to it as early in the process-launch as possible.
-.It Fl p, -attach-pid Ar pid
-Specifies a currently running process that
-.Nm
-should attach to.
-.It Fl c, -core Ar core-file
-Specifies the core file to examine.
-.It Fl l, -script-language Ar language
-Tells the debugger to use the specified scripting language for
-user-defined scripts, rather than the default.
-Valid scripting
-languages that can be specified include Python, Perl, Ruby and Tcl.
-Currently only the Python extensions have been implemented.
-.It Fl d, -debug
-Tells the debugger to print out extra information for debugging itself.
-.It Fl s, -source Ar filename
-Tells
-.Nm
-to read in and execute the file
-.Qq Ar filename ,
-which should contain
-.Nm
-commands.
-.It Fl e, -editor
-Instructs
-.Nm
-to open source files using the host's "external editor" mechanism.
-.It Fl x, -no-lldbinit
-Do not automatically parse any '.lldbinit' files.
-.Pp
-(If you do not provide -f then the first argument will be the file to
-be debugged
-so 'lldb -- <filename> [<ARG1> [<ARG2>]]' also works.
-Remember to end the options with "--" if any of your arguments have
-a "-" in them.)
-.El
-.Sh USING LLDB
-In
-.Nm
-there is a
-.Cm help
-command which can be used to find descriptions and examples of all
-.Nm
-commands.
-To get help on
-.Qq Cm breakpoint set
-you would type
-.Qq Cm help breakpoint set .
-.Pp
-There is also an
-.Cm apropos
-command which will search the help text of all commands
-for a given term -- this is useful for locating a command by topic.
-For instance,
-.Qq Cm apropos breakpoint
-will list any command that has the word
-.Qq Cm breakpoint
-in its help text.
-.Sh FILES
-.Nm
-will read settings/aliases/commands from three files at startup, if they exist.
-.Pp
-First, it will read a
-.Pa ~/.lldbinit-debugger
-command file.
-If you are using the
-.Nm
-command line interface, this is
-.Pa ~/.lldbinit-lldb .
-If you are using
-.Nm
-inside a GUI debugger like
-.Nm Xcode
-this will be
-.Pa ~/.lldbinit-Xcode .
-This is a useful place to put settings that you want to apply only when a given
-.Nm
-command interpreter is used.
-.Pp
-Second,
-.Pa ~/.lldbinit
-is read.
-.Pp
-Third, an
-.Pa .lldbinit
-file in the current working directory (where
-.Nm
-is started) will be read.
-.Sh SEE ALSO
-The LLDB project page http://lldb.llvm.org/ has many different resources for
-.Nm
-users -- the gdb/lldb command equivalence page http://lldb.llvm.org/lldb-gdb.html can
-be especially helpful for users coming from gdb.
-.Sh BUGS
-To report bugs, please visit https://bugs.llvm.org/
-.Sh AUTHOR
-Maintained by the LLDB Team, http://lldb.llvm.org/

lldb/docs/man/lldb.rst

+:orphan:
+
+lldb -- The Debugger
+====================
+
+.. program:: lldb
+
+SYNOPSIS
+--------
+
+| :program:`lldb` [*options*] *executable*
+
+DESCRIPTION
+-----------
+
+:program:`lldb` is a fully featured debugger. It is a command line interface to
+the LLDB debugger library.
+
+ATTACHING
+---------
+
+.. option:: --attach-name <name>
+
+ Tells the debugger to attach to a process with the given name.
+
+.. option:: --attach-pid <pid>
+
+ Tells the debugger to attach to a process with the given pid.
+
+.. option:: -n <value>
+
+ Alias for --attach-name
+
+.. option:: -p <value>
+
+ Alias for --attach-pid
+
+.. option:: --wait-for
+
+ Tells the debugger to wait for a process with the given pid or name to launch before attaching.
+
+.. option:: -w
+
+ Alias for --wait-for
+
+COMMANDS
+--------
+
+.. option:: --batch
+
+ Tells the debugger to run the commands from -s, -S, -o & -O, and then quit.
+
+.. option:: -b
+
+ Alias for --batch
+
+.. option:: -K <value>
+
+ Alias for --source-on-crash
+
+.. option:: -k <value>
+
+ Alias for --one-line-on-crash
+
+.. option:: --local-lldbinit
+
+ Allow the debugger to parse the .lldbinit files in the current working directory, unless --no-lldbinit is passed.
+
+.. option:: --no-lldbinit
+
+ Do not automatically parse any '.lldbinit' files.
+
+.. option:: --one-line-before-file <command>
+
+ Tells the debugger to execute this one-line lldb command before any file provided on the command line has been loaded.
+
+.. option::  --one-line-on-crash <command>
+
+ When in batch mode, tells the debugger to source this file of lldb commands if the target crashes.
+
+.. option:: --one-line <command>
+
+ Tells the debugger to execute this one-line lldb command after any file provided on the command line has been loaded.
+
+.. option:: -O <value>
+
+ Alias for --one-line-before-file
+
+.. option:: -o <value>
+
+ Alias for --one-line
+
+.. option:: -Q
+
+ Alias for --source-quietly
+
+.. option:: --source-before-file <file>
+
+ Tells the debugger to read in and execute the lldb commands in the given file, before any file has been loaded.
+
+.. option:: --source-on-crash <file>
+
+ When in batch mode, tells the debugger to source this file of lldb commands if the target crashes.
+
+.. option:: --source-quietly
+
+ Tells the debugger to execute this one-line lldb command before any file has been loaded.
+
+.. option:: --source <file>
+
+ Tells the debugger to read in and execute the lldb commands in the given file, after any file has been loaded.
+
+.. option:: -S <value>
+
+ Alias for --source-before-file
+
+.. option:: -s <value>
+
+ Alias for --source
+
+.. option:: -x
+
+ Alias for --no-lldbinit
+
+OPTIONS
+-------
+
+.. option:: --arch <architecture>
+
+ Tells the debugger to use the specified architecture when starting and running the program.
+
+.. option:: -a <value>
+
+ Alias for --arch
+
+.. option:: --capture-path <filename>
+
+ Tells the debugger to use the given filename for the reproducer.
+
+.. option:: --capture
+
+ Tells the debugger to capture a reproducer.
+
+.. option:: --core <filename>
+
+ Tells the debugger to use the full path to <filename> as the core file.
+
+.. option:: -c <value>
+
+ Alias for --core
+
+.. option:: --debug
+
+ Tells the debugger to print out extra information for debugging itself.
+
+.. option:: -d
+
+ Alias for --debug
+
+.. option:: --editor
+
+ Tells the debugger to open source files using the host's "external editor" mechanism.
+
+.. option:: -e
+
+ Alias for --editor
+
+.. option:: --file <filename>
+
+ Tells the debugger to use the file <filename> as the program to be debugged.
+
+.. option:: -f <value>
+
+ Alias for --file
+
+.. option:: --help
+
+ Prints out the usage information for the LLDB debugger.
+
+.. option:: -h
+
+ Alias for --help
+
+.. option:: --no-use-colors
+
+ Do not use colors.
+
+.. option:: --replay <filename>
+
+ Tells the debugger to replay a reproducer from <filename>.
+
+.. option:: --version
+
+ Prints out the current version number of the LLDB debugger.
+
+.. option:: -v
+
+ Alias for --version
+
+.. option:: -X
+
+ Alias for --no-use-color
+
+REPL
+----
+
+.. option:: -r=<flags>
+
+ Alias for --repl=<flags>
+
+.. option:: --repl-language <language>
+
+ Chooses the language for the REPL.
+
+.. option:: --repl=<flags>
+
+ Runs lldb in REPL mode with a stub process with the given flags.
+
+.. option:: -R <value>
+
+ Alias for --repl-language
+
+SCRIPTING
+---------
+
+.. option:: -l <value>
+
+ Alias for --script-language
+
+.. option:: --python-path
+
+ Prints out the path to the lldb.py file for this version of lldb.
+
+.. option:: -P
+
+ Alias for --python-path
+
+.. option:: --script-language <language>
+
+ Tells the debugger to use the specified scripting language for user-defined scripts.
+
+EXAMPLES
+--------
+
+The debugger can be started in several modes.
+
+Passing an executable as a positional argument prepares lldb to debug the
+given executable. Arguments passed after -- are considered arguments to the
+debugged executable.
+
+  lldb --arch x86_64 /path/to/program -- --arch arvm7
+
+Passing one of the attach options causes lldb to immediately attach to the
+given process.
+
+  lldb -p <pid>
+  lldb -n <process-name>
+
+Passing --repl starts lldb in REPL mode.
+
+  lldb -r
+
+Passing --core causes lldb to debug the core file.
+
+  lldb -c /path/to/core
+
+Command options can be combined with these modes and cause lldb to run the
+specified commands before or after events, like loading the file or crashing,
+in the order provided on the command line.
+
+  lldb -O 'settings set stop-disassembly-count 20' -o 'run' -o 'bt'
+  lldb -S /source/before/file -s /source/after/file
+  lldb -K /source/before/crash -k /source/after/crash
+
+Note: In REPL mode no file is loaded, so commands specified to run after
+loading the file (via -o or -s) will be ignored.
+
+USING LLDB
+----------
+
+In lldb there is a help command which can be used to find descriptions
+and examples of all lldb commands.  To get help on "breakpoint set" you
+would type "help breakpoint set".
+
+There is also an apropos command which will search the help text of all
+commands for a given term ‐‐ this is useful for locating a command by topic.
+For instance, "apropos breakpoint" will list any command that has the word
+"breakpoint" in its help text.
+
+CONFIGURATION FILES
+-------------------
+
+lldb will read settings/aliases/commands from three files at startup, if they
+exist.
+
+First, it will read a ~/.lldbinit‐debugger command file.  If you are using the
+lldb command line interface, this is ~/.lldbinit‐lldb.  If you are using lldb
+inside a GUI debugger like Xcode this will be ~/.lldbinit‐Xcode.  This is a
+useful place to put settings that you want to apply only when a given lldb
+command interpreter is used.
+
+Second, ~/.lldbinit is read.
+
+Third, an .lldbinit file in the current working directory (where lldb is
+started) will be read.
+
+SEE ALSO
+--------
+
+The LLDB project page https://lldb.llvm.org has many different resources
+for lldb users ‐‐ the gdb/lldb command equivalence page
+https://lldb.llvm.org/use/map.html can be especially helpful for users
+coming from gdb.