From ec2bbbe7064c01b2279eb5869302d10b90b4f448 Mon Sep 17 00:00:00 2001
From: Scott Weiss <sdw35@cornell.edu>
Date: Wed, 29 Mar 2017 18:05:50 -0400
Subject: [PATCH] add doc for debugging

---
 README.md                    |  1 +
 developer_setup/debugging.md | 54 ++++++++++++++++++++++++++++++++++++
 2 files changed, 55 insertions(+)
 create mode 100644 developer_setup/debugging.md

diff --git a/README.md b/README.md
index b166c078..1dd25999 100644
--- a/README.md
+++ b/README.md
@@ -10,6 +10,7 @@
     - [Amazon AWS](providers/amazon_aws_config.md)
     - [Hawkular](providers/hawkular.md)
     - [Openstack Infra](providers/openstack_infra_provider.md)
+  - [Interactive debugging with Pry-Remote](developer_setup/debugging.md)
 * [Development Appliance Setup](https://github.com/ManageIQ/manageiq-appliance-dev-setup)
 * [Developer Copr setup for CentOS6](developer_copr_setup_centos6.md)
 * [Internationalization Guidelines](i18n.md)
diff --git a/developer_setup/debugging.md b/developer_setup/debugging.md
new file mode 100644
index 00000000..e25bad78
--- /dev/null
+++ b/developer_setup/debugging.md
@@ -0,0 +1,54 @@
+## Debugging ManageIQ with Remote Pry
+
+Interactive debugging using pry or byebug is normally difficult with ManageIQ, as `rake evm:start` launches the server and worker processes in the background. Therefore the only way to do interactive debugging is with `pry-remote` or `byebug` running in remote mode.
+
+Running ManageIQ with `byebug` was exceedingly slow, so this guide will focus on remote debugging using `pry`.
+
+### Adding dependencies
+
+You'll need to add the following gems to your dev overrides file in `bundler.d/`:
+
+```ruby
+  gem 'pry'
+  gem 'pry-remote'
+  gem 'pry-nav'
+```
+
+### Starting the debugger
+
+Setting a breakpoint with `pry` requires adding the following line somewhere in your code:
+
+```ruby
+#code executes until this line
+binding.remote_pry
+#code here does not execute
+```
+
+When execution reaches the `remote_pry` call, the line  `pry-remote] Waiting for client on drb://localhost:9876` will print to STDOUT (stderr?) and execution will block until you connect the client debug process.
+
+To connect the debugger, simply run from the ManageIQ root dir:
+```
+bundle exec pry-remote
+```
+which will attempt to connect to the pry server on port 9876.
+
+With the addition of `pry-nav`, you'll have access to commands `continue`, `step`, and `next`, to navigate through your code.
+
+### Notes
+
+Setting breakpoints from within pry is currently not possible with `pry-nav`. As a workaround, it's possible to set conditional breakpoints throughout your code like so:
+
+```ruby
+
+binding.remote_pry
+
+# do some stuff
+
+if @breakpoint_enabled
+  binding.remote_pry
+end
+```
+
+And simply set `@breakpoint_enabled = true` when you reach your first breakpoint to enable the next breakpoint to trigger.
+
+Note that you will have to `continue` to exit out of `pry` and then `bundle exec pry-remote` again to enter into subsequent breakpoints in the same process.