2017-11-16 15:31:52 +00:00
|
|
|
Building a CorDapp
|
|
|
|
==================
|
2017-07-25 16:54:36 +00:00
|
|
|
|
2017-11-16 15:31:52 +00:00
|
|
|
.. contents::
|
2017-07-25 16:54:36 +00:00
|
|
|
|
2017-11-16 15:31:52 +00:00
|
|
|
Cordapps run on the Corda platform and integrate with it and each other. This article explains how to build CorDapps.
|
|
|
|
To learn what a CorDapp is, please read :doc:`cordapp-overview`.
|
2017-07-25 16:54:36 +00:00
|
|
|
|
2017-11-16 15:31:52 +00:00
|
|
|
CorDapp format
|
|
|
|
--------------
|
|
|
|
A CorDapp is a semi-fat JAR that contains all of the CorDapp's dependencies *except* the Corda core libraries and any
|
|
|
|
other CorDapps it depends on.
|
2017-07-25 16:54:36 +00:00
|
|
|
|
2017-11-16 15:31:52 +00:00
|
|
|
For example, if a Cordapp depends on ``corda-core``, ``your-other-cordapp`` and ``apache-commons``, then the Cordapp
|
|
|
|
JAR will contain:
|
2017-07-25 16:54:36 +00:00
|
|
|
|
2017-11-16 15:31:52 +00:00
|
|
|
* All classes and resources from the ``apache-commons`` JAR and its dependencies
|
|
|
|
* *Nothing* from the other two JARs
|
2017-07-25 16:54:36 +00:00
|
|
|
|
2017-11-16 15:31:52 +00:00
|
|
|
Build tools
|
|
|
|
-----------
|
|
|
|
In the instructions that follow, we assume you are using ``gradle`` and the ``cordformation`` plugin to build your
|
|
|
|
CorDapp. See the `example build file <https://github.com/corda/cordapp-template-kotlin/blob/release-V1/build.gradle>`_
|
|
|
|
from the CorDapp template.
|
2017-07-25 16:54:36 +00:00
|
|
|
|
2017-11-16 15:31:52 +00:00
|
|
|
Setting your dependencies
|
|
|
|
-------------------------
|
2017-07-25 16:54:36 +00:00
|
|
|
|
|
|
|
Choosing your Corda version
|
|
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
2017-12-21 11:22:32 +00:00
|
|
|
``ext.corda_release_version`` and ``ext.corda_gradle_plugins_version`` are used in the ``build.gradle`` to define the
|
|
|
|
versions of Corda and the Corda Gradle Plugins that are used to build your CorDapp.
|
|
|
|
|
|
|
|
For example, to use version 1.0 of Corda and version 1.0 of the Corda gradle plugins, you'd write:
|
2017-07-25 16:54:36 +00:00
|
|
|
|
|
|
|
.. sourcecode:: groovy
|
|
|
|
|
2017-11-16 15:31:52 +00:00
|
|
|
ext.corda_release_version = '1.0.0'
|
|
|
|
ext.corda_gradle_plugins_version = '1.0.0'
|
|
|
|
|
|
|
|
You can find the latest published version of both here: https://bintray.com/r3/corda.
|
2017-07-25 16:54:36 +00:00
|
|
|
|
|
|
|
``corda_gradle_plugins_versions`` are given in the form ``major.minor.patch``. You should use the same ``major`` and
|
|
|
|
``minor`` versions as the Corda version you are using, and the latest ``patch`` version. A list of all the available
|
2017-10-09 19:08:08 +00:00
|
|
|
versions can be found here: https://bintray.com/r3/corda/cordapp.
|
2017-07-25 16:54:36 +00:00
|
|
|
|
|
|
|
In certain cases, you may also wish to build against the unstable Master branch. See :doc:`building-against-master`.
|
|
|
|
|
2017-11-16 15:31:52 +00:00
|
|
|
Corda dependencies
|
|
|
|
^^^^^^^^^^^^^^^^^^
|
2017-12-21 11:22:32 +00:00
|
|
|
The ``cordformation`` plugin adds two new gradle configurations:
|
2017-11-16 15:31:52 +00:00
|
|
|
|
2017-12-21 11:22:32 +00:00
|
|
|
* ``cordaCompile``, which extends ``compile``
|
|
|
|
* ``cordaRuntime``, which extends ``runtime``
|
2017-11-16 15:31:52 +00:00
|
|
|
|
2018-01-29 12:42:31 +00:00
|
|
|
``cordaCompile`` and ``cordaRuntime`` indicate dependencies that should not be included in the CorDapp JAR. These
|
|
|
|
configurations should be used for any Corda dependency (e.g. ``corda-core``, ``corda-node``) in order to prevent a
|
|
|
|
dependency from being included twice (once in the CorDapp JAR and once in the Corda JARs).
|
|
|
|
|
2017-12-21 11:22:32 +00:00
|
|
|
To build against Corda, you must add the following to your ``build.gradle`` file:
|
2017-07-25 16:54:36 +00:00
|
|
|
|
2017-12-21 11:22:32 +00:00
|
|
|
* ``net.corda:corda:$corda_release_version`` as a ``cordaRuntime`` dependency
|
|
|
|
* Each Corda compile dependency (eg ``net.corda:corda-core:$corda_release_version``) as a ``cordaCompile`` dependency
|
2017-07-25 16:54:36 +00:00
|
|
|
|
2017-12-21 11:22:32 +00:00
|
|
|
You may also want to add:
|
|
|
|
|
|
|
|
* ``net.corda:corda-test-utils:$corda_release_version`` as a ``testCompile`` dependency, in order to use Corda's test
|
|
|
|
frameworks
|
|
|
|
* ``net.corda:corda-webserver:$corda_release_version`` as a ``cordaRuntime`` dependency, in order to use Corda's
|
|
|
|
built-in development webserver
|
2017-07-25 16:54:36 +00:00
|
|
|
|
2017-11-16 15:31:52 +00:00
|
|
|
.. warning:: Never include ``corda-test-utils`` as a ``compile`` or ``cordaCompile`` dependency.
|
|
|
|
|
|
|
|
Dependencies on other CorDapps
|
|
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
2017-12-21 11:22:32 +00:00
|
|
|
You CorDapp may also depend on classes defined in another CorDapp, such as states, contracts and flows. There are two
|
|
|
|
ways to add another CorDapp as a dependency in your CorDapp's ``build.gradle`` file:
|
|
|
|
|
|
|
|
* ``cordapp project(":another-cordapp")`` (use this if the other CorDapp is defined in a module in the same project)
|
|
|
|
* ``cordapp "net.corda:another-cordapp:1.0"`` (use this otherwise)
|
2017-11-16 15:31:52 +00:00
|
|
|
|
2018-01-29 12:42:31 +00:00
|
|
|
The ``cordapp`` gradle configuration serves two purposes:
|
|
|
|
|
|
|
|
* When using the ``cordformation`` Gradle plugin, the ``cordapp`` configuration indicates that this JAR should be
|
|
|
|
included on your node as a CorDapp
|
|
|
|
* When using the ``cordapp`` Gradle plugin, the ``cordapp`` configuration prevents the dependency from being included
|
|
|
|
in the CorDapp JAR
|
|
|
|
|
|
|
|
Note that the ``cordformation`` and ``cordapp`` Gradle plugins can be used together.
|
|
|
|
|
2017-11-16 15:31:52 +00:00
|
|
|
Other dependencies
|
|
|
|
^^^^^^^^^^^^^^^^^^
|
2017-07-25 16:54:36 +00:00
|
|
|
If your CorDapps have any additional external dependencies, they can be specified like normal Kotlin/Java dependencies
|
|
|
|
in Gradle. See the example below, specifically the ``apache-commons`` include.
|
|
|
|
|
|
|
|
For further information about managing dependencies, see
|
|
|
|
`the Gradle docs <https://docs.gradle.org/current/userguide/dependency_management.html>`_.
|
|
|
|
|
|
|
|
Example
|
2017-11-16 15:31:52 +00:00
|
|
|
^^^^^^^
|
|
|
|
The following is a sample of what a gradle dependencies block for a CorDapp could look like. The CorDapp template
|
2017-07-25 16:54:36 +00:00
|
|
|
is already correctly configured and this is for reference only;
|
|
|
|
|
|
|
|
.. container:: codeset
|
|
|
|
|
|
|
|
.. sourcecode:: groovy
|
|
|
|
|
|
|
|
dependencies {
|
|
|
|
// Corda integration dependencies
|
2017-07-27 16:53:51 +00:00
|
|
|
cordaCompile "net.corda:corda-core:$corda_release_version"
|
|
|
|
cordaCompile "net.corda:corda-finance:$corda_release_version"
|
|
|
|
cordaCompile "net.corda:corda-jackson:$corda_release_version"
|
|
|
|
cordaCompile "net.corda:corda-rpc:$corda_release_version"
|
|
|
|
cordaCompile "net.corda:corda-node-api:$corda_release_version"
|
|
|
|
cordaCompile "net.corda:corda-webserver-impl:$corda_release_version"
|
2017-07-25 16:54:36 +00:00
|
|
|
cordaRuntime "net.corda:corda:$corda_release_version"
|
|
|
|
cordaRuntime "net.corda:corda-webserver:$corda_release_version"
|
|
|
|
testCompile "net.corda:corda-test-utils:$corda_release_version"
|
|
|
|
|
|
|
|
// Corda Plugins: dependent flows and services
|
2017-11-16 15:31:52 +00:00
|
|
|
// Identifying a CorDapp by its module in the same project.
|
|
|
|
cordapp project(":cordapp-contracts-states")
|
|
|
|
// Identifying a CorDapp by its fully-qualified name.
|
2017-07-25 16:54:36 +00:00
|
|
|
cordapp "net.corda:bank-of-corda-demo:1.0"
|
|
|
|
|
|
|
|
// Some other dependencies
|
|
|
|
compile "org.jetbrains.kotlin:kotlin-stdlib-jre8:$kotlin_version"
|
|
|
|
testCompile "org.jetbrains.kotlin:kotlin-test:$kotlin_version"
|
|
|
|
testCompile "junit:junit:$junit_version"
|
|
|
|
|
|
|
|
compile "org.apache.commons:commons-lang3:3.6"
|
|
|
|
}
|
|
|
|
|
2017-11-16 15:31:52 +00:00
|
|
|
Creating the CorDapp JAR
|
|
|
|
------------------------
|
2017-12-07 16:39:52 +00:00
|
|
|
Once your dependencies are set correctly, you can build your CorDapp JAR using the gradle ``jar`` task:
|
|
|
|
|
|
|
|
* Unix/Mac OSX: ``./gradlew jar``
|
|
|
|
|
|
|
|
* Windows: ``gradlew.bat jar``
|
|
|
|
|
|
|
|
The CorDapp JAR will be output to the ``build/libs`` folder.
|
2017-11-16 15:31:52 +00:00
|
|
|
|
2017-11-29 17:07:13 +00:00
|
|
|
.. warning:: The hash of the generated CorDapp JAR is not deterministic, as it depends on variables such as the
|
|
|
|
timestamp at creation. Nodes running the same CorDapp must therefore ensure they are using the exact same CorDapp
|
2017-12-07 16:39:52 +00:00
|
|
|
JAR, and not different versions of the JAR created from identical sources.
|
2017-11-16 15:31:52 +00:00
|
|
|
|
|
|
|
The filename of the JAR must include a unique identifier to deduplicate it from other releases of the same CorDapp.
|
|
|
|
This is typically done by appending the version string to the CorDapp's name. This unique identifier should not change
|
|
|
|
once the JAR has been deployed on a node. If it does, make sure no one is relying on ``FlowContext.appName`` in their
|
|
|
|
flows (see :doc:`versioning`).
|
|
|
|
|
2017-12-07 16:39:52 +00:00
|
|
|
Installing the CorDapp JAR
|
2017-11-16 15:31:52 +00:00
|
|
|
--------------------------
|
|
|
|
|
|
|
|
.. note:: Before installing a CorDapp, you must create one or more nodes to install it on. For instructions, please see
|
2017-11-29 17:07:13 +00:00
|
|
|
:doc:`generating-a-node`.
|
2017-11-16 15:31:52 +00:00
|
|
|
|
|
|
|
At runtime, nodes will load any CorDapps present in their ``cordapps`` folder. Therefore in order to install a CorDapp on
|
|
|
|
a node, the CorDapp JAR must be added to the ``<node_dir>/cordapps/`` folder, where ``node_dir`` is the folder in which
|
2018-01-29 12:42:31 +00:00
|
|
|
the node's JAR and configuration files are stored.
|
2018-02-14 14:49:59 +00:00
|
|
|
|
|
|
|
CorDapp configuration files
|
|
|
|
---------------------------
|
|
|
|
|
|
|
|
CorDapp configuration files should be placed in ``<node_dir>/cordapps/config``. The name of the file should match the
|
|
|
|
name of the JAR of the CorDapp (eg; if your CorDapp is called ``hello-0.1.jar`` the config should be ``config/hello-0.1.conf``).
|
|
|
|
|
|
|
|
Config files are currently only available in the `Typesafe/Lightbend <https://github.com/lightbend/config>`_ config format.
|
|
|
|
These files are loaded when a CorDapp context is created and so can change during runtime.
|
|
|
|
|
|
|
|
CorDapp configuration can be accessed from ``CordappContext::config`` whenever a ``CordappContext`` is available.
|
|
|
|
|
|
|
|
There is an example project that demonstrates in ``samples` called ``cordapp-configuration`` and API documentation in
|
|
|
|
<api/kotlin/corda/net.corda.core.cordapp/index.html>`_.
|
|
|
|
|
|
|
|
|
|
|
|
|