Jump to: navigation, search

GettingStarted:Pulling, Hacking, and Pushing All the Code from the CLI

Intro

This page tries to give you a quick start guide to pulling, hacking, and pushing the code for an OpenDaylight project.

For a quick reference on some commonly used git commands, check out the GIT Cheat Sheet.

Make sure you have an account

While you can pull code anonymously, if you want to push it (or edit the wiki) you will need to have an OpenDaylight Account. To access the account creation form, currently you need to click the colorful icon here.

Gerrit Setup

Code reviews are enabled through Gerrit. Set up Gerrit for use if you wish to use ssh. If you wish to use https, Set up Gerrit to use HTTPS.

Note: You will need to perform the Gerrit Setup before you can access git via ssh as described below.

Install Dependencies

NOTE: If you have not setup your environment according to Development Environment Setup, make sure you at least follow Edit your .m2 settings.xml to ensure maven can resolve the correct dependencies.
NOTE: ODL now requires a minimum version of 3.3.9 for Boron+ releases! There are a significant number of dependencies required for building. The following works for Fedora 20 to add the dependencies:

  • Fedora
sudo yum -y install maven git bzip2 \
  make binutils gcc gcc-c++ boost-devel openssl-devel perl-ExtUtils-MakeMaker \
  unixODBC-devel gtest-devel redhat-lsb-core json-c-devel libcurl-devel \
  perl-Digest-SHA tomcat-native
  • Ubuntu 13.10/14.04 (assuming maven already installed using this guide)
   apt-get install pkg-config gcc make ant g++ git libboost-dev libcurl4-openssl-dev \
    libjson0-dev libssl-dev openjdk-7-jdk unixodbc-dev xmlstarlet

Pull code via git CLI

Pull the code by cloning the controller repository.

First, all the lines below use the $ODL_USERNAME environment variable, so your life will be *way* easier of you set it with:

export ODL_USERNAME=<username for the account you created at OpenDaylight>

or better yet, if you can use ssh (see below), add the following to your ~/.ssh/config file (create it if necessary):

Host git.opendaylight.org
    User <your username>

(then you can simply omit "${USERNAME}@" from the instructions below).

If your host is located behind a proxy that would drop ssh connections that uses ports other than http[s], you should add the following lines to ~/.ssh/config file

Host git.opendaylight.org
    User <your username>
    IdentityFile ~/.ssh/<public key, usually id_rsa.pub>
    ProxyCommand corkscrew <your proxy name or ip> <your proxy port, usually 8080 or 3128> %h %p
    Port 29418

This configuratioin requires a tool named corkscrew :

  • Fedora
sudo yum -y install corkscrew
  • Ubuntu 13.10/14.04
sudo apt-get install corkscrew

Then you will want to check out the code from each of the repos for each project. You can, of course select any one of the projects if you are only looking for one.

You have two choices for your method of engagement, you can use:

  1. ssh on port 29418 (blocked by some firewalls)
  2. https

Pull code via ssh

for PROJECT in aaa aalldp alto armoury atrium bgpcep bier capwap cardinal centinel coe controller daexim didm discovery \
dlux dluxapps docs eman faas federation fpc genius groupbasedpolicy honeycomb/vbd integration/distribution \
integration/packaging integration/packaging/ansible-opendaylight integration/packaging/puppet-opendaylight integration/test \
iotdm jsonrpc kafkaproducer l2switch lacp lispflowmapping mdsal messaging4transport natapp nemo netconf netide netvirt \
neutron next nic ocpplugin odlparent of-config ofextensions/circuitsw ofextensions/epc openflowjava openflowplugin opflex \
ovsdb packetcable persistence plugin2oc releng releng/autorelease releng/builder reservation sdninterfaceapp sfc snbi snmp \
snmp4sdn sxp systemmetrics tcpmd5 topoprocessing transportpce tsdr ttp unimgr usc usecplugin vpnservice vtn yang-push \
yangide yangtools; \
do git clone ssh://${ODL_USERNAME}@git.opendaylight.org:29418/${PROJECT}.git ${PROJECT}; \
done

Note: The best way to build an ODL distribution is to compile the integration/distribution project. The integration/distribution project pulls the latest artifacts published by each project and builds a karaf distribution where you can install and test out the latest features. There aren't many scenarios in which you would want to compile all of the projects on your own machine!

Pull code with https

for PROJECT in aaa aalldp alto armoury atrium bgpcep bier capwap cardinal centinel coe controller daexim didm discovery \
dlux dluxapps docs eman faas federation fpc genius groupbasedpolicy honeycomb/vbd integration/distribution \
integration/packaging integration/packaging/ansible-opendaylight integration/packaging/puppet-opendaylight integration/test \
iotdm jsonrpc kafkaproducer l2switch lacp lispflowmapping mdsal messaging4transport natapp nemo netconf netide netvirt \
neutron next nic ocpplugin odlparent of-config ofextensions/circuitsw ofextensions/epc openflowjava openflowplugin opflex \
ovsdb packetcable persistence plugin2oc releng releng/autorelease releng/builder reservation sdninterfaceapp sfc snbi snmp \
snmp4sdn sxp systemmetrics tcpmd5 topoprocessing transportpce tsdr ttp unimgr usc usecplugin vpnservice vtn yang-push \
yangide yangtools; \
do git clone https://git.opendaylight.org/gerrit/${PROJECT}.git ${PROJECT}; \
done

Checkout Stable branch

git checkout stable/<release name>

Checkout Release tag

git checkout tags/release/<release name>

Hack the Code

Build the code

FIXME: The process described below does not work for the Lithium SR2 release nor the latest master branch. Need to dig the correct instructions out of the builder and integration jobs and put here.

Please make sure you have followed the development environment setup guide properly and especially make sure that you have edited your ~/.m2/settings.xml.

Note that the code is structured by project, and each project has its own subdirectory. You must explicitly enter each subdirectory and build in that directory to build that project. In the example below, we show how to build ALL of the projects, but you can just build say the base controller by entering the controller directory and building there.

You are going to want to increase the memory available to maven, the settings on the Jenkins build server are:

export MAVEN_OPTS="-Xmx1024m -XX:MaxPermSize=256m"

Below is the top level build line for each project:

for i in odlparent affinity bgpcep controller lispflowmapping openflowjava openflowplugin ovsdb/commons/parent vtn yangtools
do (cd "$i" && mvn clean install ); done

Note 1: You'll need at least 15 GiB of free space for the build to complete.

Note 2: If you are missing a build dependency, such as "make" the vtn build will fail, but likely report success.

Test the Code

Build and Run Karaf distribution

Without clearing .m2 cache (it contains built artifacts from last step), download integration code:

git clone ssh://${ODL_USERNAME}@git.opendaylight.org:29418/integration/distribution.git

or

git clone https://git.opendaylight.org/gerrit/p/integration/distribution.git

Build the integration code skipping test:

cd distribution
mvn clean install -Pq

Run the just created Karaf distribution:

cd distribution-karaf/target/assembly
bin/karaf

Install the features you want to test and perform any suitable test. You can find Karaf help on this link , including important tips for development under Karaf.

Gerrit Workflow

Refer to http://docs.releng.linuxfoundation.org/en/latest/gerrit.html for details on how to use Gerrit.