[Lldb-commits] [lldb] 1441ffe - [lldb] Use __lldb_init_module instead of "if lldb.debugger" idiom
Dave Lee via lldb-commits
lldb-commits at lists.llvm.org
Thu Jan 13 16:37:58 PST 2022
Author: Dave Lee
Date: 2022-01-13T16:37:49-08:00
New Revision: 1441ffe6a6da90e9c4800914eb0005b1087aa5d2
URL: https://github.com/llvm/llvm-project/commit/1441ffe6a6da90e9c4800914eb0005b1087aa5d2
DIFF: https://github.com/llvm/llvm-project/commit/1441ffe6a6da90e9c4800914eb0005b1087aa5d2.diff
LOG: [lldb] Use __lldb_init_module instead of "if lldb.debugger" idiom
Update examples and docs to demonstrate using `__lldb_init_module` instead of
the idiom that checks for `lldb.debugger` at the top-level.
```
if __name__ == '__main__':
...
elif lldb.debugger:
...
```
Is replaced with:
```
if __name__ == '__main__':
...
def __lldb_init_module(debugger, internal_dict):
...
```
This change is for two reasons. First, it's generally encouraged not to only
use the convenience singletons (`lldb.{debugger,process,target,etc}`)
interactively from the `script` command. Second, there's a bug where
registering a python class as a command (using `command script add -c ...`),
result in the command not being runnable. Note that registering function-backed
commands does not have this bug.
Differential Revision: https://reviews.llvm.org/D117237
Added:
Modified:
lldb/docs/use/python-reference.rst
lldb/examples/darwin/heap_find/heap.py
lldb/examples/python/delta.py
lldb/examples/python/diagnose_unwind.py
lldb/examples/python/gdb_disassemble.py
lldb/examples/python/gdbremote.py
lldb/examples/python/jump.py
lldb/examples/python/memory.py
lldb/examples/python/stacks.py
lldb/examples/python/types.py
Removed:
################################################################################
diff --git a/lldb/docs/use/python-reference.rst b/lldb/docs/use/python-reference.rst
index d5ab09cbf7c22..e1e2f61eb5fec 100644
--- a/lldb/docs/use/python-reference.rst
+++ b/lldb/docs/use/python-reference.rst
@@ -584,26 +584,33 @@ the form:
where debugger and internal_dict are as above, that function will get run when
the module is loaded allowing you to add whatever commands you want into the
current debugger. Note that this function will only be run when using the LLDB
-command command script import, it will not get run if anyone imports your
-module from another module. If you want to always run code when your module is
-loaded from LLDB or when loaded via an import statement in python code you can
-test the lldb.debugger object, since you imported the module at the top of the
-python ls.py module. This test must be in code that isn't contained inside of
-any function or class, just like the standard test for __main__ like all python
-modules usually do. Sample code would look like:
+command ``command script import``, it will not get run if anyone imports your
+module from another module.
+
+The standard test for ``__main__``, like many python modules do, is useful for
+creating scripts that can be run from the command line. However, for command
+line scripts, the debugger instance must be created manually. Sample code would
+look like:
::
if __name__ == '__main__':
+ # Initialize the debugger before making any API calls.
+ lldb.SBDebugger.Initialize()
# Create a new debugger instance in your module if your module
# can be run from the command line. When we run a script from
# the command line, we won't have any debugger object in
# lldb.debugger, so we can just create it if it will be needed
- lldb.debugger = lldb.SBDebugger.Create()
- elif lldb.debugger:
- # Module is being run inside the LLDB interpreter
- lldb.debugger.HandleCommand('command script add -f ls.ls ls')
- print 'The "ls" python command has been installed and is ready for use.'
+ debugger = lldb.SBDebugger.Create()
+
+ # Next, do whatever work this module should do when run as a command.
+ # ...
+
+ # Finally, dispose of the debugger you just made.
+ lldb.SBDebugger.Destroy(debugger)
+ # Terminate the debug sesssion
+ lldb.SBDebugger.Terminate()
+
Now we can create a module called ls.py in the file ~/ls.py that will implement
a function that can be used by LLDB's python command code:
@@ -673,7 +680,7 @@ that goal:
Python Interactive Interpreter. To exit, type 'quit()', 'exit()' or Ctrl-D.
>>> def pofoo_funct(debugger, command, result, internal_dict):
... cmd = "po [ModifyString(" + command + ") capitalizedString]"
- ... lldb.debugger.HandleCommand(cmd)
+ ... debugger.HandleCommand(cmd)
...
>>> ^D
(lldb) command script add pofoo -f pofoo_funct
diff --git a/lldb/examples/darwin/heap_find/heap.py b/lldb/examples/darwin/heap_find/heap.py
index 75cb9225e72d6..b04f69008b68e 100644
--- a/lldb/examples/darwin/heap_find/heap.py
+++ b/lldb/examples/darwin/heap_find/heap.py
@@ -1494,30 +1494,29 @@ def objc_refs(debugger, command, result, dict):
if __name__ == '__main__':
lldb.debugger = lldb.SBDebugger.Create()
-# Make the options so we can generate the help text for the new LLDB
-# command line command prior to registering it with LLDB below. This way
-# if clients in LLDB type "help malloc_info", they will see the exact same
-# output as typing "malloc_info --help".
-ptr_refs.__doc__ = get_ptr_refs_options().format_help()
-cstr_refs.__doc__ = get_cstr_refs_options().format_help()
-malloc_info.__doc__ = get_malloc_info_options().format_help()
-objc_refs.__doc__ = get_objc_refs_options().format_help()
-lldb.debugger.HandleCommand(
- 'command script add -f %s.ptr_refs ptr_refs' %
- __name__)
-lldb.debugger.HandleCommand(
- 'command script add -f %s.cstr_refs cstr_refs' %
- __name__)
-lldb.debugger.HandleCommand(
- 'command script add -f %s.malloc_info malloc_info' %
- __name__)
-lldb.debugger.HandleCommand(
- 'command script add -f %s.find_variable find_variable' %
- __name__)
-# lldb.debugger.HandleCommand('command script add -f %s.heap heap' % package_name)
-# lldb.debugger.HandleCommand('command script add -f %s.section_ptr_refs section_ptr_refs' % package_name)
-# lldb.debugger.HandleCommand('command script add -f %s.stack_ptr_refs stack_ptr_refs' % package_name)
-lldb.debugger.HandleCommand(
- 'command script add -f %s.objc_refs objc_refs' %
- __name__)
-print('"malloc_info", "ptr_refs", "cstr_refs", "find_variable", and "objc_refs" commands have been installed, use the "--help" options on these commands for detailed help.')
+def __lldb_init_module(debugger, internal_dict):
+ # Make the options so we can generate the help text for the new LLDB
+ # command line command prior to registering it with LLDB below. This way
+ # if clients in LLDB type "help malloc_info", they will see the exact same
+ # output as typing "malloc_info --help".
+ ptr_refs.__doc__ = get_ptr_refs_options().format_help()
+ cstr_refs.__doc__ = get_cstr_refs_options().format_help()
+ malloc_info.__doc__ = get_malloc_info_options().format_help()
+ objc_refs.__doc__ = get_objc_refs_options().format_help()
+ debugger.HandleCommand(
+ 'command script add -f %s.ptr_refs ptr_refs' %
+ __name__)
+ debugger.HandleCommand(
+ 'command script add -f %s.cstr_refs cstr_refs' %
+ __name__)
+ debugger.HandleCommand(
+ 'command script add -f %s.malloc_info malloc_info' %
+ __name__)
+ debugger.HandleCommand(
+ 'command script add -f %s.find_variable find_variable' %
+ __name__)
+ # debugger.HandleCommand('command script add -f %s.section_ptr_refs section_ptr_refs' % package_name)
+ debugger.HandleCommand(
+ 'command script add -f %s.objc_refs objc_refs' %
+ __name__)
+ print('"malloc_info", "ptr_refs", "cstr_refs", "find_variable", and "objc_refs" commands have been installed, use the "--help" options on these commands for detailed help.')
diff --git a/lldb/examples/python/delta.py b/lldb/examples/python/delta.py
index 0176fb0b3345f..3f14fb1e152b9 100755
--- a/lldb/examples/python/delta.py
+++ b/lldb/examples/python/delta.py
@@ -125,11 +125,10 @@ def parse_log_file(file, options):
import sys
parse_time_log_args(sys.argv[1:])
-else:
- import lldb
- if lldb.debugger:
+
+def __lldb_init_module(debugger, internal_dict):
# This initializer is being run from LLDB in the embedded command interpreter
# Add any commands contained in this module to LLDB
- lldb.debugger.HandleCommand(
+ debugger.HandleCommand(
'command script add -f delta.parse_time_log parse_time_log')
print('The "parse_time_log" command is now installed and ready for use, type "parse_time_log --help" for more information')
diff --git a/lldb/examples/python/diagnose_unwind.py b/lldb/examples/python/diagnose_unwind.py
index db3ff1952f335..bd6976de4a3df 100644
--- a/lldb/examples/python/diagnose_unwind.py
+++ b/lldb/examples/python/diagnose_unwind.py
@@ -308,7 +308,8 @@ def create_diagnose_unwind_options():
usage=usage)
return parser
-lldb.debugger.HandleCommand(
- 'command script add -f %s.diagnose_unwind diagnose-unwind' %
- __name__)
-print('The "diagnose-unwind" command has been installed, type "help diagnose-unwind" for detailed help.')
+def __lldb_init_module(debugger, internal_dict):
+ debugger.HandleCommand(
+ 'command script add -f %s.diagnose_unwind diagnose-unwind' %
+ __name__)
+ print('The "diagnose-unwind" command has been installed, type "help diagnose-unwind" for detailed help.')
diff --git a/lldb/examples/python/gdb_disassemble.py b/lldb/examples/python/gdb_disassemble.py
index 65983e2e993e2..08d1ef5611070 100755
--- a/lldb/examples/python/gdb_disassemble.py
+++ b/lldb/examples/python/gdb_disassemble.py
@@ -21,6 +21,7 @@ def disassemble(debugger, command, result, dict):
print("<%s + %-4u> 0x%x %8s %s" % (name, inst_offset, inst_addr, inst.mnemonic, inst.operands))
# Install the command when the module gets imported
-lldb.debugger.HandleCommand(
- 'command script add -f gdb_disassemble.disassemble gdb-disassemble')
-print('Installed "gdb-disassemble" command for disassembly')
+def __lldb_init_module(debugger, internal_dict):
+ debugger.HandleCommand(
+ 'command script add -f gdb_disassemble.disassemble gdb-disassemble')
+ print('Installed "gdb-disassemble" command for disassembly')
diff --git a/lldb/examples/python/gdbremote.py b/lldb/examples/python/gdbremote.py
index 804977259de77..3045bb0170886 100755
--- a/lldb/examples/python/gdbremote.py
+++ b/lldb/examples/python/gdbremote.py
@@ -1619,13 +1619,11 @@ def parse_gdb_log(file, options):
else:
parse_gdb_log(sys.stdin, options)
-else:
- import lldb
- if lldb.debugger:
- # This initializer is being run from LLDB in the embedded command interpreter
- # Add any commands contained in this module to LLDB
- lldb.debugger.HandleCommand(
- 'command script add -f gdbremote.start_gdb_log start_gdb_log')
- lldb.debugger.HandleCommand(
- 'command script add -f gdbremote.stop_gdb_log stop_gdb_log')
- print('The "start_gdb_log" and "stop_gdb_log" commands are now installed and ready for use, type "start_gdb_log --help" or "stop_gdb_log --help" for more information')
+def __lldb_init_module(debugger, internal_dict):
+ # This initializer is being run from LLDB in the embedded command interpreter
+ # Add any commands contained in this module to LLDB
+ debugger.HandleCommand(
+ 'command script add -f gdbremote.start_gdb_log start_gdb_log')
+ debugger.HandleCommand(
+ 'command script add -f gdbremote.stop_gdb_log stop_gdb_log')
+ print('The "start_gdb_log" and "stop_gdb_log" commands are now installed and ready for use, type "start_gdb_log --help" or "stop_gdb_log --help" for more information')
diff --git a/lldb/examples/python/jump.py b/lldb/examples/python/jump.py
index dc4cc48b14447..d7fd03e533890 100644
--- a/lldb/examples/python/jump.py
+++ b/lldb/examples/python/jump.py
@@ -191,8 +191,8 @@ def jump(debugger, command, result, internal_dict):
frame.SetPC(desired_address.GetLoadAddress(target))
-if lldb.debugger:
+def __lldb_init_module(debugger, internal_dict):
# Module is being run inside the LLDB interpreter
jump.__doc__ = usage_string()
- lldb.debugger.HandleCommand('command script add -f jump.jump jump')
+ debugger.HandleCommand('command script add -f jump.jump jump')
print('The "jump" command has been installed, type "help jump" or "jump <ENTER>" for detailed help.')
diff --git a/lldb/examples/python/memory.py b/lldb/examples/python/memory.py
index 26703462c2cde..aa5df0178e91b 100755
--- a/lldb/examples/python/memory.py
+++ b/lldb/examples/python/memory.py
@@ -270,8 +270,9 @@ def memfind(target, options, args, result):
if __name__ == '__main__':
print('error: this script is designed to be used within the embedded script interpreter in LLDB')
-elif getattr(lldb, 'debugger', None):
+
+def __lldb_init_module(debugger, internal_dict):
memfind_command.__doc__ = create_memfind_options().format_help()
- lldb.debugger.HandleCommand(
+ debugger.HandleCommand(
'command script add -f memory.memfind_command memfind')
print('"memfind" command installed, use the "--help" option for detailed help')
diff --git a/lldb/examples/python/stacks.py b/lldb/examples/python/stacks.py
index 41729ec67443f..5b0a877b30668 100755
--- a/lldb/examples/python/stacks.py
+++ b/lldb/examples/python/stacks.py
@@ -63,6 +63,7 @@ def stack_frames(debugger, command, result, dict):
print(frame_info)
-lldb.debugger.HandleCommand(
- "command script add -f stacks.stack_frames stack_frames")
-print("A new command called 'stack_frames' was added, type 'stack_frames --help' for more information.")
+def __lldb_init_module(debugger, internal_dict):
+ debugger.HandleCommand(
+ "command script add -f stacks.stack_frames stack_frames")
+ print("A new command called 'stack_frames' was added, type 'stack_frames --help' for more information.")
diff --git a/lldb/examples/python/types.py b/lldb/examples/python/types.py
index 513a03b2600ad..024348cdaa3a3 100755
--- a/lldb/examples/python/types.py
+++ b/lldb/examples/python/types.py
@@ -351,7 +351,7 @@ def verify_types(target, options):
continue
verify_types(target, options)
-elif getattr(lldb, 'debugger', None):
- lldb.debugger.HandleCommand(
+def __lldb_init_module(debugger, internal_dict):
+ debugger.HandleCommand(
'command script add -f types.check_padding_command check_padding')
print('"check_padding" command installed, use the "--help" option for detailed help')
More information about the lldb-commits
mailing list