Jump to: navigation, search

GettingStarted: Eclipse

These instructions should enable you to not only use the CLI to pull and push to the git repository, but hack on code from Eclipse.

NEW: Fully automated opendaylight-eclipse-setup based on Eclipse Installer (Oomph)

You will now probably want to use the new fully automated opendaylight-eclipse-setup based on Eclipse Installer (Oomph) from https://github.com/vorburger/opendaylight-eclipse-setup instead of following the manual instructions listed on this page. Watch this https://www.youtube.com/watch?v=BLW8aOh6WeQ video to see what it is all about.

OLD: Manual procedure previously used

Introduction

Eclipse is an IDE (Integrated Development Environment) which provides a single pane of glass for developing and debugging source code, and is a framework for building, deploying and managing software across the software lifecycle.

At present only the following projects have been validated to import into Eclipse without compile errors:

  • Controller
  • OpenflowPlugin

The remaining projects have not yet been modified to play nice with Eclipse.


Quick Start / Useful Tips

  • Ctrl + Shift + T opens a window that allows you to search for any java class.
  • Ctrl + Shift + R opens a window that allows you to search for any resource.
  • Window->Preferences provides a large number of customization options including use spaces for tabs, line numbers, etc. (On Mac it is Eclipse->Preferences).

Installing Eclipse

Go to the Eclipse Website and download Eclipse Java Developers Edition if you haven't already. The Developers Edition version comes with all the Git tools, which is not included in the Classic version.

WARNING: If you use Ubuntu, see Installing Eclipse on Ubuntu. If you try to install eclipse manually (as stated in these instructions) you may end up in a situation in which it seens to not work or to work erratically. For example the menu may fail to integrate with Ubuntu's window manager properly.

  1. Make sure you have a Java 1.7 or 1.8 JDK installed.
  2. Download the Eclipse package ("for Java EE Developers", "for Java Developers" and "for RCP and RAP Developers" all seem to work) and extract it into your home directory.
  3. Increase the memory for the Eclipse installation by modifying the eclipse.ini file in the same directory as the eclipse executable.
    • Change the -Xmx setting to be AT least 1G, recommended 2GB. (i.e. -Xmx2048m ). Note: This file may be in a different location depending on your OS. Refer to eclipse documentation if you don't see the file.
    • Also change the PermGen space (-XX:MaxPermSize) to be at least 512MB, i.e., -XX:MaxPermSize=512m. If you are only using 1 GB for max memory, then I would suggest 300 MB to start for PermSize.
  4. (not required if you use Eclipse Luna) Install Eclipse Maven Integration
    1. From Eclipse, go to Help => Install New Software...
    2. Paste "http://download.eclipse.org/technology/m2e/releases" into the "Work with:" field
    3. Select m2e and (optionally) m2e - slf4j both (1.4.0 is current as of the writing of these instructions)
    4. Click Next, OK and Finish else until things install
    5. Restart Eclipse when it asks
  5. Install Eclipse Tycho integration
    1. From Eclipse, go to Help => Install New Software...
    2. Paste http://repo1.maven.org/maven2/.m2e/connectors/m2eclipse-tycho/0.7.0/N/0.7.0.201309291400/ into the "Work with:" field.
    3. Select the Tycho Project Configurators. Click Next, OK, Finish etc until it installs (ignore the unsigned content warning by clicking "OK" in the form).
    4. Restart Eclipse when it asks.
  6. Install the build-helper-maven plugin (this allows eclipse to see yang/xtend generated directories as source folders)
    1. From Eclipse, go to Windows => Preferences, expand the Maven folder and select Discovery.
    2. In the right panel, click 'Open Catalog'.
    3. Type 'build' in he Find box to filter the list.
    4. You should see 'buildhelper' listed. Select it and click Finish.
    5. Click Next in the following 2 panels, accept the license terms and click Finish (ignore the unsigned content warning by clicking "OK" in the form).
    6. Restart Eclipse when it asks.

If you are planning to import the YANG Tools project, also take the following steps:

  1. Install the Eclipse Xtend plugin
    1. From Eclipse, go to Help => Install New Software...
    2. Paste "http://download.eclipse.org/modeling/tmf/xtext/updates/composite/releases" into the "Work with:" field
    3. Click Next, OK and Finish else until things install
    4. Restart Eclipse when it asks
      • If you still have issues after install the plugin, you might try:
        1. When installing the xtend plugin, uncheck "Show only the latest versions of available software" and "Group items by category", if necessary.
        2. Select Xtend SDK 2.4.3.XXX and Xtend M2E extensions 2.4.3.XXX
          There are newer versions, however some users have reported having issues with newer versions.
  2. Install Groovy plugin
    1. From Eclipse, go to Help => About, and note what eclipse version you have (4,4, 4.3, 4.2 etc).
    2. From Eclipse, go to Help => Install New Software...
    3. In the "Work with:" field, paste http://dist.springsource.org/release/GRECLIPSE/e4.4 and hit Enter. Note: if you have an earlier eclipse version, change 4.4 to that version, e.g http://dist.springsource.org/release/GRECLIPSE/e4.3 for version 4.3
    4. Select 'Groovy-Eclipse' and 'm2e Confgurator for Groovy-Eclipse' to install.
    5. Click Next, accept the license terms and click Finish.
    6. Restart Eclipse when it asks.

