HMLLDB

HMLLDB is a collection of LLDB commands to assist in the debugging of iOS apps.
中文介绍

Features

• Non-intrusive. Your iOS project does not need to be modified
• All commands support real devices, and most commands support simulators
• All commands support Objective-C and Swift project
• Some commands provide interactive UI within the APP

Requirements

• Xcode 16.2
• 64-bit simulator or real device, iOS 13.0+
• Some commands require debug configuration (or Optimization Level set [-O0]/[-Onone])

Installation

1. Download all the files. I recommend you to clone the repository.
2. Open (or create) ~/.lldbinit file, and append the following lines to the end of the file:

command script import /path/to/HMLLDB.py

For example, this is the command in my computer:
command script import /Users/pal/Desktop/gitProjects/HMLLDB/commands/HMLLDB.py

3. Restart Xcode, run your own iOS project, click Pause program execution to enter the LLDB debugging mode, enter the command help, if you see the commands described below, the installation is successful.

Note: If you configured a LLDB Init File based on your project Scheme, you may need to add imports to that file.

Commands

| Command | Description | | -------------- | ---------------------- | | autodsym | Add a debug symbol file to the target's modules automatically | | deletefile | Delete the specified file in the sandbox | | pbundlepath | Print the path of the main bundle | | phomedirectory | Print the path of the home directory("~") | | fclass | Find all classes whose names contain the specified string(Case insensitive) | | fsubclass | Find the subclass of the input | | fsuperclass | Find the superclass of the input | | fmethod | Find the specified method in the method list, you can also find the method list of the specified class | | methods | Execute [inputClass _methodDescription] or [inputClass _shortMethodDescription] | | properties | Execute [inputClass _propertyDescription] | | ivars | Execute [instance _ivarDescription] | | ivarsinfo | Show ivars information of class | | bpframe | Set a breakpoint that stops only when the specified stack keyword is matched | | bpmessage | Set a breakpoint for a selector on a class, even if the class itself doesn't override that selector | | bpmethod | Set a breakpoint that stops when the next OC method is called(via objc_msgSend) in the current thread | | cbt | Completely displays the current thread's call stack based on the fp/lr register | | rr | Alias for 'register read' with additional -s/--sp arguments | | twos_complement_to_int | Convert two's complement to a signed value | | reference | Scan the image section to obtain all reference addresses of a certain address | | adrp | Get the execution result of the adrp instruction | | edisassemble | Enhanced disassemble | | tracefunction | Trace functions step by step until the next breakpoint is hit | | traceinstruction | Trace instructions step by step until the next breakpoint is hit | | trace-step-over-instruction | Trace step over instruction | | pfont | Print all font names supported by the device | | plifecycle | Print life cycle of UIViewController | | redirect | Redirect stdout/stderr | | push | Find UINavigationController in keyWindow then push a specified UIViewController | | showhud | Display the debug HUD on the key window. It shows the memory usage, CPU utilization and FPS of the main thread | | sandbox | Present a sandbox browser that can share and delete files | | inspect | Inspect UIView | | request | Print http/https request automatically | | environment | Show diagnostic environment. | | ... | |

All commands in the table can use help <command> to view the syntax and examples. For example, the output of help fmethod:

(lldb) help fmethod
     Find the method.  Expects 'raw' input (see 'help raw-input'.)

Syntax: fmethod

    Syntax:
        fmethod <methodName>  (Case insensitive.)
        fmethod [--class] <className>

    Options:
        --class/-c; Find all method in the class

    Examples:
        (lldb) fmethod viewdid
        (lldb) fmethod viewDidLayoutSubviews
        (lldb) fmethod -c UITableViewController

    This command is implemented in HMClassInfoCommands.py

Example

Some examples use the demo in the Kingfisher project.
It is recommended to click Pause program execution to enter the LLDB debugging mode to execute commands, instead of executing commands by hitting breakpoints.

autodsym

The target symbols add [<symfile>] command needs to specify the address of the symbol, and the autodsym command allows you to omit the parameter.

# The following two commands have the same effect
(lldb) autodsym
(lldb) target symbol add /path/to/dSYM

Notice:
The autodsym command automatically finds the path of the debug symbol file. Xcode needs permission to access the path. The autodsym command does not prompt for authorization.

deletefile

It is recommended to re-run the application after executing the command, because some data is still in the memory.

# Delete all file in the sandbox
(lldb) deletefile -a

# Delete the "~/Documents" directory
(lldb) deletefile -d

# Delete the "~/Library" directory
(lldb) deletefile -l

# Delete the "~/tmp" directory
(lldb) deletefile -t

# Delete the "~/Library/Caches" directory
(lldb) deletefile -c

# Delete the "~Library/Preferences" directory
(lldb) deletefile -p

# Delete the specified file or directory
(lldb) deletefile -f path/to/fileOrDirectory

pbundlepath & phomedirectory

