This section covers development and test environment setup and configuration. 

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. 

 

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.

Code Formatting

The formatting followed by the project are:

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.

Copyright

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 orginal can be found at: 

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

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:

Git/Gerrit Setup

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

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.

Java and Maven

Build failures may occur if multiple Java versions are installed, and Maven is pointed to the incorrect version.

If not set automatically during the Java 8 installation process, The JAVA_HOME environment variable should be set to the JRE installation location for Java 8. The process for verifying/setting the proper version varies with platform.

On OS X

$ /usr/libexec/java_home
/Library/Java/JavaVirtualMachines/jdk1.8.0_25.jdk/Contents/Home

To set the version, either run or add the following to the shell profile:

$ export JAVA_HOME=$(/usr/libexec/java_home -v 1.8)

On Ubuntu

$ sudo update-alternatives --config java
There are 2 choices for the alternative java (providing /usr/bin/java).

  Selection    Path                                            Priority   Status
------------------------------------------------------------
  0            /usr/lib/jvm/java-8-oracle/jre/bin/java          1072      auto mode
  1            /usr/lib/jvm/java-7-openjdk-amd64/jre/bin/java   1071      manual mode
* 2            /usr/lib/jvm/java-8-oracle/jre/bin/java          1072      manual mode

Press enter to keep the current choice[*], or type selection number: 

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.

Test Environment Setup

Testing a distributed platform like ONOS can become a cumbersome task. ONOS, being an SDN controller authored in Java, can run on a variety of platforms. However, in the interest of focus, the project engages primarily in testing on Ubuntu server distributions, specifically Ubuntu Server 14.04* LTS 64-bit, using the Oracle Java 8 JRE.

in order to simplify testing and to make it more repeatable, a number of assets, including the aforementioned ONOS scripts, have been developed to make the developer’s  and tester’s lives easier. These are located under onos/tools/test/, and Appendix A of this Guide provides a listing of available utilities.

Overview

An ONOS developer's environment may include the following:

In the above case, the ONOS scripts are run from the development machine, and are directed towards VMs running on a hypervisor (which can also be on the same machine, or elsewhere). Since a developer may want to test different scenarios against different sets of VMs or servers, ONOS provides the notion of test cells

Test Cells

A test cell refers to a specific controller cluster environment designated for testing. This can mean a set of bare-metal servers, or a set of VMs running on developer’s laptop. Cell definition files are bash snippets that export a few environment variables into the developer’s (or tester’s) shell. These variables are then used by a number of the ONOS test and utility scripts. This allows the scripts and test scenarios to be independent to a specific test bench setup.

Using cells

Cell definitions are loaded into the shell environment with the cell utility. This utility takes the name of a cell definition file as the argument. For example:

$ cell local                                              
ONOS_CELL=local
OCI=192.168.56.101
OC1=192.168.56.101
OC2=192.168.56.102
OCN=192.168.56.103
ONOS_FEATURES=webconsole,onos-api,onos-core,onos-cli,onos-openflow,onos-gui,onos-rest,onos-app-fwd,onos-app-proxyarp,onos-app-tvue
ONOS_NIC=192.168.56.*

cell echoes back with the key environment variables understood by the ONOS scripts:

Once a cell definition is exported, utilities such as onos will fall back to using the value set in OCI (192.168.56.101 for above) if not given any parameters. 

The utility script cells can be used to view all available cell definitions. Without parameters, cell will list the values associated with the current cell in use.

Cell Definition Files

A cell definition file defines values for the aforementioned environment variables. A cell definition file may look like the following:

# Default ONOS Controller VM instances 1,2,3 and a Mininet VM
export OC1="192.168.56.101"
export OC2="192.168.56.102"
export OC3="192.168.56.104"
export OCN="192.168.56.103"  # Mininet VM
       
# for node clustering
export ONOS_NIC=”192.168.56.*”    

# ONOS features to load
export ONOS_FEATURES="webconsole,onos-api,onos-core-trivial,onos-cli"

These files are located in ONOS_ROOT/tools/test/cells/.

Creating custom cell definitions

Custom cell definition files may be added to ONOS_ROOT/tools/test/cells/, which enables them to be loaded and listed with cell and cells.