Automatically Avoiding Trailing Whitespace

OpenDaylight (at least in the controller project) will refuse to compile code which has trailing whitespaces in in. Eclipse can be configured to automatically eliminate them for Java files.

  1. Go to Window => Preferences (or "Eclipse => Preferences" on a Mac), expand Java => Editor and click "Save Actions"
  2. check "Perform the selected actions on save" and "Additional actions", but uncheck the rest
  3. click "Configure..." next to the additional actions (expand the form's window if you don't see the button).
  4. Check "Remove trailing whitespace" and "All lines" on the first tab ("Code Organizing"), uncheck everything else on the other tabs
    • (at the bottom of the form you should see "1 of 27 save actions activated"; the "1" in the message is important, the "27" can differ if not in version 4.4).
    • (while the other save actions in the "1" part are likely harmless, they will result in spurious changes if you save files that other people created without those options)

Automatically Using Spaces instead of Tabs

  1. Go to Preferences
  2. Go to Java => Code Style => Formatter
  3. Click "edit" next to the "Active Profile"
  4. Go to the "Indentation" tab
  5. Change the tab policy to "Spaces only"
  6. Click OK

See also the Best Practices: Coding Guidelines (Java) page.

Eclipse Maven Integration (m2e) version

Previously, there were issues with m2e 1.3 and we recommended using 1.2, but those issues have been fixed and everything should works as expected with the most recent m2e version, 1.4.

Importing the Source Into Eclipse

  1. Pull the code from the command line and build it with these instructions. The short version is:
    1. Pull the code: git clone ssh://<username>@git.opendaylight.org:29418/controller.git
    2. Build the code: cd controller && MAVEN_OPTS="-Xmx2048m -XX:MaxPermSize=512m" mvn clean install You can also build from opendaylight/distribution/opendaylight, but it just builds the distribution as opposed to building everything
      The long version is available here GettingStarted:Pulling,_Hacking,_and_Pushing_All_the_Code_from_the_CLI.
    3. Incase you face issues with Non-Resolvable POM Parent Error while compiling, you can check whether you have settings.xml properly configured as mentioned in below link (See Edit ~/ml2/settings.xml section)

https://wiki.opendaylight.org/view/GettingStarted:Development_Environment_Setup#Edit_your_.7E.2F.m2.2Fsettings.xml

  1. Import all of the OpenDaylight projects into eclipse
    1. From Eclipse, go to File => Import => Maven => Existing Maven Projects
    2. Browse to the root directory of the git repository
    3. All of the projects should be selected by default, just click Finish
    4. It may ask you to install Tycho, do so if it asks (This should be a 1 time deal. Make sure you have enough memory allocated otherwise it can cause Eclipse to hang and eventually crash)
    5. It may also complain about jacoco, you should be able to ignore those errors

Help - I still have Red X's! (i.e. Eclipse compile errors)

Eclipse is no longer able to compile OpenDayLight. The reason is three maven plugins which are used by OpenDayLight but are not integrated into Eclipse: maven-plugin-plugin, karaf-maven-plugin and maven-antrun-plugin. This means you will always have Eclipse compile errors in the project (this could go to up to 100000 errors).

You can use Eclipse for editing easily but to compile the project you need to open a terminal window and do the compilation according to the instructions from OpenDaylight Controller:Pulling, Hacking, and Pushing the Code from the CLI or GettingStarted:Pulling, Hacking, and Pushing All the Code from the CLI. If you want to debug the code, you need to do it remotely as described in the next section.

Debugging the Controller

As it is no longer possible to build OpenDayLight cleanly in Eclipse, the only way to debug it is to use remote debugging. If you attempt to run or debug OpenDayLight from Eclipse, you will end up with a build failure reporting over 100000 errors and most likely run out of memory as well.

Attaching the Debugger to a Running ODL

Using Eclipse you can debug a locally running, or a remote running controller. Thankfully, the way you do either debugging is the same. First you start ODL with a debug flag, and then you tell Eclipse to attach to the running application via IP. If it is a local instance, use localhost, otherwise provide the hostname or IP address of the remote server!

