JDevlieghere updated this revision to Diff 230353. JDevlieghere added a comment.
Fix description for `one-line-on-crash` CHANGES SINCE LAST ACTION https://reviews.llvm.org/D70514/new/ https://reviews.llvm.org/D70514 Files: lldb/docs/CMakeLists.txt lldb/docs/conf.py lldb/docs/lldb.1 lldb/docs/man/lldb.rst lldb/tools/driver/Options.td
Index: lldb/tools/driver/Options.td =================================================================== --- lldb/tools/driver/Options.td +++ lldb/tools/driver/Options.td @@ -5,6 +5,8 @@ class R<list<string> prefixes, string name> : Option<prefixes, name, KIND_REMAINING_ARGS>; +// Please keep this in sync with the man page in docs/man/lldb.rst + // Attaching options. def grp_attach : OptionGroup<"attaching">, HelpText<"ATTACHING">; @@ -117,7 +119,7 @@ def one_line_on_crash: Separate<["--", "-"], "one-line-on-crash">, MetaVarName<"<command>">, - HelpText<"When in batch mode, tells the debugger to source this file of lldb commands if the target crashes.">, + HelpText<"When in batch mode, tells the debugger to run this one-line lldb command if the target crashes.">, Group<grp_command>; def: Separate<["-"], "k">, Alias<one_line_on_crash>, Index: lldb/docs/man/lldb.rst =================================================================== --- /dev/null +++ lldb/docs/man/lldb.rst @@ -0,0 +1,316 @@ +: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 run this one-line lldb command 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 :program:`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 :program:`lldb` to immediately attach +to the given process. + + lldb -p <pid> + lldb -n <process-name> + +Passing --repl starts :program:`lldb` in REPL mode. + + lldb -r + +Passing --core causes :program:`lldb` to debug the core file. + + lldb -c /path/to/core + +Command options can be combined with these modes and cause :program:`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 :program:`lldb` there is a help command which can be used to find +descriptions and examples of all :program:`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 +------------------- + +:program:`lldb` reads things like settings, aliases and commands from the +.lldbinit file. It will first look for ~/.lldbinit and load that first. +Secondly, it will look for an .lldbinit file in the current working directory. +For security reasons, :program:`lldb` will print a warning and not source this +file by default. This behavior can be changed by changing the +target.load-cwd-lldbinit setting. + +To always load the .lldbinit file in the current working directory, add the +following command to ~/.lldbinit: + + settings set target.load-cwd-lldbinit true + +To never load the .lldbinit file in the current working directory and silence +the warning, add the following command to ~/.lldbinit: + + settings set target.load-cwd-lldbinit false + +SEE ALSO +-------- + +The LLDB project page https://lldb.llvm.org has many different resources +for :program:`lldb` users ‐‐ the gdb/lldb command equivalence page +https://lldb.llvm.org/use/map.html can be especially helpful for users +coming from gdb. Index: lldb/docs/lldb.1 =================================================================== --- lldb/docs/lldb.1 +++ /dev/null @@ -1,154 +0,0 @@ -.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/ Index: lldb/docs/conf.py =================================================================== --- lldb/docs/conf.py +++ lldb/docs/conf.py @@ -226,7 +226,7 @@ # 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 Index: lldb/docs/CMakeLists.txt =================================================================== --- lldb/docs/CMakeLists.txt +++ lldb/docs/CMakeLists.txt @@ -66,5 +66,9 @@ 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-commits mailing list lldb-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-commits
