mirror of
https://github.com/corda/corda.git
synced 2024-12-19 04:57:58 +00:00
Merged in rg_doc_changes (pull request #474)
First revision for 'getting set up' - docs not rebuilt as to keep changes visible
This commit is contained in:
Richard Green
commit
e5d7f3fb98
16
docs/source/further-notes-on-kotlin.rst
Normal file
16
docs/source/further-notes-on-kotlin.rst
Normal file
@ -0,0 +1,16 @@
|
||||
|
||||
Further Comments on Kotlin
|
||||
--------------------------
|
||||
|
||||
Corda is written in a language called `Kotlin <https://kotlinlang.org/>`_. 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 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 <https://medium.com/@octskyward/why-kotlin-is-my-next-programming-language-c25c001e26e3>`_.
|
||||
|
||||
61
docs/source/getting-set-up-fault-finding.rst
Normal file
61
docs/source/getting-set-up-fault-finding.rst
Normal file
@ -0,0 +1,61 @@
|
||||
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,
|
||||
you may need to fix the project structure. Do this by following `these instructions<https://www.jetbrains.com/help/idea/2016.2/configuring-global-project-and-module-sdks.html>`_. The correct JDK is often found at a path such as ``jdk1.8.0_xx…/Contents/Home``
|
||||
|
||||
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 <https://intellij-support.jetbrains.com/hc/en-us/articles/206544879-Selecting-the-JDK-version-the-IDE-will-run-under>`_.
|
||||
|
||||
Kotlin issues
|
||||
-------------
|
||||
|
||||
Installation
|
||||
************
|
||||
|
||||
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.
|
||||
|
||||
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 <https://plugins.jetbrains.com/plugin/6954>`_.
|
||||
|
||||
|
||||
Gradle issues
|
||||
-------------
|
||||
|
||||
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.
|
||||
|
||||
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 <https://www.jetbrains.com/help/idea/2016.2/working-with-gradle-projects.html>`_.
|
||||
|
||||
|
||||
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 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 remember to run ``git pull`` occasionally to upgrade the source code to the latest revision
|
||||
@ -1,61 +1,74 @@
|
||||
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. The JDK can be obtained `from Oracle <http://www.oracle.com/technetwork/java/javase/downloads/index.html>`_.
|
||||
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 for free from
|
||||
`JetBrains <https://www.jetbrains.com/idea/download/>`_. 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. Refer to IntelliJ's instructions on
|
||||
`getting Started with Kotlin and IntelliJ <https://kotlinlang.org/docs/tutorials/getting-started.html>`_. 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. The authorative place to obtain git is from the main `git website <https://git-scm.com/downloads>`_
|
||||
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 <https://www.jetbrains.com/help/idea/2016.2/using-git-integration.html>`_
|
||||
|
||||
|
||||
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 <No SDK> 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.
|
||||
|
||||
@ -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 <https://kotlinlang.org/>`_. 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 <https://medium.com/@octskyward/why-kotlin-is-my-next-programming-language-c25c001e26e3>`_.
|
||||
Loading…
Reference in New Issue
Block a user