To remotely debug the controller you first need to start ODL with the -debug flag, or just debug since Helium release.

  1. Start the controller with the -debug flag passed to the run.sh script.
    ./run.sh -debug   
    This starts the controller, opening up port 8000 for debugging.
    Since Helium, start the controller with the debug flag passed to the karaf.sh script.
    ./karaf.sh debug 
    This starts the controller, opening up port 5005 for debugging.
  2. In Eclipse choose Run->"Debug Configurations"
    • Under "Remote Java Application" choose a standard connection type, and enter the hostname (localhost or remote controller name) and port (8000 by default).
    • Under the "Source" tab click "Add" and then "Java Project". This will give you a list of all java projects in the workspace. Select them all and click OK a few times to close out of the dialogs.
      Note: this should only be required once per debug configuration.
    • Click debug to launch the debugger.

Debugging a Start Up Issue

Sometimes it is necessary to debug an issue that only occurs at start-up. If thats the case, the above technique can be frustrating because it becomes a race condition between you and the start up process! Thankfully there is a way you can start ODL, but pause any initialization code until a debugger is attached! To do this, start ODL using the -debugsuspend flag.

./run.sh -debugsuspend

This starts the controller, but pauses before any initialization code is run. Additionally it opens port 8000 for debugging. In order for ODL to start up now you MUST connect a debugger remotely, using the same process defined above.

Debugging Weird Errors

If Eclipse starts giving you lots of weird errors that seem to make no sense, try the following things:

  1. right click on the project with the issue and go to Maven => Update Project... and then press OK
    • You can do this more easily by creating a single "Java Working Set" for all of the OpenDaylight projects
    • Do that by going File => New => Java Working Set and giving it a name and adding all the projects you want
    • When you're importing Maven projects into Eclipse, you can also check the "Add project(s) to working set" box at the bottom of the dialog and pick the working set you're using for OpenDaylight
    • Then you can right-click on the project and do the Maven = Update Project... on all of them at once
  2. If that doesn't work closing, deleting and the reimporting all of the OpenDaylight projects seems to help when nothing else does
    • while you have the projects not imported into Eclipse, it doesn't hurt to do a build from the CLI as well


Frequent gotchas

  • eclipse needs to setup a classpath variable M2_REPO pointing to local repository. Can be done manually or via
    mvn -Declipse.workspace=<path-to-eclipse-workspace> eclipse:add-maven-repo
  • some projects miss maven-compiler-plugin configuration and render into java 1.4 compliant settings - you need to change that manually in eclipse or fix corresponding pom
  • when running eclipse:eclipse upon parent pom which aggregates modules, then in eclipse these modules will "see" each other in workspace. If you change code on project A, eclipse will recompile it and new stuff is immediately available to project B (having the same parent). Anyway workspace dependencies in eclipse can be set or removed manually anytime.
  • when running eclipse:eclipse upon bottom project pom, where no modules resides, eclipse will see it after import as independent project having all dependencies pointed to local repo
  • when using pax-exam you need to install touched artifacts into local repo in order for pax-exam to put updated version on classpath
  • by default maven updates every SNAPSHOT dependency every 24 hours, so if you need stable environment do not forget to use -nsu switch

Advantages

  • if you want to freeze all SNAPSHOT dependencies, use -nsu (no snapshot update) switch or -o (offline)
  • if you want to update all SNAPSHOT dependencies, use -U switch
  • if you want to build only a subset of projects contained in parent pom, use this (maven will take care of build order)
    mvn clean install -pl <relative_path_to_subproject1>,<relative_path_to_subproject2>..
  • if you want to continue a failed build (after fixing it) when having many modules, use this
    mvn clean install -rf <relative_path_to_broken_broject>
  • you can apply remote debug on everything you have source code of (including plugins), just use mvnDebug
  • to run test from commandline use
    mvn test
    mvn test -Dtest=<testName_without_package>
    mvn test -Dtest=<testName_without_package>#<methodName>
  • if everything fails, use -X to see TRACE output

And as all these are shell commands, you are free to chain them (with ; || && &) and automate your work a bit:

mvn clean compile -DskipTests && cd target/longPathToDistribution; aplay <funnyNoise.wav> > /dev/null & ./run.bat -debug; cd -

Alternative way without m2eclipse plugin - for CLI-fans

Sometimes m2eclipse plugin does weird things like compiling in infinite loop, updating dependencies when they need to be frozen and the other way around. If you want to omit m2eclipse plugin completely, you can. Of course the xtend plugin is still needed.

  1. pull code from git
  2. run in folder with pom:
    mvn eclipse:eclipse -DdownloadSources=true
  3. start eclipse and import existing project (navigate to folder with pom)

Import ordering

Eclipse-imports.png

Configure import ordering to avoid noise when doing code review. Open Preferences (Window/Preferences), then Java/Code Style/Organize Imports. Remove all rules and add following rule:

* - all unmatched type imports.

This should organize imports in following way:

  1. static imports sorted alphabetically
  2. <blank line>
  3. imports sorted alphabetically


Integrating Eclipse with Gerrit and Git

See GettingStarted:_Eclipse:_EGit and GettingStarted:_Eclipse:_Mylyn for how to get Gerrit and Git integrated into Eclipse. This allows you to commit and push to review etc. without leaving the IDE, instead of using the CLI as described here.