From c4afa4ae634674d73bbec0e4f59a51b46cb16d3b Mon Sep 17 00:00:00 2001 From: Richard Green Date: Mon, 14 Nov 2016 18:12:39 +0000 Subject: [PATCH] First revision for 'getting set up' - docs not rebuilt as to keep changes visible --- docs/source/further-notes-on-kotlin.rst | 14 +++ docs/source/getting-set-up-fault-finding.rst | 53 +++++++++ docs/source/getting-set-up.rst | 118 +++++++++++-------- docs/source/inthebox.rst | 14 --- 4 files changed, 135 insertions(+), 64 deletions(-) create mode 100644 docs/source/further-notes-on-kotlin.rst create mode 100644 docs/source/getting-set-up-fault-finding.rst diff --git a/docs/source/further-notes-on-kotlin.rst b/docs/source/further-notes-on-kotlin.rst new file mode 100644 index 0000000000..eca3f6c4e8 --- /dev/null +++ b/docs/source/further-notes-on-kotlin.rst @@ -0,0 +1,14 @@ + +Further Comments on Kotlin +-------------------------- + +Corda is written in a language called `Kotlin `_. Kotlin is a language that targets the JVM +and can be thought of as a simpler Scala, with much better Java interop. It is developed by and has commercial support +from JetBrains, the makers of the IntelliJ IDE and other popular developer tools. + +As Kotlin is very new, without a doubt you have not encountered it before. Don't worry: it is designed as a better +Java for industrial use and as such, the syntax was carefully designed to be readable even to people who don't know +the language, after only a few minutes of introduction. + +Due to the seamless Java interop the use of Kotlin to extend the platform is *not* required and the tutorial shows how +to write contracts in both Kotlin and Java. You can `read more about why Kotlin is a potentially strong successor to Java here `_. \ No newline at end of file diff --git a/docs/source/getting-set-up-fault-finding.rst b/docs/source/getting-set-up-fault-finding.rst new file mode 100644 index 0000000000..f625b1bc11 --- /dev/null +++ b/docs/source/getting-set-up-fault-finding.rst @@ -0,0 +1,53 @@ +Getting Set Up : Faultfinding +============================= + + +If IntelliJ complains about lack of an SDK +------------------------------------------ + +If on attempting to open the project (including importing Gradle project), IntelliJ refuses because SDK was not selected, do the following: + + Configure -> Project Defaults -> Project Structure + +on that tab: + + Project Settings / Project + +click on New… next to the red symbol, and select JDK. It should then pop up and show the latest JDK it has +found at something like + + jdk1.8.0_xx…/Contents/Home + +Also select Project language level: as 8. Click OK. Open should now work. + +Kotlin installation issues +-------------------------- + +If you are having trouble installing Kotlin, first try upgrading the Kotlin plugin to the latest version by clicking +"Configure > Plugins" in the opening screen, then clicking "Install JetBrains plugin", then searching for Kotlin, +then hitting "Upgrade" and then "Restart". You can confirm what is the latest version of Kotlin plugin on this page: + + https://plugins.jetbrains.com/plugin/6954 + + +Gradle issues +------------- + +After you have updated your code to the latest version from git, ensure that Gradle project is imported. + +You should have the "Unliked Gradle project?" pop-up window in the IntelliJ top right corner. Please click on "Import Gradle Project". Wait for it to think and download the dependencies. After that you might have another popup titled "Unindexed remote maven repositories found." This is general IntelliJ question and doesn't affect Corda, therefore you can decided to index them or not. + +Next click on "green arrow" next to "All tests" pop-up on the top toolbar. + +The code should build, the unit tests should show as all green. + + + +Doing it without IntelliJ +------------------------- + +If you don't want to explore or modify the code in a local IDE, you can also just use the command line and a text editor: +* First run ``git clone https://your_username@bitbucket.org/R3-CEV/r3prototyping.git`` to download Corda source code. Please remember to replace your_username with your actual bitbucket user name. +* Next ensure that you are in r3repository ``cd r3repository`` +* Then you can run ``./gradlew test`` to run the unit tests. +* Finally remeber to run ``git pull`` to upgrade the source code. diff --git a/docs/source/getting-set-up.rst b/docs/source/getting-set-up.rst index 656576c5b2..dbce789315 100644 --- a/docs/source/getting-set-up.rst +++ b/docs/source/getting-set-up.rst @@ -1,61 +1,79 @@ Getting set up ============== +We have tried to make access to Corda as relatively simple as possible, using industry standard established tools. +Although it is possible to replace any of the recommendations below, we will find it a lot easier to support your efforts +if you follow our guidelines. Saying that, we are also interested in problems that arise due to different configurations. + +A JVM +----- + +Corda runs in a JVM and is written predominantly in Kotlin with some example use cases demonstrated in Java that we have +incorporated to demonstrate that Kotlin and Java can work seemlessly together. We recommend the most recent production +version of Java 8. This can be obtained `from Oracle `_. +Other implementations of the JVM are not actively supported, but as mentioned, we are interested in finding out any issues you +do have with them. + +IntelliJ +-------- +We strongly recommend the use of IntelliJ's Development Environment known as IDEA. Download it from +`JetBrains `_. The primary reason we recommend this particular IDE is that it integrates +very well with our choice of language for Corda "Kotlin", as Jetbrains also support the development of Kotlin. + + +Kotlin +------ +Kotlin is available as a downloadable plugin to IntelliJ. As the configuration of this may change while this document is +being prepared, we advise you to refer to IntelliJ's own reference on +`Getting Started with Kotlin and IntelliJ `_. Additionally, +if you would like to start getting to grips with the Kotlin language, then we strongly recommend you work through some +of the tutorials (known as "koans") as well. Also see our :doc:`further-notes-on-kotlin`. + + +Version Control via Git +----------------------- + +We use git to version control Corda. However, git installation is not essential to install and use Corda - it is possible +to download a snapshot "M" release of the code and work with that. Nonetheless, we recommend that you do use git in order +to easily keep up-to-date with the software as it progresses. + +The authorative place to obtain git is from the main `git website `_ but +it may be the case that your operating system provides git with a supported utility (e.g. for Apple, git is provided along +with XCode - their free development environment). If this is the case, we would recommend you obtain git via that +supported route. + +You will need the command line package installed which you can then use natively (via the command line) or via IntelliJ +(in which case you may need to configure IntelliJ to recognise where git has been installed on your system). IntelliJ and +git configuration are quite seemless although the first time you use it, you will have to configure IntelliJ the location +of your git command installation. More details regarding this can be found +on the `JetBrains website `_ + + +Gradle +------ + +Gradle is our primary means of building Corda and managing dependencies. IntelliJ has its own view of this and occasionally +may need to be resynced from time to time. This can be done within IntelliJ by pressing the "gradle refresh" icon located +on the gradle tab (generally found on the right hand side), or by following the gradle commands specific for the task you +are performing (details expounded later). Whenever prompted about gradle, accept the defaults suggested by IntelliJ. + + + +Corda Source Code +----------------- + +(TODO - when the location has been confirmed) + Ensure that you have access to R3 git repository. - https://bitbucket.org/R3-CEV/r3prototyping.git + https://TODO/corda-core.git -If you cannot access the page please contact the R3 admin team. +You can catch up with the latest code by selecting "VCS -> Update Project" in the IntelliJ menu. -Install the Oracle JDK 8u45 or higher. OpenJDK will probably also work, but it hasn't been tested. -Then install IntelliJ. The Community Edition is good enough: +Troubleshooting +--------------- - https://www.jetbrains.com/idea/download/ +See :doc:`getting-set-up-fault-finding`. -Upgrade the Kotlin plugin to the latest version by clicking "Configure > Plugins" in the opening screen, -then clicking "Install JetBrains plugin", then searching for Kotlin, then hitting "Upgrade" and then "Restart". -You can confirm what is the latest version of Kotlin plugin on this page: - https://plugins.jetbrains.com/plugin/6954 - -Choose "Check out from version control" and use this git URL. Please remember to replace your_username with your -actual bitbucket user name. - - https://your_username@bitbucket.org/R3-CEV/r3prototyping.git - -After code is cloned open the project. Please ensure that Gradle project is imported. -You should have the "Unliked Gradle project?" pop-up window in the IntelliJ top right corner. Please click on "Import Gradle Project". Wait for it to think and download the dependencies. After that you might have another popup titled "Unindexed remote maven repositories found." This is general IntelliJ question and doesn't affect Corda, therefore you can decided to index them or not. - -Next click on "green arrow" next to "All tests" pop-up on the top toolbar. - -The code should build, the unit tests should show as all green. - -You can catch up with the latest code by selecting "VCS -> Update Project" in the menu. - -If IntelliJ complains about lack of an SDK ------------------------------------------- - -If on attempting to open the project (including importing Gradle project), IntelliJ refuses because SDK was not selected, do the following: - - Configure -> Project Defaults -> Project Structure - -on that tab: - - Project Settings / Project - -click on New… next to the red symbol, and select JDK. It should then pop up and show the latest JDK it has -found at something like - - jdk1.8.0_xx…/Contents/Home - -Also select Project language level: as 8. Click OK. Open should now work. - -Doing it without IntelliJ -------------------------- - -If you don't want to explore or modify the code in a local IDE, you can also just use the command line and a text editor: -* First run ``git clone https://your_username@bitbucket.org/R3-CEV/r3prototyping.git`` to download Corda source code. Please remember to replace your_username with your actual bitbucket user name. -* Next ensure that you are in r3repository ``cd r3repository`` -* Then you can run ``./gradlew test`` to run the unit tests. -* Finally remeber to run ``git pull`` to upgrade the source code. diff --git a/docs/source/inthebox.rst b/docs/source/inthebox.rst index 3d2bf3b8b9..7b67a7fe7e 100644 --- a/docs/source/inthebox.rst +++ b/docs/source/inthebox.rst @@ -25,17 +25,3 @@ would not in order to boost productivity: * Some privacy techniques aren't implemented yet. * It uses an embedded SQL database and doesn't yet have connectivity support for mainstream SQL vendors (Oracle, Postgres, MySQL, SQL Server etc). - -Kotlin ------- - -Corda is written in a language called `Kotlin `_. Kotlin is a language that targets the JVM -and can be thought of as a simpler Scala, with much better Java interop. It is developed by and has commercial support -from JetBrains, the makers of the IntelliJ IDE and other popular developer tools. - -As Kotlin is very new, without a doubt you have not encountered it before. Don't worry: it is designed as a better -Java for industrial use and as such, the syntax was carefully designed to be readable even to people who don't know -the language, after only a few minutes of introduction. - -Due to the seamless Java interop the use of Kotlin to extend the platform is *not* required and the tutorial shows how -to write contracts in both Kotlin and Java. You can `read more about why Kotlin is a potentially strong successor to Java here `_. \ No newline at end of file