# Print the path of the main bundle
(lldb) pbundlepath
[HMLLDB] /Users/pal/Library/Developer/CoreSimulator/Devices/D90D74C6-DBDF-4976-8BEF-E7BA549F8A89/data/Containers/Bundle/Application/84AE808C-6703-488D-86A2-C90004434D3A/Kingfisher-Demo.app

# Print the path of the home directory
(lldb) phomedirectory
[HMLLDB] /Users/pal/Library/Developer/CoreSimulator/Devices/D90D74C6-DBDF-4976-8BEF-E7BA549F8A89/data/Containers/Data/Application/3F3DF0CD-7B57-4E69-9F15-EB4CCA7C4DD8

# If it is running on the simulator, you can add the -o option to open path with Finder
(lldb) pbundlepath -o
(lldb) phomedirectory -o

fclass & fsubclass & fsuperclass & fmethod

These commands are optimized for Swift, and the namespace can be omitted when entering the Swift class.

fclass: Find all classes whose names contain the specified string(Case insensitive).

Syntax:
	fclass <class_name> [-p <protocol>]
        
(lldb) fclass NormalLoadingViewController
[HMLLDB] Waiting...
[HMLLDB] Count: 1
Kingfisher_Demo.NormalLoadingViewController (0x102148fa8, Kingfisher-Demo)

# Case insensitive
(lldb) fclass image
[HMLLDB] Waiting...
[HMLLDB] Count: 672
Kingfisher.ImageLoadingProgressSideEffect (0x10124ae18, Kingfisher)
Kingfisher.GIFAnimatedImage (0x10124a3e0, Kingfisher)
...
Kingfisher_Demo.DetailImageViewController (0x1009068e8, Kingfisher-Demo)
Kingfisher_Demo.AVAssetImageGeneratorViewController (0x100904568, Kingfisher-Demo)
...
UIImagePickerController (0x1ea918240, UIKitCore)
_UIStackedImageContainerView (0x1ea90fac8, UIKitCore)
...

# Option -p: Display classes that conform to the protocol.
(lldb) fclass controller -p UICollectionViewDelegate
[HMLLDB] Waiting...
[HMLLDB] Count: 16
UIActivityContentViewController (0x224739570, ShareSheet)
UIPrintPreviewViewController (0x225b5f408, PrintKitUI)
UIDebuggingSpecViewController (0x2252cfeb8, UIKitCore)
UIDebuggingInformationHierarchyViewController (0x2252cfc60, UIKitCore)
UICollectionViewController (0x2245d4e50, UIKitCore)
SUIKSearchResultsCollectionViewController (0x2256e82b8, Preferences)
Kingfisher_Demo.InfinityCollectionViewController (0x10079ac18, Kingfisher-Demo)
Kingfisher_Demo.HighResolutionCollectionViewController (0x100799ed0, Kingfisher-Demo)
Kingfisher_Demo.OrientationImagesViewController (0x100799cc8, Kingfisher-Demo)
Kingfisher_Demo.ImageDataProviderCollectionViewController (0x100799bb0, Kingfisher-Demo)
Kingfisher_Demo.IndicatorCollectionViewController (0x100799328, Kingfisher-Demo)
Kingfisher_Demo.ProcessorCollectionViewController (0x100799178, Kingfisher-Demo)
Kingfisher_Demo.NormalLoadingViewController (0x1007989b8, Kingfisher-Demo)
_UISearchSuggestionsListViewController (0x2252dcb40, UIKitCore)
_UIAlertControllerTextFieldViewController (0x2245d13b8, UIKitCore)
UIActivityGroupViewController (0x224739520, ShareSheet)

# Find all classes that conform to the UICollectionViewDelegate protocol
(lldb) fclass -p UICollectionViewDelegate
[HMLLDB] Waiting...
[HMLLDB] Count: 30
...

fsubclass: Find all subclasses of a class.

(lldb) fsubclass UICollectionViewController
[HMLLDB] Waiting...
[HMLLDB] Subclass count: 10 
Kingfisher_Demo.InfinityCollectionViewController (0x102cf2c18, Kingfisher_Demo)
Kingfisher_Demo.HighResolutionCollectionViewController (0x102cf1ed0, Kingfisher_Demo)
...

fsuperclass: Find the super class of a class.

(lldb) fsuperclass UIButton
[HMLLDB] UIButton : UIControl : UIView : UIResponder : NSObject

(lldb) fsuperclass KingfisherManager
[HMLLDB] Kingfisher.KingfisherManager : Swift._SwiftObject

fmethod: Find the specified method in the method list, you can also find the method list of the specified class.

# Find the specified method in the method list. Case insensitive.
(lldb) fmethod clear
[HMLLDB] Waiting...
[HMLLDB] Methods count: 3725 
(-) clearMemoryCache (0x10340c174, Kingfisher)
	Type encoding:v16@0:8
	Class:Kingfisher.ImageCache
(-) _clearAllSpecifiers (0x1c7f1959c, Preferences)
	Type encoding:v16@0:8
	Class:PSSpecifierDataSource
(-) _clearCells (0x2160258c0, ScreenReaderOutput)
	Type encoding:v16@0:8
	Class:SCRO2DBrailleCanvas
...

#