[lldb][Docs] Remove .txt copy of tutorial

[DavidSpickett]

This was last modified in 4fd3347 in 2021 and was made obsolete by the RST version that edb874b added in 2019.

There are some differences but at this point, I'd bet the RST is the correct one.

[llvmbot]

@llvm/pr-subscribers-lldb

Author: David Spickett (DavidSpickett)

Changes

This was last modified in 4fd3347 in 2021 and was made obsolete by the RST version that edb874b added in 2019.

There are some differences but at this point, I'd bet the RST is the correct one.

---

Full diff: https://github.com/llvm/llvm-project/pull/90585.diff

1 Files Affected:

• (removed) lldb/docs/lldb-for-gdb-users.txt (-488)

diff --git a/lldb/docs/lldb-for-gdb-users.txt b/lldb/docs/lldb-for-gdb-users.txt
deleted file mode 100644
index e5eae376bb4807..00000000000000
--- a/lldb/docs/lldb-for-gdb-users.txt
+++ /dev/null
@@ -1,488 +0,0 @@
-Here's a short precis of how to run lldb if you are familiar with the
-gdb command set:
-
-
-1) LLDB Command Structure:
-
-First some details on lldb command structure to help orient you...
-
-Unlike gdb's command set, which is rather free-form, we tried to make
-the lldb command syntax fairly structured.  The commands are all of the
-form
-
-<noun> <verb> [-options [option-value]] [argument [argument...]]
-
-The command line parsing is done before command execution, so it is
-uniform across all the commands.  The command syntax is very simple,
-basically arguments, options and option values are all white-space
-separated.  If you need to put a backslash or double-quote character
-in an argument you back-slash it in the argument.  That makes the
-command syntax more regular, but it also means you may have to
-quote some arguments in lldb that you wouldn't in gdb.
-
-Options can be placed anywhere on the command line, but if the arguments
-begin with a "-" then you have to tell lldb that you're done with options
-using the "--" option.  So for instance, the "process launch" command takes
-the "-s" option to mean "stop the process at the first instruction".  It's 
-arguments are the arguments you are passing to the program.  So if you wanted
-to pass an argument that contained a "-" you would have to do:
-
-(lldb) process launch -- -program_arg value
-
-We also tried to reduce the number of special purpose argument
-parsers, which sometimes forces the user to be a little more explicit
-about stating their intentions.  The first instance you'll note of
-this is the breakpoint command.  In gdb, to set a breakpoint, you
-would just say:
-
-(gdb) break foo.c:12
-
-or
-
-(gdb) break foo
-
-if foo is a function.  As time went on, the parser that tells foo.c:12
-from foo from foo.c::foo (which means the function foo in the file
-foo.c) got more and more complex and bizarre, and especially in C++
-there are times where there's really no way to specify the function
-you want to break on.  The lldb commands are more verbose but also precise.  
-So you say:
-
-(lldb) breakpoint set -f foo.c -l 12
-
-to set a file & line breakpoint.  To set a breakpoint on a function
-by name, you do:
-
-(lldb) breakpoint set -n foo
-
-This can allow us to be more expressive, so you can say:
-
-(lldb) breakpoint set -M foo
-
-to break on all C++ methods named foo, or:
-
-(lldb) breakpoint set -S alignLeftEdges:
-
-to set a breakpoint on all ObjC selectors called alignLeftEdges:.  It
-also makes it easy to compose specifications, like:
-
-(lldb) breakpoint set -s foo.dylib -n foo
-
-for all functions called foo in the shared library foo.dylib.  Suggestions
-on more interesting primitives of this sort are also very welcome.
-
-So for instance:
-
-(lldb) breakpoint set -n "-[SKTGraphicView alignLeftEdges:]"
-
-Just like gdb, the lldb command interpreter does a shortest unique
-string match on command names, so the previous command can also be
-typed:
-
-(lldb) b s -n "-[SKTGraphicView alignLeftEdges:]"
-
-lldb also supports command completion for source file names, symbol
-names, file names, etc. Completion is initiated by a hitting a <TAB>.
-Individual options in a command can have different completers, so for
-instance the -f option in "breakpoint" completes to source files, the
--s option to currently loaded shared libraries, etc...  We can even do 
-things like if you specify -s, and are completing on -f, we will only
-list source files in the shared library specified by -s...
-
-The individual commands are pretty extensively documented, using
-the "help" command.  And there is an "apropos" command that will
-search the help for a particular word and dump a summary help string
-for each matching command.
-
-Finally, there is a mechanism to construct aliases for commonly used
-commands.  So for instance if you get annoyed typing
-
-(lldb) b s -f foo.c -l 12
-
-you can do:
-
-(lldb) command alias bfl breakpoint set -f %1 -l %2
-(lldb) bfl foo.c 12
-
-We have added a few aliases for commonly used commands (e.g. "step",
-"next" and "continue") but we haven't tried to be exhaustive because
-in our experience it is more convenient to make the basic commands
-unique down to a letter or two, and then learn these sequences than
-fill the namespace with lots of aliases, and then have to type them
-all the way out.
-
-However, users are free to customize lldb's command set however they
-like, and since lldb reads the file ~/.lldbinit at startup, you can
-store all your aliases there and they will be generally available to
-you.  Your aliases are also documented in the help command so you can
-remind yourself of what you've set up.
-
-lldb also has a built-in Python interpreter, which is accessible by
-the "script" command.  All the functionality of the debugger is
-available as classes in the Python interpreter, so the more complex
-commands that in gdb you would introduce with the "define" command can
-be done by writing Python functions using the lldb-Python library,
-then loading the scripts into your running session and accessing them
-with the "script" command.  
-
-
-
-2) A typical session:
-
-
-a) Setting the program to debug:
-
-
-As with gdb, you can start lldb and specify the file you wish to debug
-on the command line:
-
-$ lldb /Projects/Sketch/build/Debug/Sketch.app
-Current executable set to '/Projects/Sketch/build/Debug/Sketch.app' (x86_64).
-
-or you can specify it after the fact with the "file" command:
-
-(lldb) file /Projects/Sketch/build/Debug/Sketch.app
-Current executable set to '/Projects/Sketch/build/Debug/Sketch.app' (x86_64).
-
-
-b) Setting breakpoints:
-
-
-We've discussed how to set breakpoints above.  You can use "help break set" 
-to see all the options for breakpoint setting.  For instance, we might do:
-
-(lldb) b s -S alignLeftEdges:
-Breakpoint created: 1: name = 'alignLeftEdges:', locations = 1, resolved = 1
-
-You can find out about the breakpoints you've set with:
-
-(lldb) break list
-Current breakpoints:
-1: name = 'alignLeftEdges:', locations = 1, resolved = 1
-  1.1: where = Sketch`-[SKTGraphicView alignLeftEdges:] + 33 at /Projects/Sketch/SKTGraphicView.m:1405, address = 0x0000000100010d5b, resolved, hit count = 0 
-
-Note that each "logical" breakpoint can have multiple "locations".
-The logical breakpoint has an integer id, and its locations have an
-id within their parent breakpoint (the two are joined by a ".",
-e.g. 1.1 in the example above.)  
-
-Also the breakpoints remain "live" so that if another shared library
-were to be loaded that had another implementation of the
-"alignLeftEdges:" selector, the new location would be added to
-breakpoint 1 (e.g. a "1.2" breakpoint would be set on the newly loaded
-selector).
-
-The other piece of information in the breakpoint listing is whether the
-breakpoint location was "resolved" or not.  A location gets resolved when
-the file address it corresponds to gets loaded into the program you are
-debugging.  For instance if you set a breakpoint in a shared library that 
-then gets unloaded, that breakpoint location will remain, but it will no 
-longer be "resolved".
-
-One other thing to note for gdb users is that lldb acts like gdb with:
-
-(gdb) set breakpoint pending on
-
-That is, lldb should always make a breakpoint from your specification, even
-if it couldn't find any locations that match the specification.  You can tell
-whether the expression was resolved or not by checking the locations field
-in "breakpoint list", and we report the breakpoint as "pending" when you
-set it so you can tell you've made a typo more easily, if that was indeed 
-the reason no locations were found:
-
-(lldb) b s -f no_such_file.c -l 10000000
-Breakpoint created: 1: file ='no_such_file.c', line = 10000000, locations = 0 (pending)
-
-You can delete, disable, set conditions and ignore counts either on all the
-locations generated by your logical breakpoint, or on particular locations
-your specification resolved to.  For instance if we wanted to add a command
-to print a backtrace when we hit this breakpoint we could do:
-
-(lldb) b command add -c 1.1
-Enter your debugger command(s).  Type 'DONE' to end.
-> bt
-> DONE
-
-The "-c" option specifies that the breakpoint command is a set of lldb
-command interpreter commands.  Use "-s" if you want to implement your
-breakpoint command using the Python interface instead.
-
-
-c) Running the program:
-
-Then you can either launch the process with the command:
-
-(lldb) process launch
-
-or its alias:
-
-(lldb) r
-
-Or you can attach to a process by name with:
-
-(lldb) process attach -n Sketch
-
-The "attach by name"  also supports the "-w" option which waits for the
-next process of that name to show up, and attaches to that.  You can also
-attach by PID:
-
-(lldb) process attach -p 12345
-Process 46915 Attaching
-(lldb) Process 46915 Stopped
-1 of 3 threads stopped with reasons:
-* thread #1: tid = 0x2c03, 0x00007fff85cac76a, where = libSystem.B.dylib`__getdirentries64 + 10, stop reason = signal = SIGSTOP, queue = com.apple.main-thread
-
-Note that we tell you that "1 of 3 threads stopped with reasons" and
-then list those threads.  In a multi-threaded environment it is very
-common for more than one thread to hit your breakpoint(s) before the
-kernel actually returns control to the debugger.  In that case, you
-will see all the threads that stopped for some interesting reason
-listed in the stop message.
-
-
-d) Controlling execution:
-
-
-After launching, we can continue until we hit our breakpoint.  The primitive
-commands for process control all exist under the "thread" command:
-
-(lldb) thread continue
-Resuming thread 0x2c03 in process 46915
-Resuming process 46915
-(lldb)
-
-At present you can only operate on one thread at a time, but the
-design will ultimately support saying "step over the function in
-Thread 1, and step into the function in Thread 2, and continue Thread
-3" etc.  When we eventually support keeping some threads running while
-others are stopped this will be particularly important.  For
-convenience, however, all the stepping commands have easy aliases.  
-So "thread continue" is just "c", etc.
-
-The other program stepping commands are pretty much the same as in gdb.  
-You've got:
-
-  1. (lldb) thread step-in
-     The same as gdb's "step" -- there is also the alias "s" in lldb
-
-  2. (lldb) thread step-over
-     The same as gdb's "next" -- there is also the alias "n" in lldb
-
-  3. (lldb) thread step-out
-     The same as gdb's "finish" -- there is also the alias "f" in lldb
-
-And the "by instruction" versions:
-
-(lldb) thread step-inst
-(lldb) thread step-over-inst
-
-Finally, there's:
-
-(lldb) thread until 100
-
-Which runs the thread in the current frame till it reaches line 100 in
-this frame or stops if it leaves the current frame.  This is a pretty 
-close equivalent to gdb's "until" command.
-
-
-One thing here that might be a little disconcerting to gdb users here is that
-when you resume process execution, you immediately get a prompt back.  That's
-because the lldb interpreter remains live when you are running the target.
-This allows you to set a breakpoint, etc without having to explicitly interrupt
-the program you are debugging.  We're still working out all the operations
-that it is safe to do while running.  But this way of operation will set us
-up for "no stop" debugging when we get to implementing that.
-
-If you want to interrupt a running program do:
-
-(lldb) process interrupt
-
-To find out the state of the program, use:
-
-(lldb) process status
-Process 47958 is running.
-
-This is very convenient, but it does have the down-side that debugging
-programs that use stdin is no longer as straightforward.  For now, you
-have to specify another tty to use as the program stdout & stdin using
-the appropriate options to "process launch", or start your program in
-another terminal and catch it with "process attach -w".  We will come
-up with some more convenient way to juggle the terminal back & forth
-over time.
-
-
-e) Examining program state:
-
-Once you've stopped, lldb will choose a current thread, usually the
-one that stopped "for a reason", and a current frame in that thread.
-Many the commands for inspecting state work on this current
-thread/frame.
-
-To inspect the current state of your process, you can start with the
-threads:
-
-(lldb) thread list
-Process 46915 state is Stopped
-* thread #1: tid = 0x2c03, 0x00007fff85cac76a, where = libSystem.B.dylib`__getdirentries64 + 10, stop reason = signal = SIGSTOP, queue = com.apple.main-thread
-  thread #2: tid = 0x2e03, 0x00007fff85cbb08a, where = libSystem.B.dylib`kevent + 10, queue = com.apple.libdispatch-manager
-  thread #3: tid = 0x2f03, 0x00007fff85cbbeaa, where = libSystem.B.dylib`__workq_kernreturn + 10
-
-The * indicates that Thread 1 is the current thread.  To get a
-backtrace for that thread, do:
-
-(lldb) thread backtrace
-thread #1: tid = 0x2c03, stop reason = breakpoint 1.1, queue = com.apple.main-thread
-  frame #0: 0x0000000100010d5b, where = Sketch`-[SKTGraphicView alignLeftEdges:] + 33 at /Projects/Sketch/SKTGraphicView.m:1405
-  frame #1: 0x00007fff8602d152, where = AppKit`-[NSApplication sendAction:to:from:] + 95
-  frame #2: 0x00007fff860516be, where = AppKit`-[NSMenuItem _corePerformAction] + 365
-  frame #3: 0x00007fff86051428, where = AppKit`-[NSCarbonMenuImpl performActionWithHighlightingForItemAtIndex:] + 121
-  frame #4: 0x00007fff860370c1, where = AppKit`-[NSMenu performKeyEquivalent:] + 272
-  frame #5: 0x00007fff86035e69, where = AppKit`-[NSApplication _handleKeyEquivalent:] + 559
-  frame #6: 0x00007fff85f06aa1, where = AppKit`-[NSApplication sendEvent:] + 3630
-  frame #7: 0x00007fff85e9d922, where = AppKit`-[NSApplication run] + 474
-  frame #8: 0x00007fff85e965f8, where = AppKit`NSApplicationMain + 364
-  frame #9: 0x0000000100015ae3, where = Sketch`main + 33 at /Projects/Sketch/SKTMain.m:11
-  frame #10: 0x0000000100000f20, where = Sketch`start + 52
-
-You can also provide a list of threads to backtrace, or the keyword
-"all" to see all threads:
-
-(lldb) thread backtrace all
-
-Next task is inspecting data:
-
-The most convenient way to inspect a frame's arguments and local variables is:
-
-(lldb) frame variable 
-self = (SKTGraphicView *) 0x0000000100208b40
-_cmd = (struct objc_selector *) 0x000000010001bae1
-sender = (id) 0x00000001001264e0
-selection = (NSArray *) 0x00000001001264e0
-i = (NSUInteger) 0x00000001001264e0
-c = (NSUInteger) 0x00000001001253b0
-
-You can also choose particular variables to view:
-
-(lldb) frame variable self
-(SKTGraphicView *) self = 0x0000000100208b40
-
-The frame variable command is not a full expression parser but it
-does support some common operations like dereferencing:
-
-(lldb) fr v *self
-(SKTGraphicView *) self = 0x0000000100208b40
-  (NSView) NSView = {
-    (NSResponder) NSResponder = {
-...
-
-and structure element references:
-
-(lldb) frame variable self.isa
-(struct objc_class *) self.isa = 0x0000000100023730
-
-The frame variable command will also perform "object printing" operations on
-variables (currently we only support NSPrintForDebugger) with:
-
-(lldb) fr v -o self
-(SKTGraphicView *) self = 0x0000000100208b40
-<SKTGraphicView: 0x100208b40>
-
-You can select another frame to view with:
-
-(lldb) frame select 9
-frame #9: 0x0000000100015ae3, where = Sketch`main + 33 at /Projects/Sketch/SKTMain.m:11
-   8      
-   9      
-  10      int main(int argc, const char *argv[]) {
-  11 ->       return NSApplicationMain(argc, argv);
-  12          }
-  13          
-  14          
-
-Another neat trick that the variable list does is array references, so:
-
-(lldb) fr v argv[0]
-(char const *) argv[0] = 0x00007fff5fbffaf8 "/Projects/Sketch/build/Debug/Sketch.app/Contents/MacOS/Sketch"
-
-If you need to view more complex data or change program data, you can
-use the general "expression" command.  It takes an expression and
-evaluates it in the scope of the currently selected frame.  For instance:
-
-(lldb) expr self
-$0 = (SKTGraphicView *) 0x0000000100135430
-(lldb) expr self = 0x00
-$1 = (SKTGraphicView *) 0x0000000000000000
-(lldb) frame var self
-(SKTGraphicView *) self = 0x0000000000000000
-
-You can also call functions:
-
-(lldb) expr (int) printf ("I have a pointer 0x%llx.\n", self)
-$2 = (int) 22
-I have a pointer 0x0.
-
-One thing to note from this example is that lldb commands can be defined to
-take "raw" input.  "expression" is one of these.  So in the expression command,
-you don't have to quote your whole expression, nor backslash protect quotes,
-etc...
-
-Finally, the results of the expressions are stored in persistent variables
-(of the form $[0-9]+) that you can use in further expressions, like:
-
-(lldb) expr self = $0
-$4 = (SKTGraphicView *) 0x0000000100135430
-
-f) Customization:
-
-You can use the embedded Python interpreter to add the following 'pwd' and 'cd' commands
-for your lldb session:
-
-(lldb) script import os
-(lldb) command alias pwd script print os.getcwd()
-(lldb) command regex cd "s/^(.*)$/script os.chdir(os.path.expanduser('%1'))/"
-
-...
-
-(lldb) cd /tmp
-script os.chdir(os.path.expanduser('/tmp'))
-(lldb) pwd
-/private/tmp
-(lldb) 
-
-Or for a more capable 'cd' command, create ~/utils.py like this:
-
-import os
-
-def chdir(debugger, args, result, dict):
-    """Change the working directory, or cd to ${HOME}."""
-    dir = args.strip()
-    if dir:
-        os.chdir(args)
-    else:
-        os.chdir(os.path.expanduser('~'))
-    print "Current working directory: %s" % os.getcwd()
-
-and, have the following in your ~/.lldbinit file:
-
-script import os, sys
-script sys.path.append(os.path.expanduser('~'))
-script import utils
-command alias pwd script print os.getcwd()
-command script add -f utils.chdir cd
-
-and, then in your lldb session, you can have:
-
-(lldb) help cd
-
-Change the working directory, or cd to ${HOME}.
-Syntax: cd
-(lldb) cd
-Current working directory: /Volumes/data/Users/johnny
-(lldb) cd /tmp
-Current working directory: /private/tmp
-(lldb) pwd
-/private/tmp
-(lldb) 
-
-For more examples of customization, look under the ToT/examples/customization
-directory.