vorburger / opendaylight-eclipse-setup

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

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 ([email protected]) 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 [email protected] and/or [email protected] mailing lists, and comment and vote for it on that bugzilla issue.

How to get the sources of the setup model?

How to add new entries to the Project List?

How to add additional M2E lifecycle mapping?