maxjhandsome
/
llvm-project
forked from OSchip/llvm-project
1
0
Fork 0
Code Issues Pull Requests Packages Releases Wiki Activity
llvm-project/lldb/docs/man/lldb.rst

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

346 lines
8.5 KiB
ReStructuredText
Raw Normal View History

[Docs] Generate the LLDB man page with Sphinx 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. Differential revision: https://reviews.llvm.org/D70514
2019-11-21 06:53:37 +08:00
:orphan:
lldb -- The Debugger
====================
.. program:: lldb
SYNOPSIS
--------
| :program:`lldb` [*options*] *executable*
DESCRIPTION
-----------
[lldb/Docs] Extend description section of the main page The current description is a bit terse. I've copy/pasted the introduction form the website.
2020-01-14 01:28:54 +08:00
:program:`lldb` is a next generation, high-performance debugger. It is built as
a set of reusable components which highly leverage existing libraries in the
larger LLVM Project, such as the Clang expression parser and LLVM disassembler.
:program:`lldb` is the default debugger in Xcode on macOS and supports
debugging C, Objective-C and C++ on the desktop and iOS devices and simulator.
All of the code in the LLDB project is available under the Apache 2.0 License
with LLVM exceptions.
[Docs] Generate the LLDB man page with Sphinx 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. Differential revision: https://reviews.llvm.org/D70514
2019-11-21 06:53:37 +08:00
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
[lldb] fix --source-quietly Jim says: lldb has a -Q or --source-quietly option, which supposedly does: --source-quietly Tells the debugger to execute this one-line lldb command before any file has been loaded. That seems like a weird description, since we don't generally use source for one line entries, but anyway, let's try it: > $LLDB_LLVM/clean-mono/build/Debug/bin/lldb -Q "script print('I should be quiet')" a.out -O "script print('I should be before')" -o "script print('I should be after')" (lldb) script print('I should be before') I should be before (lldb) target create "script print('I should be quiet')" error: unable to find executable for 'script print('I should be quiet')' That was weird. The first real -O gets sourced but not quietly, then the argument to the -Q gets treated as the target. > $LLDB_LLVM/clean-mono/build/Debug/bin/lldb -Q a.out -O "script print('I should be before')" -o "script print('I should be after')" (lldb) script print('I should be before') I should be before (lldb) target create "a.out" Current executable set to '/tmp/a.out' (x86_64). (lldb) script print('I should be after') I should be after Well, that's a little better, but the -Q option seems to have done nothing. --- This fixes the description of --source-quietly, as well as causing it to actually suppress echoing while executing the initialization commands. Reviewed By: jingham Differential Revision: https://reviews.llvm.org/D112988
2021-11-03 02:01:53 +08:00
Tells the debugger not to echo commands while sourcing files or one-line commands provided on the command line.
[Docs] Generate the LLDB man page with Sphinx 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. Differential revision: https://reviews.llvm.org/D70514
2019-11-21 06:53:37 +08:00
.. 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
[lldb] make it easier to find LLDB's python It is surprisingly difficult to write a simple python script that can reliably `import lldb` without failing, or crashing. I'm currently resorting to convolutions like this: def find_lldb(may_reexec=False): if prefix := os.environ.get('LLDB_PYTHON_PREFIX'): if os.path.realpath(prefix) != os.path.realpath(sys.prefix): raise Exception("cannot import lldb.\n" f" sys.prefix should be: {prefix}\n" f" but it is: {sys.prefix}") else: line1, line2 = subprocess.run( ['lldb', '-x', '-b', '-o', 'script print(sys.prefix)'], encoding='utf8', stdout=subprocess.PIPE, check=True).stdout.strip().splitlines() assert line1.strip() == '(lldb) script print(sys.prefix)' prefix = line2.strip() os.environ['LLDB_PYTHON_PREFIX'] = prefix if sys.prefix != prefix: if not may_reexec: raise Exception( "cannot import lldb.\n" + f" This python, at {sys.prefix}\n" f" does not math LLDB's python at {prefix}") os.environ['LLDB_PYTHON_PREFIX'] = prefix python_exe = os.path.join(prefix, 'bin', 'python3') os.execl(python_exe, python_exe, *sys.argv) lldb_path = subprocess.run(['lldb', '-P'], check=True, stdout=subprocess.PIPE, encoding='utf8').stdout.strip() sys.path = [lldb_path] + sys.path This patch aims to replace all that with: #!/usr/bin/env lldb-python import lldb ... ... by adding the following features: * new command line option: --print-script-interpreter-info. This prints language-specific information about the script interpreter in JSON format. * new tool (unix only): lldb-python which finds python and exec's it. Reviewed By: JDevlieghere Differential Revision: https://reviews.llvm.org/D112973
2021-11-11 02:33:33 +08:00
.. option:: --print-script-interpreter-info
Prints out a json dictionary with information about the scripting language interpreter.
[Docs] Generate the LLDB man page with Sphinx 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. Differential revision: https://reviews.llvm.org/D70514
2019-11-21 06:53:37 +08:00
.. 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.
[lldb/Driver] Fix handling on positional arguments Before the transition to libOption it was possible to specify arguments for the inferior without -- as long as they didn't start with a dash. For example, the following invocations should all behave the same: $ lldb inferior inferior-arg $ lldb inferior -- inferior-arg $ lldb -- inferior inferior-arg This patch fixes that behavior, documents it and adds a test to cover the different combinations. Differential revision: https://reviews.llvm.org/D80165
2020-05-19 09:10:53 +08:00
Passing an executable as a positional argument prepares lldb to debug the given
executable. To disambiguate between arguments passed to lldb and arguments
passed to the debugged executable, arguments starting with a - must be passed
after --.
[Docs] Generate the LLDB man page with Sphinx 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. Differential revision: https://reviews.llvm.org/D70514
2019-11-21 06:53:37 +08:00
Fix typo, arvm7 -> armv7
2021-05-05 12:55:36 +08:00
lldb --arch x86_64 /path/to/program program argument -- --arch armv7
[lldb/Driver] Fix handling on positional arguments Before the transition to libOption it was possible to specify arguments for the inferior without -- as long as they didn't start with a dash. For example, the following invocations should all behave the same: $ lldb inferior inferior-arg $ lldb inferior -- inferior-arg $ lldb -- inferior inferior-arg This patch fixes that behavior, documents it and adds a test to cover the different combinations. Differential revision: https://reviews.llvm.org/D80165
2020-05-19 09:10:53 +08:00
For convenience, passing the executable after -- is also supported.
Fix typo, arvm7 -> armv7
2021-05-05 12:55:36 +08:00
lldb --arch x86_64 -- /path/to/program program argument --arch armv7
[Docs] Generate the LLDB man page with Sphinx 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. Differential revision: https://reviews.llvm.org/D70514
2019-11-21 06:53:37 +08:00
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
[Docs] Correct description of lldbinit behavior Jim pointed out that "every time somebody has touched the documentation on startup files they have stated that we source the application one and then the global one, even though in actual fact we’ve never done that." Indeed, when we read the application specific .lldbinit file, the global one is not read. This patch updates the man page to reflect that.
2020-05-29 04:06:44 +08:00
.lldbinit file.
[lldb/interpreter] Add REPL-specific init file This patch adds the infrastructure to have language specific REPL init files. It's the foundation work to a following patch that will introduce Swift REPL init file. When lldb is launched with the `--repl` option, it will look for a REPL init file in the home directory and source it. This overrides the default `~/.lldbinit`, which content might make the REPL behave unexpectedly. If the REPL init file doesn't exists, lldb will fall back to the default init file. rdar://65836048 Differential Revision: https://reviews.llvm.org/D86242 Signed-off-by: Med Ismail Bennani <medismail.bennani@gmail.com>
2020-08-20 04:04:35 +08:00
First, :program:`lldb` will try to read the application specific init file
whose name is ~/.lldbinit followed by a "-" and the name of the current
program. This would be ~/.lldbinit-lldb for the command line :program:`lldb`
and ~/.lldbinit-Xcode for Xcode. If there is no application specific init
file, :program:`lldb` will look for an init file in the home directory.
If launched with a `REPL`_ option, it will first look for a REPL configuration
[lldb/interpreter] Improve REPL init file compatibility This patch changes the command interpreter sourcing logic for the REPL init file. Instead of looking for a arbitrary file name, it standardizes the REPL init file name to match to following scheme: `.lldbinit-<language>-repl` This will make the naming more homogenous and the sourcing logic future-proof. rdar://65836048 Differential Revision: https://reviews.llvm.org/D86987 Signed-off-by: Med Ismail Bennani <medismail.bennani@gmail.com>
2020-09-02 06:47:16 +08:00
file, specific to the REPL language. The init file should be named as follow:
[lldb][docs] Use inline literals for code/paths instead of rendering it with the default role Right now we're using the 'content' role as default which will just render these things as cursive (which isn't really useful for code examples). It also prevents us from assigning a more useful default role in the future.
2021-01-18 18:07:26 +08:00
``.lldbinit-<language>-repl`` (i.e. ``.lldbinit-swift-repl``). If this file doesn't
[lldb/interpreter] Improve REPL init file compatibility This patch changes the command interpreter sourcing logic for the REPL init file. Instead of looking for a arbitrary file name, it standardizes the REPL init file name to match to following scheme: `.lldbinit-<language>-repl` This will make the naming more homogenous and the sourcing logic future-proof. rdar://65836048 Differential Revision: https://reviews.llvm.org/D86987 Signed-off-by: Med Ismail Bennani <medismail.bennani@gmail.com>
2020-09-02 06:47:16 +08:00
exist, or :program:`lldb` wasn't launch with `REPL`_, meaning there is neither
[lldb][docs] Use inline literals for code/paths instead of rendering it with the default role Right now we're using the 'content' role as default which will just render these things as cursive (which isn't really useful for code examples). It also prevents us from assigning a more useful default role in the future.
2021-01-18 18:07:26 +08:00
a REPL init file nor an application specific init file, ``lldb`` will fallback to
[lldb/interpreter] Improve REPL init file compatibility This patch changes the command interpreter sourcing logic for the REPL init file. Instead of looking for a arbitrary file name, it standardizes the REPL init file name to match to following scheme: `.lldbinit-<language>-repl` This will make the naming more homogenous and the sourcing logic future-proof. rdar://65836048 Differential Revision: https://reviews.llvm.org/D86987 Signed-off-by: Med Ismail Bennani <medismail.bennani@gmail.com>
2020-09-02 06:47:16 +08:00
the global ~/.lldbinit.
[Docs] Correct description of lldbinit behavior Jim pointed out that "every time somebody has touched the documentation on startup files they have stated that we source the application one and then the global one, even though in actual fact we’ve never done that." Indeed, when we read the application specific .lldbinit file, the global one is not read. This patch updates the man page to reflect that.
2020-05-29 04:06:44 +08:00
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
[Docs] Generate the LLDB man page with Sphinx 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. Differential revision: https://reviews.llvm.org/D70514
2019-11-21 06:53:37 +08:00
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.