If you like/use this project, a Star / Watch / Follow me on GitHub is appreciated.

Watch https://www.youtube.com/watch?v=BLW8aOh6WeQ screencast video to see what this is all about.

Watch https://www.youtube.com/watch?v=TU1zjytlwFE recording of presentation from OpenDaylight Mini Summit June 2016. Slides from this session are also available here http://www.slideshare.net/mikervorburger/opendaylight-developers-experience-15-eclipse-setup-hot-reload-future-plans (faster) and (in better quality) here https://docs.google.com/presentation/d/14yLzog3OhIlVsk7Clr0Tff1YayRcFnQCUZqxHMWxiNI/.

OpenDaylight has Oomph, and you can set up an Eclipse-based development workspace for OpenDaylight projects by:

1. Downloading the Eclipse Installer from https://www.eclipse.org/downloads/ and clicking "Get Eclipse [Neon] Download 64 bit", unzipping eclipse-inst-* and starting it. (Alternatively the same, perhaps in a slightly more up-to-date version, is available from https://wiki.eclipse.org/Eclipse_Installer as well.)

2. On the initial page, click on the Switch to advanced mode button in the top right.

3. On the Product page, select Eclipse IDE for Java Developers.

4. On the Projects page, collapse the Eclipse Projects & GitHub Projects to scroll down to the OpenDaylight.org Projects (or use the "Select Catalogs" icon in the upper right hand corner for permanent filtering)

5. Double-click the projects (i.e. ODL repos) of interest to you.

6. Choose your installation settings on the Variables page, incl. your OpenDaylight.org username to access gerrit and a root install directory location for the workspace (projects Git repo can be elsewhere, see below)

7. Finish the wizard and watch how your development environment is being assembled, courtesy of Oomph.

This fully automates the manual steps currently described on https://wiki.opendaylight.org/view/GettingStarted:_Eclipse, in order for anyone to get easily started successfully hacking on https://www.opendaylight.org quickly, without having any red problem markers.

This is implemented used an Eclipse "Oomph" workspace set up model, see http://www.eclipse.org/oomph

By default, it will git clone the repos of all projects you clicked into your new ${installation.location/git}. If you already have OpenDaylight projects git clone with existing local work, then simply on the "Variables" step of the Eclipse Installer, click [X] Show all variables, and replace the "Git clone location:" variable which defaults to "${installation.location/git/}${@id.remoteURI|gitRepository}" by something like "/absolute/path/where/you/keep/your/opendaylight/clones/${@id.remoteURI|gitRepository}".

Similarly, if for some reason you prefer a non-standard directory layout setup with custom directories instead of Oomph’s default git/, ws/ and eclipse/ directories, this can be changed during setup on the "Variables" step by clicking [X] Show all variables.

In order to be able to propose changes to OpenDaylight via Gerrit, you’ll of couse still need to your SSH public key to the ODL Gerrit account. Note that this setup currently does the git clone via ssh:// not via https:// Git protocol. (If this is a problem for you perhaps because from behing a corporate firewall you can also do git with HTTP but not SSH, then please raise bring it up on the odl-parent mailing list, as it would be possible to improve this.)

To import more projects after completing the wizard, click on the "Perform Setup Tasks" yellow/blue circle arrows kind of icon in the Toolbar, next to the little blue man icon, and choose "Import Projects…​". If those two icons are not visible in your toolbar, enable them using menu Window > Preferences > Oomph > Setup Tasks: [X] Show Toolbar contributions.

This work was started on https://github.com/vorburger/opendaylight-eclipse-setup just because it’s easier for me to maintain it here for now. As other ODL developers use this, perhaps we’ll move it to https://git.opendaylight.org. TODO which repo, new or inside an existing one?

Michael Vorburger @ work @ Red Hat April 2016

What exactly this actually does

Provision an Eclipse installation which includes:

• a few required and useful customizations of the eclipse.ini (notably -Xmx)

• some custom Preferences, including: Organize Import, Auto Save actions, Java & XML Formatter, EGit Signed off, etc.

• pre-installing the appropriate versions of the following useful Eclipse plugins:

  • https://www.eclipse.org/xtend/

  • https://wiki.eclipse.org/Linux_Tools_Project/Docker_Tooling/User_Guide

  • https://wiki.eclipse.org/Linux_Tools_Project/Vagrant_Tooling/User_Guide

  • http://eclipse-cs.sourceforge.net

  • http://findbugs.sourceforge.net

  • https://pmd.github.io

  • http://eclemma.org

  • https://www.eclipse.org/egerrit/

  • https://github.com/oyse/yedit YAML Editor (until it’s part of Eclipse)

  • https://infinitest.github.io/

  • https://wiki.eclipse.org/Mylyn/WikiText/AsciiDoc

  • http://resteditor.sourceforge.net

  • http://andrei.gmxhome.de/anyedit/ with configuration Remove trailing whitespace for all text files, not just *.java, as enforced by ODL Checkstyle; core Eclipse Platform Text lacks this, see (bug 180349

  • https://github.com/heeckhau/mousefeed (NOTE heeckhau/mousefeed#4)

In particular the M2Eclipse (M2) Maven Eclipse integration PITA is correctly configured with:

• settings.xml for nexus.opendaylight.org

• an appropriate lifecycle-mapping-metadata.xml for M2E

• all required M2E connector plugins (buildhelper, m2e-code-quality, mavendev, tycho, m2e-apt incl. config)

• M2E Auto Update preference

• Checkstyle gets configured, in line with Maven (it actually automatically reads the ODL Checkstyle configuration from the respective JAR in the local m2 repo; see Project > Properties > Checkstyle > Local Check Configurations tab)

