README.md 3.89 KB
Newer Older
1
# pry-debugger-jruby
2

Ivo Anjo's avatar
Ivo Anjo committed
3 4
[![Gem Version](https://badge.fury.io/rb/pry-debugger-jruby.svg)](https://badge.fury.io/rb/pry-debugger-jruby)

Ivo Anjo's avatar
Ivo Anjo committed
5
_JRuby 9k-compatible pry debugging!_
6

7 8
Requires JRuby >= 9.1.3.0.

9
Using MRI? I strongly recommend [`pry-byebug`](https://github.com/deivid-rodriguez/pry-byebug) instead!
Gopal Patel's avatar
Gopal Patel committed
10

11
Adds `step`, `next`, `finish`, and `continue` commands and `breakpoints` to [Pry](http://pry.github.com).
Gopal Patel's avatar
Gopal Patel committed
12

Ivo Anjo's avatar
Ivo Anjo committed
13
To use, run JRuby with the `--debug` flag, and then invoke `pry` normally:
Gopal Patel's avatar
Gopal Patel committed
14 15 16 17

```ruby
def some_method
  binding.pry          # Execution will stop here.
Ivo Anjo's avatar
Ivo Anjo committed
18
  puts 'Hello, World!' # Run 'step' or 'next' in the console to move here.
Gopal Patel's avatar
Gopal Patel committed
19 20 21
end
```

Ivo Anjo's avatar
Ivo Anjo committed
22
You can also add the `--debug` flag to your `JRUBY_OPTS` environment variable, so it will be picked up by any ruby application. Do note that running `JRuby` in debug mode **does** have a noticeable impact on performance.
23 24

## Execution Commands
25

Ivo Anjo's avatar
Ivo Anjo committed
26
* `step`: Step execution into the next line or method. Takes an optional numeric argument to step multiple times.
27

Ivo Anjo's avatar
Ivo Anjo committed
28
* `next`: Step over to the next line within the same frame. Also takes an optional numeric argument to step multiple lines.
29

Ivo Anjo's avatar
Ivo Anjo committed
30
* `finish`: Execute until current stack frame returns.
31

Ivo Anjo's avatar
Ivo Anjo committed
32
* `continue`: Continue program execution and end the Pry session.
33 34 35

## Breakpoints

Ivo Anjo's avatar
Ivo Anjo committed
36
You can set and adjust breakpoints directly from a Pry session using the following commands:
37

38
* `break`: Set a new breakpoint from a line number in the current file, a file and line number, or a method. Pass an optional expression to create a conditional breakpoint. Edit existing breakpoints via various flags. Type `break --help` from a Pry session to see all available options.
39

Ivo Anjo's avatar
Ivo Anjo committed
40
    Examples:
Ivo Anjo's avatar
Ivo Anjo committed
41

42
```ruby
43 44 45 46 47
break SomeClass#run            Break at the start of `SomeClass#run`.
break Foo#bar if baz?          Break at `Foo#bar` only if `baz?`.
break app/models/user.rb:15    Break at line 15 in user.rb.
break 14                       Break at line 14 in the current file.

48
break --condition 4 x > 2      Change condition on breakpoint #4 to 'x > 2'.
49 50 51 52
break --condition 3            Remove the condition on breakpoint #3.

break --delete 5               Delete breakpoint #5.
break --disable-all            Disable all breakpoints.
53 54 55

break                          List all breakpoints. (Same as `breakpoints`)
break --show 2                 Show details about breakpoint #2.
56
```
57

Ivo Anjo's avatar
Ivo Anjo committed
58
* `breakpoints`: List all defined breakpoints. Pass `-v` or `--verbose` to see the source code around each breakpoint.
59 60 61

## Remote debugging

62
Support for [pry-remote](https://github.com/Mon-Ouie/pry-remote) is also included. Requires explicity requiring `pry-debugger-jruby`, not just relying on pry's plugin loader.
63

Ivo Anjo's avatar
Ivo Anjo committed
64
Want to debug a Rails app running inside `foreman`? Add to your `Gemfile`:
65 66 67

```ruby
gem 'pry'
68
gem 'pry-remote'
69
gem 'pry-debugger-jruby'
70 71
```

72 73 74
Then add `binding.remote_pry` where you want to pause:

```ruby
Ivo Anjo's avatar
Ivo Anjo committed
75 76
require 'pry-remote'

77 78 79
class UsersController < ApplicationController
  def index
    binding.remote_pry
Ivo Anjo's avatar
Ivo Anjo committed
80
    # ...
81 82 83 84 85 86
  end
end
```

Load a page that triggers the code. Connect to the session:

Ivo Anjo's avatar
Ivo Anjo committed
87
```bash
88 89 90 91 92
$ bundle exec pry-remote
```

## Tips

Gopal Patel's avatar
Gopal Patel committed
93 94 95
Stepping through code often? Add the following shortcuts to `~/.pryrc`:

```ruby
96
if defined?(PryDebuggerJRuby)
97 98 99 100 101
  Pry.commands.alias_command 'c', 'continue'
  Pry.commands.alias_command 's', 'step'
  Pry.commands.alias_command 'n', 'next'
  Pry.commands.alias_command 'f', 'finish'
end
Gopal Patel's avatar
Gopal Patel committed
102 103
```

Gopal Patel's avatar
Gopal Patel committed
104 105
## Contributors

106
`pry-debugger-jruby` is maintained by [Ivo Anjo](https://ivoanjo.me) and is based off the awesome previous work from the [`pry-debugger`](https://github.com/nixme/pry-debugger) creators:
107

108 109 110 111 112
* [Gopal Patel](https://github.com/nixme)
* [John Mair](https://github.com/banister)
* [Nicolas Viennot](https://github.com/nviennot)
* [Benjamin R. Haskell](https://github.com/benizi)
* [Joshua Hou](https://github.com/jshou)
113 114 115
* ...and others who helped with [`pry-nav`](https://github.com/nixme/pry-nav)

Patches and bug reports are welcome. Just send in a pull request or issue :)