diff --git a/docs/source/building-a-cordapp-index.rst b/docs/source/building-a-cordapp-index.rst index 9539ac5b31..925d1cc535 100644 --- a/docs/source/building-a-cordapp-index.rst +++ b/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 diff --git a/docs/source/conf.py b/docs/source/conf.py index e191a60755..0a7b71bede 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -66,6 +66,9 @@ release = 'Master' # The version for use in the dropdown html. html_context = {'version': 'Master'} +# Properties. +kotlin_version = '1.2.51' + # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. # diff --git a/docs/source/debugging-a-cordapp.rst b/docs/source/debugging-a-cordapp.rst new file mode 100644 index 0000000000..a3dab57304 --- /dev/null +++ b/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 `_ 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 `_ 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`. \ No newline at end of file diff --git a/docs/source/getting-set-up.rst b/docs/source/getting-set-up.rst index 09852b645e..d61a6a82f5 100644 --- a/docs/source/getting-set-up.rst +++ b/docs/source/getting-set-up.rst @@ -6,7 +6,7 @@ Software requirements Corda uses industry-standard tools: * **Oracle JDK 8 JVM** - minimum supported version **8u171** -* **IntelliJ IDEA** - supported versions **2017.x** and **2018.x** +* **IntelliJ IDEA** - supported versions **2017.x** and **2018.x** (with Kotlin plugin version |kotlin_version|) * **Git** We also use Gradle and Kotlin, but you do not need to install them. A standalone Gradle wrapper is provided, and it @@ -75,6 +75,7 @@ IntelliJ ^^^^^^^^ 1. Visit https://www.jetbrains.com/idea/download/download-thanks.html?code=IIC 2. Download and run the executable to install IntelliJ Community Edition (use the default settings) +3. Ensure the Kotlin plugin in Intellij is updated to version |kotlin_version| Download a sample project ^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -155,6 +156,7 @@ IntelliJ ^^^^^^^^ 1. Visit https://www.jetbrains.com/idea/download/download-thanks.html?platform=mac&code=IIC 2. Download and run the executable to install IntelliJ Community Edition (use the default settings) +3. Ensure the Kotlin plugin in Intellij is updated to version |kotlin_version| Download a sample project ^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/source/running-a-node.rst b/docs/source/running-a-node.rst index fbd5a97940..ede89bafe2 100644 --- a/docs/source/running-a-node.rst +++ b/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 a node with JMX monitoring enabled ------------------------------------------- diff --git a/docs/source/shell.rst b/docs/source/shell.rst index 42a8e92847..dc07eafb67 100644 --- a/docs/source/shell.rst +++ b/docs/source/shell.rst @@ -314,24 +314,24 @@ Examples Starting a flow ~~~~~~~~~~~~~~~ -We would start the ``CashIssue`` flow as follows: +We would start the ``CashIssueFlow`` flow as follows: ``flow start CashIssueFlow amount: $1000, issuerBankPartyRef: 1234, notary: "O=Controller, L=London, C=GB"`` This breaks down as follows: * ``flow start`` is a shell command for starting a flow -* ``CashIssue`` is the flow we want to start +* ``CashIssueFlow`` is the flow we want to start * Each ``name: value`` pair after that is a flow constructor argument -This command invokes the following ``CashIssue`` constructor: +This command invokes the following ``CashIssueFlow`` constructor: .. container:: codeset .. sourcecode:: kotlin class CashIssueFlow(val amount: Amount, - val issueRef: OpaqueBytes, + val issuerBankPartyRef: OpaqueBytes, val recipient: Party, val notary: Party) : AbstractCashFlow(progressTracker) diff --git a/docs/source/tutorial-cordapp.rst b/docs/source/tutorial-cordapp.rst index eba4a85348..e87aadc607 100644 --- a/docs/source/tutorial-cordapp.rst +++ b/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`.