Document recommended Eclipse IDE setup in root README.md

gitlab #524

Change-Id: I27a3596169117f5a32c522089de5bc394b0ea557

diff --git a/README.md b/README.md
index f5ede656849b70fdece241f396bc880208dd894f..3db0acbd12f1119983f6503f9bbf4a9a528eb6b6 100644 (file)
--- a/README.md
+++ b/README.md
@@ -1,20 +1,98 @@
-## IDE Setup
+## Headless Builds
 
-It is recommended to using the latest Eclipse IDEs.
+Official builds and testing of the platform are done with Maven.
+
+To build the platform, run:
+mvn package
+
+or to run unit tests as well:
+mvn verify
+
+## Development
+
+### Eclipse IDE Setup
+
+It is generally recommended to using the latest Eclipse IDE release.
+
+However, use of Eclipse IDE 2020-03 (4.15) release is not recommended
+because of [JDT bug 561338](https://bugs.eclipse.org/bugs/show_bug.cgi?id=561338).
+
+Therefore the current recommended versions are
+* 2019-12 (4.14)
+* 2020-06 (4.16) Milestone builds for the adventurous, which have the mentioned bug fixed.
+
+#### Install Eclipse IDE Plug-ins
 
 Two plug-ins need to be installed into the IDE from P2 repositories:
-1. Eclipse Target Platform Definition DSL and Generator from http://www.simantics.org/update/cbi/tpd/3.0.0-SNAPSHOT/
+
+1. Eclipse Target Platform Definition DSL and Generator from the P2 repository at http://www.simantics.org/update/cbi/tpd/3.0.0-SNAPSHOT/
    * Please read the detailed installation and basic use instructions
-     from [the tool's website](https://github.com/eclipse-cbi/targetplatform-dsl)
+     from [the tool's own GitHub site](https://github.com/eclipse-cbi/targetplatform-dsl)
 2. Simantics Graph Compiler plug-in from http://www.simantics.org/update/utils/
-   * Allows the IDE to compile `<bundle>/graph/*.pgraph` files
+   * Enables the IDE to compile `<bundle>/graph/*.pgraph` files
      into `<bundle>/graph.tg` for installation into Simantics database.
 
-## Building
+#### Install Required JDK
 
-To build the platform, run:
-mvn package
+This version of the platform requires at least JDK 11.
 
-or to run unit tests as well:
-mvn verify
+It is recommended to download the Hotspot variant from [AdoptOpenJDK.net](https://adoptopenjdk.net/?variant=openjdk11&jvmVariant=hotspot).
+You can also use newer JDKs but 11 as an LTS version is recommended, especially for bundling with built products.
+
+1. Download and install a compatible JDK version
+   * For Windows, download the `.msi` installer and install it
+2. Open IDE preference page **Java / Installed JREs**.
+   If the previously installed JDK is not already in use, add it as a *Standard VM*
+   installation to the list and select the added JRE as the active JRE.
+3. Open IDE preference page **Java / Installed JREs / Execution Environments**
+   and ensure that your selected JDK is selected in the *Compatible JREs* for `JavaSE-1.6` - `JavaSE-11`.
+
+#### Clone Repository into Eclipse
+
+Use [Eclipse Git Integration - EGit](https://wiki.eclipse.org/EGit/User_Guide) to clone repositories.
+
+##### gerrit.simantics.org
+
+Gerrit is currently still the authoritative repository for the platform, so use the following for now
+
+Anonymous HTTP cloning without push rights:
+
+    git clone "https://gerrit.simantics.org/r/simantics/platform"
+
+Developers with push access:
+
+    git clone "ssh://lehtonen@gerrit.simantics.org:29418/simantics/platform"
+
+##### gitlab.simantics.org
+
+GitLab will become the authoritative repository for the platform in the future.
+Until then, please do not push directly to this repository.
+
+Just follow GitLab's cloning instructions at https://gitlab.simantics.org/simantics/platform.
+Use HTTP cloning for anonymous access and SSH for developer access.
+
+#### Import Projects into Workspace
+
+From the main menu, uncheck *Build Automatically* from the *Project*
+menu to prevent unnecessary build failures from happening before the
+setup is complete.
+
+From the *Git Repositories* view in Eclipse, choose *Import Projects* from the repository context menu.
+Import all projects into their own working set.
+
+#### Set Target Platform
+
+To get the platform to compile in the IDE, you will need to use one of the custom target platforms
+provided [releng/org.simantics.sdk.build.targetdefinition/](releng/org.simantics.sdk.build.targetdefinition).
+
+To use a minimal target platform, open [releng/org.simantics.sdk.build.targetdefinition/org.simantics.sdk.build.targetdefinition.tpd](releng/org.simantics.sdk.build.targetdefinition/org.simantics.sdk.build.targetdefinition.tpd)
+using the *Target Platform DSL Editor* and press `CTRL+R` in the editor to
+re-build the corresponding .target file and set it as the current platform.
+
+Re-enable *Build Automatically* from the *Project* main menu to start the build
+which should now succeed.
+
+#### Test
 
+Open [releng/org.simantics.desktop.rcp.product/simantics-desktop.product](releng/org.simantics.desktop.rcp.product/simantics-desktop.product)
+and press `Launch an Eclipse application in Debug mode`. The basic desktop product should start.
\ No newline at end of file