Jump to: navigation, search

OpenDaylight Controller:Pulling, Hacking, and Pushing the Code from the CLI

This content was created for the Hydrogen release and is out-of-date and is considered deprecated. It is unlikely to be updated in the future either. Information here should be taken with that in mind. For more up-to-date information see: GettingStarted:Pulling, Hacking, and Pushing All the Code from the CLI

Guide Contents
OpenDaylight Controller Overview
Architectural Framework
Development Infrastructure Overview
Pulling, Hacking, and Pushing the Code from the CLI
Pulling, Hacking, and Pushing the Code from Eclipse

OpenDaylight_Controller:Developing_With_Intellij
Sample Applications
Library Descriptions
REST Reference and Authentication
Java API Reference
Topologies
Top Level Contents

Pulling Stable/Helium

If you want to pull the stable/helium release, have a look at Stable Helium and replace Integration with the project(s) of your choice.

Git Cheat Sheet

For a quick overview of Git commands, check out the Git Cheat Sheet. For more specifics, see below.

Gerrit Setup

Creating a Gerrit account, including registering a public/private key pair, is required for using Git over SSH as documented below. Gerrit is also used for code reviews. If you don't already have an account with established keys, follow the documentation on setting up Gerrit.

Pull code via Git CLI

Pull the code by cloning the controller repository:

git clone ssh://<username>@git.opendaylight.org:29418/controller.git

Note that the command above assumes you've registered a Gerrit account and have a valid keypair for authentication. The public key should be known to Gerrit, and the private key should be on your local system at ~/.ssh/id_rsa.pub.

If you just want to do an anonymous git clone, you can use HTTPS:

git clone https://git.opendaylight.org/gerrit/p/controller.git

Checkout The Hydrogen Branch via Git CLI

Execute the following command:

git checkout stable/hydrogen

If you skip the above step, the master branch is checked out by default. You will likely get a warning similar to the following:

[ERROR] The build could not read 1 project -> [Help 1]
[ERROR]   
[ERROR]   The project org.opendaylight.controller:config-parent:0.3.0-SNAPSHOT
          (/home/gaynor/ODL_Examples/controller/opendaylight/config/config-
           parent/pom.xml) has 1 error
[ERROR]     Non-resolvable parent POM: Could not find artifact org.opendaylight.yangtools:binding-parent:pom:0.7.0-SNAPSHOT and 'parent.relativePath' points at no local POM @ line 11, column 11 ->

This is because karaf distributions require specific project settings outlined in m2 settings setup., but are not needed for the hydrogen distribution.

Setup Gerrit Change-id Commit Msg Hook

The following Git hook automatically inserts a unique Change-Id tag in the footer of each commit message. Git doesn't track hooks, so after pulling the project you'll want to go ahead and grab this one manually. Using this hook is optional, but highly recommended for tracking changes.

cd controller
scp -p -P 29418 <username>@git.opendaylight.org:hooks/commit-msg .git/hooks/
chmod 755 .git/hooks/commit-msg

Hack the code

Prerequisites

The following are required for building the codebase.

  • Maven 3.1.1 or greater.

Install (assuming yum is your package manager, adjust accordingly):

sudo yum install maven

Check your version (example output included):

[~]$ mvn -v
Apache Maven 3.1.1 (NON-CANONICAL_2013-11-08_14-32_mockbuild; 2013-11-08 09:32:41-0500)
Maven home: /usr/share/maven
Java version: 1.7.0_55, vendor: Oracle Corporation
Java home: /usr/lib/jvm/java-1.7.0-openjdk-1.7.0.60-2.4.7.0.fc20.x86_64/jre
Default locale: en_US, platform encoding: UTF-8
OS name: "linux", version: "3.13.10-200.fc20.x86_64", arch: "amd64", family: "unix"
  • Java 1.7+, including the JDK.

Install (assuming yum is your package manager, adjust accordingly):

sudo yum install java-1.7.0-openjdk

Check your version (example output included):

[~]$ java -version
java version "1.7.0_55"
OpenJDK Runtime Environment (fedora-2.4.7.0.fc20-x86_64 u55-b13)
OpenJDK 64-Bit Server VM (build 24.51-b03, mixed mode)

For more information about setting up a development environment for example hardware requirements see GettingStarted:Development Environment Setup.

Build the code

cd opendaylight/distribution/opendaylight/
mvn clean install
  • Maven build may run out of PermGen depending on the number of artifacts built, this is usually the case when building the opendaylight distribution for this the PermGen need to be increased. In order to do this and to make permanent the changes set in the environment the following environment variable:
MAVEN_OPTS="-Xmx1024m -XX:MaxPermSize=512m"
/* syntax for setting varies on the OS used by the build machine.*/
  • If you receive a Maven error when building northbound integration tests you can skip building those tests running the following:
mvn clean install -DskipTests 
/* instead of "mvn clean install" */
  • If you want maven to continue with building and running the next test after the current one fails (but still fail the build when any test failures occur), run the following:
mvn -Dmaven.test.failure.ignore=true --fail-at-end clean install
/* instead of "mvn clean install" */

Run the controller

cd controller/opendaylight/distribution/opendaylight/target/distribution.opendaylight-osgipackage/opendaylight/
./run.sh

