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() 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/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 [[--] ...] -.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 -- [ []]' 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/man/lldb.rst =================================================================== --- /dev/null +++ lldb/docs/man/lldb.rst @@ -0,0 +1,313 @@ +: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 + + Tells the debugger to attach to a process with the given name. + +.. option:: --attach-pid + + Tells the debugger to attach to a process with the given pid. + +.. option:: -n + + Alias for --attach-name + +.. option:: -p + + 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 + + Alias for --source-on-crash + +.. option:: -k + + 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 + + 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 + + When in batch mode, tells the debugger to source this file of lldb commands if the target crashes. + +.. option:: --one-line + + Tells the debugger to execute this one-line lldb command after any file provided on the command line has been loaded. + +.. option:: -O + + Alias for --one-line-before-file + +.. option:: -o + + Alias for --one-line + +.. option:: -Q + + Alias for --source-quietly + +.. option:: --source-before-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 + + 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 + + Tells the debugger to read in and execute the lldb commands in the given file, after any file has been loaded. + +.. option:: -S + + Alias for --source-before-file + +.. option:: -s + + Alias for --source + +.. option:: -x + + Alias for --no-lldbinit + +OPTIONS +------- + +.. option:: --arch + + Tells the debugger to use the specified architecture when starting and running the program. + +.. option:: -a + + Alias for --arch + +.. option:: --capture-path + + Tells the debugger to use the given filename for the reproducer. + +.. option:: --capture + + Tells the debugger to capture a reproducer. + +.. option:: --core + + Tells the debugger to use the full path to as the core file. + +.. option:: -c + + 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 + + Tells the debugger to use the file as the program to be debugged. + +.. option:: -f + + 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 + + Tells the debugger to replay a reproducer from . + +.. 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= + + Alias for --repl= + +.. option:: --repl-language + + Chooses the language for the REPL. + +.. option:: --repl= + + Runs lldb in REPL mode with a stub process with the given flags. + +.. option:: -R + + Alias for --repl-language + +SCRIPTING +--------- + +.. option:: -l + + 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 + + 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 + lldb -n + +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.