From eaf404f51da1775fab2f42a01a87b3b69ef34c5f Mon Sep 17 00:00:00 2001 From: Clinton Alexander Date: Fri, 7 Oct 2016 16:46:33 +0100 Subject: [PATCH] Added some documentation about cordapp plugins. --- .idea/modules.xml | 3 - docs/source/cordapp-plugins.rst | 151 ++++++++++++++++++ plugins/cordformation/README.txt | 1 + .../com/r3corda/plugins/Cordform.groovy | 1 + .../com/r3corda/plugins/Cordformation.groovy | 4 + .../groovy/com/r3corda/plugins/Node.groovy | 1 + .../plugins/DefaultPublishTasks.groovy | 1 + .../com/r3corda/plugins/QuasarPlugin.groovy | 1 - 8 files changed, 159 insertions(+), 4 deletions(-) create mode 100644 docs/source/cordapp-plugins.rst create mode 100644 plugins/cordformation/README.txt diff --git a/.idea/modules.xml b/.idea/modules.xml index dec18dacb0..9eaa61f172 100644 --- a/.idea/modules.xml +++ b/.idea/modules.xml @@ -15,9 +15,6 @@ - - - diff --git a/docs/source/cordapp-plugins.rst b/docs/source/cordapp-plugins.rst new file mode 100644 index 0000000000..457291eaf3 --- /dev/null +++ b/docs/source/cordapp-plugins.rst @@ -0,0 +1,151 @@ +Cordapp Plugins +=============== + +Building Plugins +---------------- + +To build the plugins that Cordapps require run the following from the root of the Corda project: + +..code-block:: + + gradlew publishToMavenLocal + +The plugins will now be installed to MavenLocal. + +Installing Plugins +------------------ + +To use the plugins, if you are not already using the Cordapp template project, you must modify your build.gradle. Add +the following segments to the relevant part of your build.gradle. + +..code-block:: + + buildscript { + ext.corda_version = '' + ... (your buildscript) + + repositories { + ... (other repositories) + mavenLocal() + } + + dependencies { + ... (your dependencies) + classpath "com.r3corda.plugins::$corda_version" + } + } + + apply plugin: 'com.r3corda.plugins.' + + ... + +Cordformation +------------- + +Plugin Maven Name:: + + cordformation + +Cordformation is the local node deployment system for Cordapps, the nodes generated are intended to be used for +experimenting, debugging, and testing node configurations and setups but not intended for production or testnet +deployment. + +To use this plugin you must add a new task that is of the type `com.r3corda.plugins.Cordform` and then configure +the nodes you wish to deploy with the Node and nodes configuration DSL. This DSL is specified in the JavaDoc but +an example of this is in the template-cordapp and below is a three node example; + +..code-block:: + + task deployNodes(type: com.r3corda.plugins.Cordform, dependsOn: ['build']) { + directory "./build/nodes" // The output directory + networkMap "Notary" // This will resolve a node in this configuration + node { + name "Notary" + dirName "notary" + nearestCity "London" + notary true // Sets this node to be a notary + advertisedServices = [] + artemisPort 12345 + webPort 12346 + cordapps = [] + } + node { + name "NodeA" + dirName "nodea" + nearestCity "London" + advertisedServices = [] + artemisPort 31337 + webPort 31339 + cordapps = [] + } + node { + name "NodeB" + dirName "nodeb" + nearestCity "New York" + advertisedServices = [] + artemisPort 31338 + webPort 31340 + cordapps = [] + } + } + +Because it is a task you can create multiple tasks with multiple configurations that you use commonly. + +New nodes can be added by simply adding another node block and giving it a different name, directory and ports. When you +run this task it will install the nodes to the directory specified and a script will be generated (for *nix users only +at present) to run the nodes with one command. + +Other cordapps can also be specified if they are already specified as classpath or compile dependencies in your +build.gradle. + +Publish Utils +------------- + +Plugin Maven Name:: + + publish-utils + +Publishing utilities adds a couple of tasks to any project it is applied to that hide some boilerplate that would +otherwise be placed in the Cordapp template's build.gradle. + +There are two tasks exposed: `sourceJar` and `javadocJar` and both return a `FileCollection`. + +It is used within the `publishing` block of a build.gradle as such; + +..code-block:: + + // This will publish the sources, javadoc, and Java components to Maven. + // See the `maven-publish` plugin for more info: https://docs.gradle.org/current/userguide/publishing_maven.html + publishing { + publications { + jarAndSources(MavenPublication) { + from components.java + // The two lines below are the tasks added by this plugin. + artifact sourceJar + artifact javadocJar + } + } + } + +Quasar Utils +------------ + +Plugin Maven Name:: + + quasar-utils + +Quasar utilities adds several tasks and configuration that provide a default Quasar setup and removes some boilerplate. +One line must be added to your build.gradle once you apply this plugin: + +..code-block:: + + quasarScan.dependsOn('classes') + +If any sub-projects are added that this project depends on then add the gradle target for that project to the depends +on statement. eg: + +..code-block:: + + quasarScan.dependsOn('classes', 'subproject:subsubproject', ...) + + diff --git a/plugins/cordformation/README.txt b/plugins/cordformation/README.txt new file mode 100644 index 0000000000..bcb90eec02 --- /dev/null +++ b/plugins/cordformation/README.txt @@ -0,0 +1 @@ +Please see docs/source/cordapp-plugins.rst for more information. \ No newline at end of file diff --git a/plugins/cordformation/src/main/groovy/com/r3corda/plugins/Cordform.groovy b/plugins/cordformation/src/main/groovy/com/r3corda/plugins/Cordform.groovy index 42dc8ff41a..59914a78f9 100644 --- a/plugins/cordformation/src/main/groovy/com/r3corda/plugins/Cordform.groovy +++ b/plugins/cordformation/src/main/groovy/com/r3corda/plugins/Cordform.groovy @@ -4,6 +4,7 @@ import org.gradle.api.DefaultTask import org.gradle.api.tasks.TaskAction import java.nio.file.Path import java.nio.file.Paths +import org.gradle.api.Project /** * Creates nodes based on the configuration of this task in the gradle configuration DSL. diff --git a/plugins/cordformation/src/main/groovy/com/r3corda/plugins/Cordformation.groovy b/plugins/cordformation/src/main/groovy/com/r3corda/plugins/Cordformation.groovy index 61f6b4bed6..5ebafd50e5 100644 --- a/plugins/cordformation/src/main/groovy/com/r3corda/plugins/Cordformation.groovy +++ b/plugins/cordformation/src/main/groovy/com/r3corda/plugins/Cordformation.groovy @@ -8,6 +8,10 @@ import org.gradle.api.Project * testing, and debugging. It will prepopulate several fields in the configuration and create a simple node runner. */ class Cordformation implements Plugin { + void apply(Project project) { + + } + /** * Gets a resource file from this plugin's JAR file. * diff --git a/plugins/cordformation/src/main/groovy/com/r3corda/plugins/Node.groovy b/plugins/cordformation/src/main/groovy/com/r3corda/plugins/Node.groovy index 2e3f0b82d3..b0904df552 100644 --- a/plugins/cordformation/src/main/groovy/com/r3corda/plugins/Node.groovy +++ b/plugins/cordformation/src/main/groovy/com/r3corda/plugins/Node.groovy @@ -1,6 +1,7 @@ package com.r3corda.plugins import org.gradle.api.internal.file.AbstractFileCollection +import org.gradle.api.Project /** * Represents a node that will be installed. diff --git a/plugins/publish-utils/src/main/groovy/com/r3corda/plugins/DefaultPublishTasks.groovy b/plugins/publish-utils/src/main/groovy/com/r3corda/plugins/DefaultPublishTasks.groovy index 419455ba71..6ff1c2f2db 100644 --- a/plugins/publish-utils/src/main/groovy/com/r3corda/plugins/DefaultPublishTasks.groovy +++ b/plugins/publish-utils/src/main/groovy/com/r3corda/plugins/DefaultPublishTasks.groovy @@ -3,6 +3,7 @@ package com.r3corda.plugins import org.gradle.api.* import org.gradle.api.tasks.bundling.Jar import org.gradle.api.tasks.javadoc.Javadoc +import org.gradle.api.Project /** * A utility plugin that when applied will automatically create source and javadoc publishing tasks diff --git a/plugins/quasar-utils/src/main/groovy/com/r3corda/plugins/QuasarPlugin.groovy b/plugins/quasar-utils/src/main/groovy/com/r3corda/plugins/QuasarPlugin.groovy index 7411467ed4..82298b87ae 100644 --- a/plugins/quasar-utils/src/main/groovy/com/r3corda/plugins/QuasarPlugin.groovy +++ b/plugins/quasar-utils/src/main/groovy/com/r3corda/plugins/QuasarPlugin.groovy @@ -1,6 +1,5 @@ package com.r3corda.plugins -import org.gradle.api.* import org.gradle.api.tasks.testing.Test import org.gradle.api.tasks.JavaExec