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.