The system takes up to 3 minutes to fully initialize. After 3 or more minutes have passed from entering the above commands, point your browser at http://localhost:8080/ and after a while the login screen should appear in the browser:

OpenDaylight - Login.jpg

Login with username: admin, password: admin

If the browser shows a blank page instead or if it complains about refused connection, the most frequent problem is that you did not give the system enough time to fully initialize itself. Wait a couple of minutes, then try to enter the URL into your browser again.

There is much much more complete documentation on running the controller in the Installation Guide.

Commit the code via Git CLI

Note: To be accepted, all code must come with a developer certificate of origin as expressed by having a Signed-off-by. This means that you are asserting that you have made the change and you understand that the work was done as part of an open-source license.

Developer's Certificate of Origin 1.1

        By making a contribution to this project, I certify that:

        (a) The contribution was created in whole or in part by me and I
            have the right to submit it under the open source license
            indicated in the file; or

        (b) The contribution is based upon previous work that, to the best
            of my knowledge, is covered under an appropriate open source
            license and I have the right under that license to submit that
            work with modifications, whether created in whole or in part
            by me, under the same open source license (unless I am
            permitted to submit under a different license), as indicated
            in the file; or

        (c) The contribution was provided directly to me by some other
            person who certified (a), (b) or (c) and I have not modified
            it.

        (d) I understand and agree that this project and the contribution
            are public and that a record of the contribution (including all
            personal information I submit with it, including my sign-off) is
            maintained indefinitely and may be redistributed consistent with
            this project or the open source license(s) involved.

Mechanically you do it this way

git commit --signoff

or in a shorter version:

git commit -s

You will be prompted for a commit message, and if you are fixing a buzilla bug, you can add that to your commit message as well and it will get linked from the Gerrit:

Fix for bug 2.

Signed-off-by: Ed Warnicke <eaw@cisco.com>

# Please enter the commit message for your changes. Lines starting
# with '#' will be ignored, and an empty message aborts the commit.
# On branch master
# Changes to be committed:
#   (use "git reset HEAD <file>..." to unstage)
#
#       modified:   README
#

If you wish to add the signoff to the commit message on your every commit without the need to specify -s or --signoff, add the following lines in the end of .git/hooks/commit-msg, after the line "add_ChangeId":

SOB=$(git var GIT_AUTHOR_IDENT | sed -n 's/^\(.*>\).*$/Signed-off-by: \1/p')
grep -qs "^$SOB" "$1" || echo "$SOB" >> "$1"

Make sure your credentials (name, email) are configured properly in git. They can be configured by adding the following settings:

git config --global user.name "John Doe"
git config --global user.email johndoe@example.com

Pull the code changes via git CLI

Use git pull to get the latest changes from the remote repository

git pull ssh://<username>@git.opendaylight.org:29418/controller.git HEAD:refs/for/master

Push the code via git CLI

Use git push to push your changes back to the remote repository.

git push  ssh://<username>@git.opendaylight.org:29418/controller.git HEAD:refs/for/master

To push a draft (for something that is work in progress or for a discussion, that should not be merged)

git push  ssh://<username>@git.opendaylight.org:29418/controller.git HEAD:refs/drafts/master

You will get a message pointing you to your gerrit request like:

remote: Resolving deltas: 100% (2/2)
remote: Processing changes: new: 1, refs: 1, done    
remote: 
remote: New Changes:
remote:   http://git.opendaylight.org/gerrit/64
remote: 

Seeing your change in Gerrit

Follow the link you got above to see your commit in Gerrit:

Gerrit Code Review.jpg

Note the Jenkins Controller User has verified your code, and at the bottom is a link to the Jenkins build.

Once your code has been reviewed and submitted by a committer it will be merged into the authoritative repo, which would look like this:

Gerrit Merged.jpg

What to do if your Firewall blocks port 29418

There have been reports that many corporate firewalls block port 29418. If that's the case, there are two solutions: tsocks and HTTP.

tsocks

tsocks will socksify any command you run. tsocks is available on Linux and MacOS:

  • RedHat/CentOS/Fedora: yum install tsocks
  • Ubuntu: apt-get install tsocks
  • MacOS: tsocks on MacOS

Once tsocks is installed, you will need to configure your corporate proxy server in the tsocks.conf file. To use tsocks, just add "tsocks" before your normal git command. For example:

tsocks git clone ssh://<your_username>@git.opendaylight.org:29418/controller.git

HTTP

To use HTTP, please follow the Setting up HTTP in Gerrit instructions and use git URL:

git clone https://<your_username>@git.opendaylight.org/gerrit/p/controller.git

You will be prompted for the password you generated in Setting up HTTP in Gerrit.

All other instructions on this page remain unchanged :)

External Links From the Community for Dev and Ops with ODP

The following are how-tos and resources posted from community engineers, operators, devs, and architects that blog:

Key methods for early community understanding, assistance and involvement:

  • TSC:Main Listening to the weekly TSC meetings.
  • There is an IRC channel #opendaylight, #opendaylight-ovsdb and #opendaylight-dlux on irc.freenode.net. IRC is probably the best resource for realtime Q&A collaboration and meeting others in the community both vendor and non-vendor alike).