Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/facebook/chisel
Chisel is a collection of LLDB commands to assist debugging iOS apps.
https://github.com/facebook/chisel
Last synced: about 1 month ago
JSON representation
Chisel is a collection of LLDB commands to assist debugging iOS apps.
- Host: GitHub
- URL: https://github.com/facebook/chisel
- Owner: facebook
- License: mit
- Created: 2014-02-21T18:24:17.000Z (over 10 years ago)
- Default Branch: main
- Last Pushed: 2024-03-03T02:20:29.000Z (7 months ago)
- Last Synced: 2024-08-06T18:47:04.707Z (about 2 months ago)
- Language: Python
- Size: 3.38 MB
- Stars: 9,102
- Watchers: 278
- Forks: 803
- Open Issues: 47
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
- awesome-ios - chisel - Collection of LLDB commands to assist debugging iOS apps. (Debugging / Getting Started)
- awesome-reverse-engineering - **8031**星
- awesome-ios-star - chisel - Collection of LLDB commands to assist debugging iOS apps. (Debugging / Getting Started)
- Awesome-iOS - Chisel - Chisel is a collection of LLDB commands to assist debugging iOS apps. (Tools)
- awesome-hacking-lists - facebook/chisel - Chisel is a collection of LLDB commands to assist debugging iOS apps. (Python)
- awesome-security-collection - **8031**星
README
# Chisel
`Chisel` is a collection of `LLDB` commands to assist in the debugging of iOS apps.
[[Installation](#installation) • [Commands](#commands) • [Custom Commands](#custom-commands) • [Development Workflow](#development-workflow) [Contributing](#contributing) • [License](#license)]
For a comprehensive overview of LLDB, and how Chisel complements it, read Ari Grant's [Dancing in the Debugger — A Waltz with LLDB](http://www.objc.io/issue-19/lldb-debugging.html) in issue 19 of [objc.io](http://www.objc.io/).
## Installation
```shell
brew update
brew install chisel
```
if `.lldbinit` file doesn't exist you can create it & open it by tapping on the terminal
```shell
touch .lldbinit
open .lldbinit
```
Then add the following line to your `~/.lldbinit` file.
```Python
# ~/.lldbinit
...
command script import /usr/local/opt/chisel/libexec/fbchisellldb.py
```
* Note that if you are installing on an M1 Mac, the path above should be `/opt/homebrew/opt/chisel/libexec/fbchisellldb.py` instead.
Alternatively, download chisel and add the following line to your _~/.lldbinit_ file.
```Python
# ~/.lldbinit
...
command script import /path/to/fbchisellldb.py
```
The commands will be available the next time `Xcode` starts.
## Commands
There are many commands; here's a few:
*(Compatibility with iOS/Mac indicated at right)*
|Command |Description |iOS |OS X |
|-----------------|----------------|-------|-------|
|pviews |Print the recursive view description for the key window.|Yes|Yes|
|pvc |Print the recursive view controller description for the key window.|Yes|No|
|visualize |Open a `UIImage`, `CGImageRef`, `UIView`, `CALayer`, `NSData` (of an image), `UIColor`, `CIColor`, `CIImage`, `CGColorRef` or `CVPixelBuffer` in Preview.app on your Mac.|Yes|No|
|fv |Find a view in the hierarchy whose class name matches the provided regex.|Yes|No|
|fvc |Find a view controller in the hierarchy whose class name matches the provided regex.|Yes|No|
|show/hide |Show or hide the given view or layer. You don't even have to continue the process to see the changes!|Yes|Yes|
|mask/unmask |Overlay a view or layer with a transparent rectangle to visualize where it is.|Yes|No|
|border/unborder |Add a border to a view or layer to visualize where it is.|Yes|Yes|
|caflush |Flush the render server (equivalent to a "repaint" if no animations are in-flight).|Yes|Yes|
|bmessage |Set a symbolic breakpoint on the method of a class or the method of an instance without worrying which class in the hierarchy actually implements the method.|Yes|Yes|
|wivar |Set a watchpoint on an instance variable of an object.|Yes|Yes|
|presponder |Print the responder chain starting from the given object.|Yes|Yes|
|... |... and many more!|
To see the list of **all** of the commands execute the help command in `LLDB` or go to the [Wiki](https://github.com/facebook/chisel/wiki).
```Python
(lldb) help
The following is a list of built-in, permanent debugger commands:
...
The following is a list of your current user-defined commands:
...
```
The bottom list contains all the commands sourced from `Chisel`.
You can also inspect a specific command by passing its name as an argument to the help command (as with all other `LLDB` commands).
```
(lldb) help border
Draws a border around . Color and width can be optionally provided.
Arguments:
; Type: UIView*; The view to border.
Options:
--color/-c ; Type: string; A color name such as 'red', 'green', 'magenta', etc.
--width/-w ; Type: CGFloat; Desired width of border.
Syntax: border [--color=color] [--width=width]
```
All of the commands provided by `Chisel` come with verbose help. Be sure to read it when in doubt!
## Custom Commands
You can add local, custom commands. Here's a contrived example.
```python
#!/usr/bin/python
# Example file with custom commands, located at /magical/commands/example.py
import lldb
import fbchisellldbbase as fb
def lldbcommands():
return [ PrintKeyWindowLevel() ]
class PrintKeyWindowLevel(fb.FBCommand):
def name(self):
return 'pkeywinlevel'
def description(self):
return 'An incredibly contrived command that prints the window level of the key window.'
def run(self, arguments, options):
# It's a good habit to explicitly cast the type of all return
# values and arguments. LLDB can't always find them on its own.
lldb.debugger.HandleCommand('p (CGFloat)[(id)[(id)[UIApplication sharedApplication] keyWindow] windowLevel]')
```
Then all that's left is to source the commands in lldbinit. `Chisel` has a python function just for this, _loadCommandsInDirectory_ in the _fbobjclldb.py_ module.
```Python
# ~/.lldbinit
...
command script import /path/to/fbobjclldb.py
script fbobjclldb.loadCommandsInDirectory('/magical/commands/')
```
There's also builtin support to make it super easy to specify the arguments and options that a command takes. See the _border_ and _pinvocation_ commands for example use.
## Development Workflow
Developing commands, whether for local use or contributing to `Chisel` directly, both follow the same workflow. Create a command as described in the [Custom Commands](#custom-commands) section and then
1. Start `LLDB`
2. Reach a breakpoint (or simply pause execution via the pause button in `Xcode`'s debug bar or `process interrupt` if attached directly)
3. Execute `command source ~/.lldbinit` in LLDB to source the commands
4. Run the command you are working on
5. Modify the command
6. Optionally run `script reload(modulename)`
7. Repeat steps 3-6 until the command becomes a source of happiness
## Contributing
Please contribute any generic commands that you make. If it helps you then it will likely help many others! :D See `CONTRIBUTING.md` to learn how to contribute.
## License
`Chisel` is MIT-licensed. See `LICENSE`.