From c4afa4ae634674d73bbec0e4f59a51b46cb16d3b Mon Sep 17 00:00:00 2001 From: Richard Green Date: Mon, 14 Nov 2016 18:12:39 +0000 Subject: [PATCH 1/2] 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 From c370e01e68c3ce1aa7c3c21753758b20bcaeeeeb Mon Sep 17 00:00:00 2001 From: Richard Green Date: Thu, 17 Nov 2016 16:31:08 +0000 Subject: [PATCH 2/2] From comment review PR --- docs/source/further-notes-on-kotlin.rst | 10 ++-- docs/source/getting-set-up-fault-finding.rst | 56 +++++++++++--------- docs/source/getting-set-up.rst | 19 +++---- 3 files changed, 45 insertions(+), 40 deletions(-) diff --git a/docs/source/further-notes-on-kotlin.rst b/docs/source/further-notes-on-kotlin.rst index eca3f6c4e8..a52b6f8764 100644 --- a/docs/source/further-notes-on-kotlin.rst +++ b/docs/source/further-notes-on-kotlin.rst @@ -6,9 +6,11 @@ Corda is written in a language called `Kotlin `_. Kotli 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. +As Kotlin is relatively new language and is extremely easy to learn. It is designed as as 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. Additionally, at R3, we find that all of our developers are up to productive writing speed +in Kotlin within their first week. 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 +to write contracts in both Kotlin and Java. You can `read more about why Kotlin is a potentially strong successor to Java here `_. + diff --git a/docs/source/getting-set-up-fault-finding.rst b/docs/source/getting-set-up-fault-finding.rst index f625b1bc11..ff709578e1 100644 --- a/docs/source/getting-set-up-fault-finding.rst +++ b/docs/source/getting-set-up-fault-finding.rst @@ -2,52 +2,60 @@ Getting Set Up : Faultfinding ============================= +IntelliJ issues +--------------- + 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: +If on attempting to open the project (including importing Gradle project), IntelliJ refuses because SDK was not selected, +you may need to fix the project structure. Do this by following `these instructions`_. The correct JDK is often found at a path such as ``jdk1.8.0_xx…/Contents/Home`` - Configure -> Project Defaults -> Project Structure +Ensure that you have the Project language level set at as 8. If you are having trouble selecting the correct JDK, the +Jetbrains website offers the `following guidelines `_. -on that tab: +Kotlin issues +------------- - Project Settings / Project +Installation +************ -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 +There are two ways to configure Kotlin from IntelliJ. One way is via the initial project opening screen in which you will +need to use the ``Configure > Plugins`` tab. The other way is when you are in an open project, then you will need to +configure it via (on Mac) ``IntelliJ -> Preferences ...``, where on PC it is ``File -> Settings``. Select the plugins +bar, confirm that Kotlin is installed and up to date. - 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 +If you are having trouble installing Kotlin, first try upgrading the Kotlin plugin. At the time of writing, you can +confirm what is the latest version of the Kotlin plugin on `this page `_. Gradle issues ------------- -After you have updated your code to the latest version from git, ensure that Gradle project is imported. +After you have updated your code to the latest version from git, ensure that the gradle project is imported. Although +gradle is used via the command line, it is also integrated with IntelliJ in order for IntelliJ to determine dependencies +and index the project correctly. -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. +When opening a project for the first time, you should see the "Unlinked Gradle project?" pop-up window in the IntelliJ top +right corner or in a popup alert window. If you miss this, it will also appear in the "Event Log" windows which can be +opened by clicking on "Event Log" at the bottom right of the IntelliJ window. Either way, click on "Import Gradle Project". + +.. image:: unlinked-gradle.png + +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. +If still have problems, the Jetbrains website has more information on `gradle here `_. 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`` +* First run ``git clone TODO:Corda_repo_name_here`` to download Corda source code. +* Next ensure that you are in r3repository ``cd r3repository`` // TODO - change to be correct location * Then you can run ``./gradlew test`` to run the unit tests. -* Finally remeber to run ``git pull`` to upgrade the source code. +* Finally remember to run ``git pull`` occasionally to upgrade the source code to the latest revision diff --git a/docs/source/getting-set-up.rst b/docs/source/getting-set-up.rst index dbce789315..7c72eaa4ba 100644 --- a/docs/source/getting-set-up.rst +++ b/docs/source/getting-set-up.rst @@ -10,22 +10,21 @@ 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 `_. +version of Java 8. The JDK 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 +We strongly recommend the use of IntelliJ's Development Environment known as IDEA. Download it for free 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. +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, +Kotlin is available as a downloadable plugin to IntelliJ. Refer to IntelliJ's instructions 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`. @@ -33,12 +32,8 @@ of the tutorials (known as "koans") as well. Also see our :doc:`further-notes-on 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 +We use git to version control Corda. 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.