Then for each of the available ~80+ ODL repos you wish to import via the Wizard UI it does:

• git clone

• EGit Gerrit configuration

• Import Maven Projects

• Working Set

Specific setup actions required by particular projects:

• yangide: m2e.sdk, EMF Compare, Graphiti in Target Platform

• eclipse-setup: Oomph redirect to be able to work on the live *.setup in workspace

FAQ

1. Where can I get support if I have any further question not covered in this README?

   For now, please post to the general OpenDaylight development list (dev@lists.opendaylight.org) with email subject topic prefix "[eclipse]".

2. Why do I not see the "Projects" lists, only the "Product" selection?

   Switch the Advanced Mode, and Click Next; watch https://youtu.be/BLW8aOh6WeQ?t=1m42s

3. Why do I not see OpenDaylight.org in the Projects lists, only the Eclipse & GitHub Projects?

   Use the "Select Catalogs" icon in the upper right hand corner, OpenDaylight may be filtered.

4. What to do when getting installation ERRORS such as "org.eclipse.equinox.p2.transport.ecf code=1002 Unable to read repository at http://…​" with "org.apache.http.conn.ConnectTimeoutException: Connect to …​ timed out", or the Installer gets "stuck" in the "P2 Director, Adding repository", etc.

   These are "just" network connection issues which can happen when it’s downloading the additional Eclipse plugins that are required. Normally just retrying (by Cancel Operation, Back, Finish again), or waiting and retrying later, fixes all of these. If you have managed to previously have it already successfully install the required Eclipse plugins at least once, then you can often still proceed in the face of such errors simply by clicking the Offline icon on the toolbar, or by un-checking the P2 Director task in the "tasks to be executed and optionally uncheck unwanted tasks" pop-up confirmation dialog. Also if it ever asks you something like "Can’t reach …​ use locally cached version?", say Yes.

5. Why doesn’t the SonarCube (SonarLint) plugin show the same problems in Eclipse as on the https://sonar.opendaylight.org web UI?

   It does - IFF you right-click project(s) to "Bind to a SonarCube project" AND then touch a Java file or rebuild the project!

6. Wouldn’t it be better to disable automatic rebuilding?

   No, because then when switching branches the Java index used for validation and autocompletion would be out-of-date.

7. Automatic workspace building is slow.

   There is probably room for improvement, likely more so in Builders of 3rd party plugins than core Eclipse, e.g. yangide, checkstyle etc. Contributions which performance profile these and help with improvements those projects improve their performance are certainly highly welcome.

8. Why do I have to do "mvn install" to make red ink go away after I switch branches?

   You should not have to. E.g. the yangide plugin is included here so that it would auto. regen. the Java code in line with changes to YANG e.g. from branch switching. If this does not work in your project, please let me know so that we can look at what needs to be changes. Most likely, it’s a left over wrong M2E lifecycle mapping which suppresses the intended and automatic re-generation which is working on other projects.

Known open issues causing red in opendaylight Eclipse workspace

Until the Gerrits listed below get merged, you can locally work around these problems by pulling the listed Gerrit changes into your workspace. You do not need to mvn install, because M2E "workspace resolution" will make the changes immediately effective.

Cross projects, affecting all

• The very first time Eclipse opens, you’ll have to File > Restart it once. This is because the automated Preference which Oomph applies so that it uses nexus.opendaylight.org instead of Maven central has only just been configured, and M2E didn’t automatically pick it up.

• The "javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target" error while fetching url https://nexus.opendaylight.org/content/sites/p2repos/org.opendaylight.yangide/snapshot/content.xml: You have been hit by https://bugs.opendaylight.org/show_bug.cgi?id=5806. It appears that OpenJDK does not have this problem; it’s specific to Oracle JDK. You can also try to import the respective CA cert into your store as described e.g. https://bugs.eclipse.org/bugs/show_bug.cgi?id=492014#c1 and in other places online, if you are up for it. The only other thing I can do is encourage you to whine about that issue on e.g. the integration-dev@lists.opendaylight.org and/or dev@lists.opendaylight.org mailing lists, and comment and vote for it on that bugzilla issue.

• YANG code generation does not seem to always automatically correctly incrementally rebuild Java sources from YANG (e.g. when switching branches). For now, just manually right-click > Run As > Maven Generate Sources does the trick in cases where you have red errors due to YANG code.

• Checkstyle

  • OpenDaylight custom Checkstyle checks from org.opendaylight.yangtools.checkstyle-logging (used e.g. in AAA) cause issues; need to either write a new Eclipse plugin just for that (urgh), or contribute https://sourceforge.net/p/eclipse-cs/feature-requests/159/.

  • version of Checkstyle JAR used in Maven and Eclipse plug-in will have to be kept matching (unless https://sourceforge.net/p/eclipse-cs/feature-requests/158/ is ever implemented)

Implementation

Project List

To add a new project, just:

1. choose "eclipse-setup" in the Setup Wizard project list (it’s a project like any other ODL project)

2. edit generator/projects.txt

3. run ProjectsSetupGenerator.xtend

4. edit org.opendaylight.projects.setup to add the new <project href=".."> printed out by ProjectsSetupGenerator.xtend

5. test importing your new project, as described in "To import more projects.." above. Note that due to an automated redirect that was set up when you provisioned the "eclipse-setup" project, the *.setup models in your workspace are "live", and Oomph will use those models instead of the remote one - perfect for local testing.

Please note that the projects/*.setup are auto-generated by the generator/src/../ProjectsSetupGenerator.xtend, based on the generator/projects.txt list.

Those projects/*.setup models should thus never be hand-edited (contrary to the root org.opendaylight.projects.setup); instead fix the template in the ProjectsSetupGenerator if anything could be improved, and re-run the generator.