mirror of
https://github.com/corda/corda.git
synced 2024-12-21 13:57:54 +00:00
Provides clearer instructions on the 'Getting set up' page. Expands 'Troubleshooting' page.
This commit is contained in:
Joel Dudley
GitHub
parent
e8015e689a
commit
cfcfb30beb
@ -1,83 +1,83 @@
|
||||
Troubleshooting
|
||||
===============
|
||||
|
||||
IntelliJ issues
|
||||
---------------
|
||||
Milestone releases
|
||||
------------------
|
||||
|
||||
Run configurations are missing
|
||||
When you clone the corda or cordapp-template repos, they will default to the master branch. The master branch is being continuously developed upon, and its features may not align with the state of Corda as described in the docs. Additionally, the master branch of the CorDapp Template may break in response to changes in the main corda repo.
|
||||
|
||||
When developing on Corda, you should always check out the latest stable branch instead, by running ``git checkout release-M7``.
|
||||
|
||||
Java issues
|
||||
-----------
|
||||
|
||||
Outdated/non-Oracle JDKs
|
||||
************************
|
||||
|
||||
Many users have faced issues when running versions of Java that are either outdated, or are produced by organisations other than Oracle (e.g. OpenJDK). The errors generated by these issues will not always clearly point to the JDK as the cause. If in doubt, check your JDK version by following the instructions `here <https://java.com/en/download/help/version_manual.xml>`_. You can download the latest version of Oracle's JDK `here <http://www.oracle.com/technetwork/java/javase/downloads/index.html>`_.
|
||||
|
||||
"Unresolved reference: javafx"
|
||||
******************************
|
||||
|
||||
If you opened the Corda project using "Import" from the IntelliJ splash screen rather than using "Open" and then
|
||||
importing the Gradle build system from the popup bubble, then a bug in IntelliJ will cause it to wipe and recreate
|
||||
the ``.idea`` directory where the run configurations are stored. The fix is simple and doesn't require you to
|
||||
re-import the project: just undelete the files! You can do that by either:
|
||||
JavaFX is not bundled with OpenJDK. If you are using OpenJDK and get an 'Unresolved reference: javafx' error, this means that you need to install OpenJFX. Do this by running ``sudo apt install openjfx``, and possibly ``sudo apt install libopenjfx-jav``.
|
||||
|
||||
1. Running ``git checkout .idea/runConfigurations`` to restore that part of the tree to its normal state.
|
||||
2. Using the "Version Control" pane in IntelliJ to undelete the files via the GUI.
|
||||
IDEA issues
|
||||
---------------
|
||||
|
||||
If IntelliJ complains about lack of an SDK
|
||||
******************************************
|
||||
No source files are present
|
||||
***************************
|
||||
|
||||
If on attempting to open the project (including importing Gradle project), IntelliJ refuses because an 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 ...``, whereas 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
|
||||
-------------
|
||||
|
||||
Gradle within IntelliJ
|
||||
**********************
|
||||
|
||||
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".
|
||||
When opening a project in IDEA for the first time, you will need to build the project. You should see "Unlinked Gradle project?"
|
||||
in a pop-up window in the top-right corner or in a popup alert window. It will also appear in the "Event Log" window which can be
|
||||
opened by clicking on "Event Log" at the bottom right of the IDEA window. Find one of these links and click on "Import Gradle Project".
|
||||
|
||||
.. image:: resources/unlinked-gradle.png
|
||||
:height: 50 px
|
||||
:width: 410 px
|
||||
:alt: IntelliJ Gradle Prompt
|
||||
:alt: IDEA Gradle Prompt
|
||||
|
||||
Wait for it to think and download the dependencies. After that you might have another popup titled "Unindexed remote maven repositories found." This is a general IntelliJ question and doesn't affect Corda, therefore you can decided to index them or not. Next click on the "green arrow" next to "All tests" pop-up on the top toolbar.
|
||||
Wait for it to download the dependencies. You may then see another popup titled "Unindexed remote maven repositories found." This won't affect Corda,
|
||||
so you can choose to leave them unindexed.
|
||||
|
||||
The code should build, the unit tests should show as all green.
|
||||
If still have problems, the JetBrains website has more information on `here <https://www.jetbrains.com/help/idea/2016.2/working-with-gradle-projects.html>`_.
|
||||
|
||||
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>`_.
|
||||
Run configurations are missing
|
||||
******************************
|
||||
|
||||
Gradle via the CLI
|
||||
******************
|
||||
If you opened the Corda project by clicking "Import Project" on the IDEA splash screen rather than clicking "Open", a bug
|
||||
in IDEA will cause it to wipe and recreate the ``.idea`` directory where the run configurations are stored. The fix is
|
||||
simple and doesn't require you to re-import the project: just undelete the files! You can do that by either:
|
||||
|
||||
Gradle commands can also be run from the command line - further details of command line gradle can be found `here <https://docs.gradle.org/current/userguide/gradle_command_line.html>`_.
|
||||
1. Running ``git checkout .idea/runConfigurations`` to redownload the files.
|
||||
2. Using the "Version Control" pane in IDEA to undelete the files via the GUI.
|
||||
|
||||
Doing it without IntelliJ
|
||||
-------------------------
|
||||
IDEA complains about lack of an SDK
|
||||
***************************************
|
||||
|
||||
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:
|
||||
If IDEA refuses to open a project because an SDK has not been 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 on a path such as ``jdk1.8.0_xx…/Contents/Home``. Ensure that you have the Project language level set at 8.
|
||||
|
||||
* First run ``git clone https://github.com/corda/corda`` to download Corda core source code
|
||||
If you are having trouble selecting the correct JDK, the JetBrains website provides the `following guidelines <https://intellij-support.jetbrains.com/hc/en-us/articles/206544879-Selecting-the-JDK-version-the-IDE-will-run-under>`_.
|
||||
|
||||
* Next ensure that you are in correct directory ``cd corda``
|
||||
Kotlin plugin
|
||||
*************
|
||||
|
||||
* Then you can run ``./gradlew test`` to run the unit tests.
|
||||
There are two ways to configure Kotlin in IDEA:
|
||||
|
||||
* Finally remember to run ``git pull`` occasionally to upgrade the source code to the latest revision
|
||||
1. Via the initial project opening screen, by using the ``Configure > Plugins`` tab.
|
||||
2. From an open IDEA project, by clicking ``IDEA -> Preferences ...`` (on OS X) or ``File -> Settings`` (on Windows). Select the Plugins bar to confirm that Kotlin is installed and up-to-date.
|
||||
|
||||
If you are still having trouble installing Kotlin, first try upgrading the Kotlin plugin. At the time of writing, you can
|
||||
identify the latest version of the Kotlin plugin on `this page <https://plugins.jetbrains.com/plugin/6954>`_.
|
||||
|
||||
"Unable to make the module: related gradle configuration was not found. Please, re-import the Gradle project and try again"
|
||||
***************************************************************************************************************************
|
||||
|
||||
This can usually be solved by updating IDEA. Check that you have the latest version `here <https://www.jetbrains.com/idea/download/>`_.
|
||||
|
||||
Other common issues
|
||||
-------------------
|
||||
|
||||
“xterm: command not found”
|
||||
**************************
|
||||
|
||||
On some machines, running the samples requires xterm. You can download it `here <http://invisible-island.net/xterm/#download>`_.
|
||||
@ -1,83 +1,103 @@
|
||||
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.
|
||||
Software requirements
|
||||
---------------------
|
||||
|
||||
A JVM
|
||||
-----
|
||||
Corda uses industry-standard tools to make set-up as simple as possible. Following the software recommendations below will
|
||||
minimize the number of errors you encounter, and make it easier for others to provide support. However, if you do use other tools,
|
||||
we're interested to hear about any issues that arise.
|
||||
|
||||
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 seamlessly 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.
|
||||
JVM
|
||||
~~~
|
||||
|
||||
.. note:: If you are using a JVM implementation other than Oracle's you may get errors similar to ``Unresolved reference: javafx``.
|
||||
This means JavaFX is not bundled with the JVM and you will need to install it separately (e.g. OpenJFX is needed
|
||||
with OpenJDK).
|
||||
Corda is written in Kotlin and runs in a JVM. We develop against Oracle JDK 8, and other JVM implementations are not actively
|
||||
supported. Oracle JDK 8 can be obtained directly from
|
||||
`Oracle <http://www.oracle.com/technetwork/java/javase/downloads/index.html>`_. Installation instructions are
|
||||
available for `Windows <http://docs.oracle.com/javase/8/docs/technotes/guides/install/windows_jdk_install.html#CHDEBCCJ>`_,
|
||||
`Linux <http://docs.oracle.com/javase/8/docs/technotes/guides/install/linux_jdk.html#BJFGGEFG>`_ and
|
||||
`OS X <http://docs.oracle.com/javase/8/docs/technotes/guides/install/mac_jdk.html#CHDBADCG>`_.
|
||||
|
||||
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.
|
||||
Please ensure that you keep your Oracle JDK installation updated to the latest version while working with Corda.
|
||||
Even earlier versions of JDK 8 versions can cause cryptic errors.
|
||||
|
||||
.. warning:: When opening the Corda project for the first time from the IntelliJ splash screen, please use "Open"
|
||||
and then agree to import the Gradle project from the popup bubble. Don't pick "Import" on the splash screen,
|
||||
because a bug in IntelliJ will cause the pre-packaged run configurations to be erased. If you see this warning
|
||||
too late, it's no problem, just use ``git checkout .idea/runConfiguration`` or the version control tab in IntelliJ
|
||||
to undelete the files.
|
||||
If you do choose to use OpenJDK instead of Oracle's JDK, you will also need to install OpenJFX.
|
||||
|
||||
Additional troubleshooting information can be found `here <https://docs.corda.net/getting-set-up-fault-finding.html#java-issues>`_.
|
||||
|
||||
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`.
|
||||
~~~~~~
|
||||
|
||||
Applications on Corda (CorDapps) can be written in any JVM-targeting language. However, Corda itself and most of the samples
|
||||
are written in Kotlin. If you're unfamiliar with Kotlin, there is an official `getting started guide <https://kotlinlang.org/docs/tutorials/>`_.
|
||||
See also our :doc:`further-notes-on-kotlin`.
|
||||
|
||||
Version control via Git
|
||||
-----------------------
|
||||
IDE
|
||||
~~~
|
||||
|
||||
We use git to version control Corda. The authoritative 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.
|
||||
We strongly recommend the use of IntelliJ IDEA as an IDE, primarily due to the strength of its Kotlin integration. The free Community
|
||||
Edition can be downloaded from `JetBrains <https://www.jetbrains.com/idea/download/>`_.
|
||||
|
||||
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 seamless 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>`_
|
||||
Please make sure that you're running the latest version of IDEA, as older versions have been known to have problems integrating with Gradle,
|
||||
the build tool used by Corda.
|
||||
|
||||
You'll also want to install the Kotlin IDEA plugin by following the instructions
|
||||
`here <https://kotlinlang.org/docs/tutorials/getting-started.html>`_.
|
||||
|
||||
Additional troubleshooting information can be found `here <https://docs.corda.net/getting-set-up-fault-finding.html#idea-issues>`_.
|
||||
|
||||
Git
|
||||
~~~
|
||||
|
||||
We use git to version-control Corda. Instructions on installing git can be found
|
||||
`here <https://git-scm.com/book/en/v2/Getting-Started-Installing-Git>`_.
|
||||
|
||||
Following these instructions will give you access to git via the command line. It can also be useful to control git via IDEA. Instructions
|
||||
for doing so 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.
|
||||
We use Gradle as the build tool for Corda. However, you do not need to install Gradle itself, as a wrapper is provided.
|
||||
|
||||
The wrapper can be run from the command line by using ``./gradlew [taskName]`` on OS X/Linux, or ``gradlew.bat [taskName]`` on Windows.
|
||||
|
||||
Corda source code
|
||||
-----------------
|
||||
|
||||
You can check out the Corda platform source code from this repository:
|
||||
The Corda platform source code is available here:
|
||||
|
||||
https://github.com/corda/corda.git
|
||||
|
||||
and a template app that you can use as a basis for experimenting with app development from:
|
||||
and a basic CorDapp that you can use as the basis for your own CorDapps is available here:
|
||||
|
||||
https://github.com/corda/cordapp-template.git
|
||||
|
||||
You can catch up with the latest code by selecting "VCS -> Update Project" in the IntelliJ menu.
|
||||
You can clone both of these repos to your local machine by running the command ``git clone [repo URL]``.
|
||||
|
||||
By default, both repos will be on the ``master`` branch. However, this is an unstable development branch. You should check
|
||||
out the latest milestone release (currently Milestone 7) instead by running ``git checkout release-M7``.
|
||||
|
||||
Troubleshooting
|
||||
---------------
|
||||
Opening Corda/CorDapps in IDEA
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
See :doc:`getting-set-up-fault-finding`, or get in touch with us either on the `forums <https://discourse.corda.net/>`_ or via `slack <http://slack.corda.net/>`_.
|
||||
When opening a Corda project for the first time from the IDEA splash screen, please click "Open" rather than "Import Project",
|
||||
and then import the Gradle project by clicking "Import Gradle project" in the popup bubble on the lower right-hand side of the screen.
|
||||
If you instead pick "Import Project" on the splash screen, a bug in IDEA will cause Corda's pre-packaged run configurations to be erased.
|
||||
|
||||
If you see this warning too late, that's not a problem - just use ``git checkout .idea/runConfiguration`` or the version control tab in
|
||||
IDEA to undelete the files.
|
||||
|
||||
IDEA's build of the project may need to be resynced from time to time. This can be done from within IDEA by going to "View" -> "Tool Windows" -> "Gradle"
|
||||
and clicking "Refresh all Gradle projects". Whenever prompted about Gradle, accept the defaults suggested by IDEA.
|
||||
|
||||
Next steps
|
||||
----------
|
||||
|
||||
The best way to check that everything is working fine is by :doc:`running-the-demos`.
|
||||
|
||||
Once you have these demos running, you may be interested in writing your own CorDapps, in which case you should refer to
|
||||
:doc:`tutorial-cordapp`.
|
||||
|
||||
If you encounter any issues, please see the :doc:`getting-set-up-fault-finding` page, or get in touch with us on the
|
||||
`forums <https://discourse.corda.net/>`_ or via `slack <http://slack.corda.net/>`_.
|
||||
@ -14,17 +14,18 @@ they become more familiar with Corda, readers with a technical background will a
|
||||
which describes the platform's envisioned end-state.
|
||||
|
||||
Corda is designed so that developers can easily extend its functionality by writing CorDapps
|
||||
(**Cor**\ da **D**\ istributed **App**\ lication\ **s**\ ). An example CorDapp is available on
|
||||
(**Cor**\ da **D**\ istributed **App**\ lication\ **s**\ ). Some example CorDapps are available in the Corda repo's
|
||||
`samples <https://github.com/corda/corda/tree/master/samples>`_ directory. To run these yourself, make
|
||||
sure you follow the instructions in :doc:`getting-set-up`, then go to
|
||||
:doc:`running-the-demos`.
|
||||
|
||||
If, after running the demos, you're interested in writing your own CorDapps, a template CorDapp is available on
|
||||
`Github <https://github.com/corda/cordapp-template>`_. To get it running, follow the instructions in the
|
||||
`readme <https://github.com/corda/cordapp-template/blob/master/README.md>`_, or watch the
|
||||
`Corda Developers Tutorial <https://vimeo.com/192797322/aab499b152>`_.
|
||||
|
||||
Additional CorDapp samples are available in the Corda repo's `samples <https://github.com/corda/corda/tree/master/samples>`_
|
||||
directory. These are sophisticated CorDapps that implement more complex functionality. You can find directions for
|
||||
running these samples `here <https://docs.corda.net/running-the-demos.html>`_.
|
||||
|
||||
From there, you'll be in a position to start extending the example CorDapp yourself (e.g. by writing new states, contracts,
|
||||
and/or flows). For this, you'll want to refer to this docsite, and to the `tutorials <https://docs.corda.net/#tutorials>`_
|
||||
and/or flows). For this, you'll want to refer to this docsite, and to the `tutorials <https://docs.corda.net/tutorial-contract.html>`_
|
||||
in particular. If you get stuck, get in touch on `Slack <https://slack.corda.net/>`_ or the `forum <https://discourse.corda.net/>`_.
|
||||
|
||||
Once you're familiar with Corda and CorDapp development, we'd encourage you to get involved in the development of the
|
||||
|
||||
Loading…
Reference in New Issue
Block a user