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 (Berlin). 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/. — Related more recent slides from the OpenDaylight Summit October 2016 (Seattle) are available here http://www.slideshare.net/mikervorburger/opendaylight-developer-experience-20 (faster) and (in better quality) here https://docs.google.com/presentation/d/1bnwj8CrFGo5KekONYSeIHySdkoXZiewJxkHcZjXnzkQ/.

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 checked into a sub-directory named "git/" next to the eclipse/ folder (${installation.location}). If you already have OpenDaylight projects git clone’d with existing local work, then on the "Variables" step of the Eclipse Installer, simply change the git.clone.opendaylight.ROOT.location variable to /absolute/path/where/you/keep/your/opendaylight/clones/. Use [X] Show all variables if that variable is not displayed.

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://github.com/m2e-code-quality/m2e-code-quality

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

  • https://wiki.eclipse.org/Linux_Tools_Project/Docker_Tooling/User_Guide - removed due to p2 issues

  • https://wiki.eclipse.org/Linux_Tools_Project/Vagrant_Tooling/User_Guide - removed due to p2 issues

  • 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. Why do I get "…​ Cannot access opendaylight-snapshot (https://nexus.opendaylight.org/content/repositories/opendaylight.snapshot/) in offline mode …​" ?

   Since the menu Window > Preferences > Maven > Offline was enabled by default (which was done to save you constant daily re-downloads of hundreds of the very latest bleeding edge ODL SNAPSHOTS JARs), you’ll have to right-click projects to do Maven > Update Projects (Alt-F5) for an explicit one-time uncheck Offline and Update Dependencies. (Alternatively, you could also do a CLI mvn build to get the JARs, but you don’t have to and can let Eclipse M2E do it, via Update Projects.)

5. Why do I get "…​ Cannot access central (https://repo.maven.apache.org/maven2) in offline mode and the artifact org.opendaylight.odlparent:odlparent-lite:pom:3.0.2 has not been downloaded from it before. and 'parent.relativePath' points at no local POM." ?

   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 http://nexus.opendaylight.org instead of Maven central has only just been configured, and M2E didn’t automatically pick it up. You then need to make it go online once, see previous question.

6. Why do I still see the problems with dependencies from the two questions above, after I have done what those answer suggest?

   Switch to (first) do a CLI mvn build to get the JARs, and when you have that working then look at getting the code into Eclipse. Follow https://docs.opendaylight.org/en/latest/developer-guide/developing-apps-on-the-opendaylight-controller.html to set up the settings.xml. Then use "mvn -Pq,ide clean install".

7. Why do I still see red compilation errors for YANG generated code that could not be found, even though I did mvn -Pq clean generate-sources on the CLI?

   Since the introduction of the target-ide/ folder to completely separate the CLI and the Eclipse IDE build (required because the two would step onto each others feet, look JARs, etc. so better to keep them separate), when you do e.g. a mvn -Pq clean generate-sources (the -Pq is for the "quick" profile and skips a bunch of things to make your local build faster) it will generate code in target/generated-sources, but Eclipse will look in target-ide/generated-sources. Use mvn -Pq,ide clean generate-sources to activate the Maven "ide" profile to generate code into target-ide/ instead of target/.

8. Why do I still see red compilation errors for YANG generated code, even though I did mvn -Pq,ide clean generate-sources ?

   Note that you obviously have to do this on the project you want to work on, as well as on any other projects open in the workspace with YANG gen. code which your project you’re working with depends on.

9. What do to when "Running Checkstyle audit on…​" hits "File not found: /home/YOU/.m2/repository/org/opendaylight/odlparent/checkstyle/3.0.2/checkstyle-3.0.2.jar (No such file or directory)" ?

   The Checkstyle Eclipse plugin does not download the ODL Checkstyle configuration from nexus.opendaylight.org, but only looks in ~/.m2. After your very first run of something like a mvn -Pq clean install on the CLI, then that will be there.

10. What to do when hitting "An internal error occured during: Updating Maven Project" ?

    These problems typically mean that one of the many Maven plugins used in ODL failed to run in M2E, or they are bugs in M2E (see below for one specific example). First, it’s best is to close all projects in the workspace you don’t really need to actively work on. Then first retry a Maven > Update Project, and/or Project > Clean to see if it’s reproducible. If it’s one time or only sporadic, then simply ignore such errors, as they are not blocking you (M2E is not perfect). If they are blocking you, it may be possible for us to de-activate the respective Maven plugin from running in ODL through a "lifecycle mapping". Please open the Error Log view in Eclipse, and copy/paste the details of the respective error (or even just attach an export of your entire Eclipse log) in an email to the mailing list mentioned in the first QA, also specifying which specific ODL projects you saw this in.

11. 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.

12. What to do when getting ERROR: org.eclipse.equinox.p2.director code=0 Missing requirement: artificial_root 1.0.0.v1498559525446 requires 'epp.package.java [4.7.0,5.0.0)' but it could not be found

    According to https://lists.opendaylight.org/pipermail/dev/2017-June/003867.html, this happens when you check some of the "Additional optional .. plugins …​ for OpenDaylight .." and using Eclipse Oxygen - please try to uncheck those optional plugins.

