Page tree

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

This section section covers development and test environment setup and configuration. 

Table of Contents
maxLevel3

 

Info
This page assumes that the reader has successfully followed Installing and Running ONOS.

IDE Setup

The project does not enforce the use of a specific IDE, but rather, a set of guidelines that can be configured in an IDE. As such, developers should consult the documentation for the IDE of choice for specific configuration steps. 

The examples used here, if any, are either for Eclipse and IntelliJ.

Importing ONOS Source

If your IDE supports the importing of projects, ONOS should be imported as a Maven project

In Eclipse, this amounts to:

  1. navigate to File > Import > Maven > Existing Maven Projects and 
  2. selecting the root directory of your source. 

 

Info

As ONOS is a multi-module project, it may appear as a collection of many (about 50 at the time of this writing) projects beginning with "onos-". This is normal for some IDEs such as Eclipse.

For a listing of the software modules that comprise ONOS, please refer to the Javadocs, or Appendix C of this Guide.

Tip
title"Plugin execution not covered ..." errors in Eclipse

If you're using Eclipse and see "Plugin execution not covered ..." errors about jacoco-maven-plugin and onos-maven-plugin after importing ONOS projects, follow these steps to eliminate those errors.

  1. Select one of "Plugin execution not covered..." error and select "Quick Fix"

    Expand

    Image Removed

    Image Removed

  2. Select "Mark the goal as ignored in Eclipse build in Eclipse preference" as the fix and "Finish" to apply the fix.

    Expand

    Image Removed

  3. Select one of the ONOS related project to open the "Update Project" dialog, then "Select All" projects and update all the projects.

    Expand

    Image Removed

    Image Removed

    It may take a while for Eclipse to rebuild all the project after refreshing project configuration.

  4. By following the steps above, maven goal resolution errors for the same goal should disappear. (jacoco-maven-plugin). Repeat the same step for remaining goal error. (onos-maven-plugin)

    Expand

    Image Removed

 

  1. Code Formatting

The formatting followed by the project are:

  1. Indentation using four spaces
  2. No trailing whitespaces, including in empty lines
  3. Spaces after keywords such as if, for, while, and casts

The whitespace formatting, among other code styling, is enforced via Checkstyle, which is run against the code during each Maven build. The build will fail if formatting violations are found.

The full guidelines are found in the Code Style Guidelines.

Prior to contributing code to ONOS, all developers should set-up their IDE to appropriately tag the code with the Apache 2 license header text. The bare text is checked in under tools/dev/header.txt, and the original can be found at: 

http://www.apache.org/licenses/LICENSE-2.0.html 

  1. Example: Copyright setup on IntelliJ

First make sure that you have the Copyright plugin enabled. Then, under Preferences, select Copyright section and create a new Copyright profile, call it something like Apache 2, and prime it with the text above, without any decorations. Then configure your copyright formatting options as shown:

Image Removed

  1. Example: Copyright setup on Eclipse

Configure the Comments for Files similar to the following. 
Remember to put a check on "Automatically add comments for new methods and types" to apply these templates on new files.  

Image Removed
  1. Git/Gerrit Setup

  2. Git remotes

There are two ways to clone the code from Gerrit, https:// or ssh://. Either way is fine for reading the code, but when it comes time to contribute the easiest and most secure way is to access Gerrit over SSH.

To make sure you're using the ssh:// remote, first check the URLs of the remotes in your ONOS repository:

Code Block
$ git remote -v
origin  https://gerrit.onosproject.org/onos (fetch)
origin  https://gerrit.onosproject.org/onos (push)

If you see ssh:// URLs, everything is fine and you can move on to the next step (Configuring Gerrit). If you see https:// URLs, you should change them to ssh:// before continuing:

Code Block
$ git remote set-url origin ssh://<username>@gerrit.onosproject.org:29418/onos

Substitute <username> with your Gerrit/Crowd username. You can double-check the URL on Gerrit by logging in, going to Projects -> List, then clicking on 'onos', On the grey bar, click 'SSH', then just underneath the grey bar will appear 'git clone ssh://...'. This is the URL you should set your remote to in your local git repository.

  1. Configuring Gerrit

Prospective contributors should configure their account to receive notifications about their code submissions. The Settings page is accessed from the user dropdown on the upper right of the page:

Image Removed

To configure contacts by going to Contact Information, and filling out the fields, and hitting Save Changes :

Image Removed

To subscribe to the project, go to Watched Projects and enter onos-next in the Project Name field of the page. Hitting return should add onos-next to a table under the search field:

Image Removed

As shown above, email notifications are also configured from here by checking off the types of notifications to receive. 

  1. Uploading SSH Public Keys

An SSH key should also be uploaded to the ONOS Gerrit server.

Generate a key. Keep the default file name and location. This will generate an id_rsa and id_rsa.pub file in ~/.ssh:

Code Block
languagetext
$ ssh-keygen -t rsa
Generating public/private rsa key pair.
Enter file in which to save the key (/home/onosuser/.ssh/id_rsa): 
Enter passphrase (empty for no passphrase): 
Enter same passphrase again: 
Your identification has been saved in /home/onosuser/.ssh/id_rsa.
Your public key has been saved in /home/onosuser/.ssh/id_rsa.pub.

...
$ ls ~/.ssh
id_rsa  id_rsa.pub  known_hosts

...

 

Info
A key must be uploaded per host if checking code out to multiple hosts with git.
  1. Configuring git

Developers planning to contribute code should configure git with their username and email.

Code Block
languagetext
git config --global user.name "firstname lastname"
git config --global user.email "email@domain.com"

To streamline the code review process, it is highly recommended that contributors set up git-review, which integrates code submission with git. Refer to this link for instructions for setting up git-review.

Tip
titlegit-review + Mac

If you're using a Mac, you may need to manually upgrade the git-review package dependency. (git-review bug#1337701)

$ sudo pip install --upgrade setuptools
$ sudo pip install --upgrade git-review

  1. Building API Docs

To build a local set of the ONOS Java API documentation bundle, use the onos-build-docs utility, which uses Maven to generate both internal and external documentation. 

Running  onos-build-docs from any location generates HTML pages under ONOS_ROOT/docs/, and can be accessed by pointing a browser to ONOS_ROOT/docs/target/site/apidocs/index.html

The generated documentation is also wrapped into a gzipped tar archive and placed under /tmp with the naming convention onos-apidocs-<onos-version>.<user>.tar.gz.

 

Home : Developer's Guide
Next : Test Environment Setup

...

Children Display