Consolidates and extends debugging information. (#3548)

* Consolidates and extends debugging information.

* Clearer remote debugging instructions.

docs/source/building-a-cordapp-index.rst

@@ -6,6 +6,7 @@ CorDapps
 
    cordapp-overview
    writing-a-cordapp
+   debugging-a-cordapp
    upgrade-notes
    upgrading-cordapps
    cordapp-build-systems

docs/source/debugging-a-cordapp.rst

@@ -0,0 +1,73 @@
+Debugging a CorDapp
+===================
+
+.. contents::
+
+There are several ways to debug your CorDapp.
+
+Using a ``MockNetwork``
+-----------------------
+
+You can attach the `IntelliJ IDEA debugger <https://www.jetbrains.com/help/idea/debugging-code.html>`_ to a
+``MockNetwork`` to debug your CorDapp:
+
+* Define your flow tests as per :doc:`api-testing`
+
+    * In your ``MockNetwork``, ensure that ``threadPerNode`` is set to ``false``
+
+* Set your breakpoints
+* Run the flow tests using the debugger. When the tests hit a breakpoint, execution will pause
+
+Using the node driver
+---------------------
+
+You can also attach the `IntelliJ IDEA debugger <https://www.jetbrains.com/help/idea/debugging-code.html>`_ to nodes
+running via the node driver to debug your CorDapp.
+
+With the nodes in-process
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+1. Define a network using the node driver as per :doc:`tutorial-integration-testing`
+
+    * In your ``DriverParameters``, ensure that ``startNodesInProcess`` is set to ``true``
+
+2. Run the driver using the debugger
+
+3. Set your breakpoints
+
+4. Interact with your nodes. When execution hits a breakpoint, execution will pause
+
+    * The nodes' webservers always run in a separate process, and cannot be attached to by the debugger
+
+With remote debugging
+^^^^^^^^^^^^^^^^^^^^^
+
+1. Define a network using the node driver as per :doc:`tutorial-integration-testing`
+
+    * In your ``DriverParameters``, ensure that ``startNodesInProcess`` is set to ``false`` and ``isDebug`` is set to
+      ``true``
+
+2. Run the driver. The remote debug ports for each node will be automatically generated and printed to the terminal.
+   For example:
+
+.. sourcecode:: none
+
+    [INFO ] 11:39:55,471 [driver-pool-thread-0] (DriverDSLImpl.kt:814) internal.DriverDSLImpl.startOutOfProcessNode -
+        Starting out-of-process Node PartyA, debug port is 5008, jolokia monitoring port is not enabled {}
+
+3. Attach the debugger to the node of interest on its debug port:
+
+    * In IntelliJ IDEA, create a new run/debug configuration of type ``Remote``
+    * Set the run/debug configuration's ``Port`` to the debug port
+    * Start the run/debug configuration in debug mode
+
+4. Set your breakpoints
+
+5. Interact with your node. When execution hits a breakpoint, execution will pause
+
+    * The nodes' webservers always run in a separate process, and cannot be attached to by the debugger
+
+By enabling remote debugging on a node
+--------------------------------------
+
+See :ref:`enabling-remote-debugging`.

docs/source/running-a-node.rst

@@ -64,13 +64,15 @@ The node can optionally be started with the following command-line options:
 * ``--sshd``: Enables SSHD server for node administration
 * ``--version``: Print the version and exit
 
+.. _enabling-remote-debugging:
+
 Enabling remote debugging
 ~~~~~~~~~~~~~~~~~~~~~~~~~
-To enable remote debugging of the node, run the following from the terminal window:
+To enable remote debugging of the node, run the node with the following JVM arguments:
 
 ``java -Dcapsule.jvm.args="-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=5005" -jar corda.jar``
 
-This command line will start the debugger on port 5005 and pause the process awaiting debugger attachment.
+This will allow you to attach a debugger to your node on port 5005.
 
 Starting all nodes at once on a local machine from the command line
 -------------------------------------------------------------------

docs/source/tutorial-cordapp.rst

@@ -444,44 +444,24 @@ The nodes can be configured to communicate as a network even when distributed ac
    value after the nodes have been moved to their individual machines. The initial bootstrapping process requires access to the 
    nodes' databases and if two nodes share the same H2 port, the process will fail.
 
-Testing and debugging
----------------------
+Testing your CorDapp
+--------------------
 
-Testing a CorDapp
-~~~~~~~~~~~~~~~~~
 Corda provides several frameworks for writing unit and integration tests for CorDapps.
 
 Contract tests
-^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~
 You can run the CorDapp's contract tests by running the ``Run Contract Tests - Kotlin`` run configuration.
 
 Flow tests
-^^^^^^^^^^
+~~~~~~~~~~
 You can run the CorDapp's flow tests by running the ``Run Flow Tests - Kotlin`` run configuration.
 
 Integration tests
-^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~
 You can run the CorDapp's integration tests by running the ``Run Integration Tests - Kotlin`` run configuration.
 
-Debugging Corda nodes
-~~~~~~~~~~~~~~~~~~~~~
-Debugging is done via IntelliJ as follows:
+Debugging your CorDapp
+----------------------
 
-1. Start the nodes using the “Run Example CorDapp” run configuration in IntelliJ
-
-2. IntelliJ will build and run the CorDapp. The remote debug ports for each node will be automatically generated and
-   printed to the terminal. For example:
-
-.. sourcecode:: none
-
-    [INFO ] 15:27:59.533 [main] Node.logStartupInfo - Working Directory: /Users/joeldudley/cordapp-example/build/20170707142746/PartyA
-    [INFO ] 15:27:59.533 [main] Node.logStartupInfo - Debug port: dt_socket:5007
-
-3. Edit the “Debug CorDapp” run configuration with the port of the node you wish to connect to
-
-4. Run the “Debug CorDapp” run configuration
-
-5. Set your breakpoints and interact with the node you've connected to. When the node hits a breakpoint, execution will
-   pause
-
-   * The node webserver runs in a separate process, and is not attached to by the debugger
+See :doc:`debugging-a-cordapp`.