13. What to do when getting ERROR: org.eclipse.equinox.p2.director code=10053 Cannot complete the install because one or more required items could not be found. ERROR: org.eclipse.equinox.p2.director code=0 Missing requirement: artificial_root requires 'net.sf.eclipsecs.feature.group 0.0.0' but it could not be found

    First see the previous QA just above. Furthermore, this particular error means that it could not download a required Eclipse plugin from its p2 update site (for example the Checkstyle Eclipse plugin). You can find the exact URLs used in the list of <repository> in the org.opendaylight.projects.setup file (for example http://eclipse-cs.sf.net/update). If that’s up & reachable for you now, but it may have had a temporary connection issue when you first tried - just retry, a few times. If the errors persists, perhaps you are behind a corporate or university firewall which blocks some access to/download (e.g. from sf.net) ?

14. How can I do a completely fresh new install?

    Delete both your ~/.p2 and existing installation directory (where it put the eclipse/ folder), and do NOT check the option to run Offline.

15. What if I’ve done all of above and am STILL struggling with the issue shown above related to the Checkstyle (net.sf.eclipsecs) plugin?

    You may have hit the known HTTPS issue for sourceforge.net hosted p2 update sites, related to different SSL root certificates being included in different versions of OS and JDK; see https://sourceforge.net/p/eclipse-cs/feature-requests/168/ and https://sourceforge.net/p/eclipse-cs/discussion/274377/thread/5147e726/#42c5 and https://sourceforge.net/p/eclipse-cs/discussion/274377/thread/5147e726/#f363 …​ So to solve this, you have to either (a) update your OS and/or Java version to very latest available; (b) switch from Oracle JDK to OpenJDK! (c) manually tweak your JCE configuration (best of luck).

16. What does this mean, and how can I fix / work around it: org.apache.maven.plugin.PluginContainerException: Unable to load the mojo '…​' (or one of its required components) from the plugin '…​' Caused by: org.codehaus.plexus.component.repository.exception.ComponentLookupException: java.util.NoSuchElementException role: org.apache.maven.plugin.Mojo Caused by: java.util.NoSuchElementException at org.eclipse.sisu.plexus.RealmFilteredBeans$FilteredItr.next(RealmFilteredBeans.java:118) ?

    You’ve hit an M2E bug (bugs.eclipse.org #496944). It’s some concurrency issue, and retrying 2-3 times, maybe Eclipse restart, usually makes it go away. Note that this can happen both initially from the Eclipse Installer (Oomph), as well as later during regular coding in the Eclipse IDE. In the case of this happening during the initial setup from Eclipse Installer (Oomph), you retry what it was doing by using the <Back button at the bottom of the wizard to go back to the previous step and do Next> again. In case this happens during later regular use of the full Eclipse IDE, you just do whatever operation you did causing it again (typically e.g. Maven > Update Project, or Project > Clean if you use that, etc.)

17. What do do if the Dynamic Working Sets which automatically split projects into *-build and *-code got messed up because you closed & re-opened some projects?

    Use menu Window > Preferences > Oomph > Dynamic Working Sets > Apply.

18. What do I have to do if I’m on a corporate/universite campus network behind an HTTP Proxy which limits full internet access?

    Note that even if you can access remote Eclipse plugin p2 update sites, such as http://eclipse-cs.sf.net, from your Web Browser, the Eclipse Installer and the Eclipse IDE may still not be able to, if it’s not aware of your HTTP Proxy. The easiest is to go use a network without HTTP proxy (e.g. try from home). Otherwise you can also in the Eclipse Installer, use the "Network Proxy Settings", available as the 2nd icon after the Help icon in the lower left hand corner of all screens of the main wizard steps UI. In the full Eclipse IDE, once it installed, use menu Window > Preferences > General > Network Connections.

19. 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!

20. 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.

21. 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.

22. Do I still have to do at least mvn -Pq,ide clean generate-sources or even a full mvn -Pq,ide clean install to make red ink go away after I switch branches?

    Yes, you do. See the question above. (We originally hoped to be able to auto. regen. the Java code in line with changes to YANG e.g. from branch switching, but this does not yet work.)

23. Why could there be Checkstyle discrepancies between the CLI mvn build VS in Eclipse?

    The 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). Also the Checkstyle Eclipse plug-in cannot deal with custom Checkstyle checks (unless they are packaged into an Eclipse plug-in), see https://sourceforge.net/p/eclipse-cs/feature-requests/159/. In practice this should not be an issue for ODL, because e.g. the OpenDaylight custom org.opendaylight.yangtools.checkstyle-logging checks are, intentionally not widely used; we use FindBugs via https://git.opendaylight.org/gerrit/#/c/66449/ for the same.

24. What’s 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" ?

    You may have been hit by a reincarnation of https://bugs.opendaylight.org/show_bug.cgi?id=5806. It appears that OpenJDK does not have this problem; it’s specific to older versions of Oracle JDK Java 8 < 8u101. Please upgrade to either OpenJDK (recommended if you are on Linux) or latest Oracle JDK 8u131 or more recent (easier if you are on Windows). You could 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.

Implementation Details for Contributors

How to get the sources of the setup model?

There is a entry named "eclipse-setup" in the projects list; that will provision the source code of this into your workspace so that you can contribute to it.

See "To import more projects after completing the wizard (…​)" above re. how to import additional projects into your workspace.

How to add new entries to the 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.

How to add additional M2E lifecycle mapping?

If needed, add the Repository and the Requirement (Eclipse feature) of the additional new M2E Extension / Connector to the P2 Director in the org.opendaylight.projects.setup.

Then optionally, if applicable, engage a Quick Fix for the red "Plugin execution not covered by lifecycle configuration: (…​)" Problem and have it "Mark goal (..) as ignored in eclipse preferences" (NOT in pom.xml)

Now use menu Window > Preferences > Maven > Lifecycle Mappings > Open workspace lifecycle mappings metadata to copy the contents of your entire current latest lifecycle-mapping-metadata.xml file to the clipboard, and paste that into the Content in the Properties of the Resource Creation task for ${workspace.location|uri}/.metadata/.plugins/org.eclipse.m2e.core/lifecycle-mapping-metadata.xml in the org.opendaylight.projects.setup.

Then commit, and raise Pull Request to share the change.