VPP/Pulling, Building, Running, Hacking and Pushing VPP Code

From fd.io
< VPP
Jump to: navigation, search

Intro

This page tries to give you a quick start guide for Pulling, Building, Running, Hacking, and Pushing VPP Code. An older version of this content can be found at Setting up Your Dev Environment (historical) which may have some gems, but you are likely to find this page more up to date.

Pulling

fd.io uses Gerrit, a code review front end on git. You can pull and push code via ssh with an ssh key or authenticated https. ssh is recommended. You can also pull code using anonymous https. Regardless of the access method you will require the "git" program and the "git review" extension is strongly recommended.

Pulling anonymously (https)

You can pull the code anonymously using: 

git clone https://gerrit.fd.io/r/vpp

This is the fastest way to get the code, but you cannot *push* anonymously, and so you are going to have to establish an account when you get to the point of pushing code.

Pulling code via ssh

The recommended way to pull code is via ssh, especially if you intend to develop and submit changes. This requires you to setup an account and set up gerrit.

Setting up an account

fd.io uses the Linux Foundations identity system. If you do not already have an LF account, proceed to: https://identity.linuxfoundation.org/ to create one. If you do, you can use your Linux Foundation username and password for all logins at fd.io.

Setting up Gerrit

Make sure you have registered your ssh key with gerrit.

Pulling the code

Type the following git command (replacing USERNAME with your Linux Foundation username): 

git clone ssh://USERNAME@gerrit.fd.io:29418/vpp.git

Pulling code via authenticated https

If you are on a network that blocks port 29418 then you may be able to use authenticated https instead. You still need a gerrit account (see above). The invocation for this would look like: 

git clone https://USERNAME:APITOKEN@gerrit.fd.io/r/a/vpp

Again, replace USERNAME with your Linux Foundation username. APITOKEN is a Gerrit feature; In among your user settings there is a section entitled "HTTP Password". This page will allow you to generate a token that you can use in place of your password. If you do not wish to embed the token in the URL, then this method 

git clone https://USERNAME@gerrit.fd.io/r/a/vpp

will prompt you for a password; if you have generated a token then use it here though understand that you'll have to enter it every time you use this method.

Also it is worth noting that some features of the review process may unavoidably require using SSH on port 29418.

Building

Linux

VPP can be built, packaged and run on either Debian based (Ubuntu,etc) or RPM based (Centos,etc) out of the box.

Building the first time

In order to insure up to date instructions for setting up and building the first time, VPP has a script

build-root/vagrant/build.sh

which installs any dependencies, builds the proper packaging for your local Linux distribution, and installs those packages. Simply running this script should get you going fast. It is the same file used to install dependencies, build, and install packages when the vagrant environment is used. It is also a useful place to crib from for how to do those individual steps.

Subsequent Builds

Once you've gone through your first build successfully, there are detailed instructions on building, installing, and testing packages : Build A VPP Package

Building without virtualization

From the VPP repository root you can use the Makefile. 

# if vpp<18.10
make install-dep
make bootstrap
make build        # or `make build-release`

# vpp 18.10+ (cmake)
make install-dep
make install-ext-deps
make build        # or `make build-release`


Bootstrap errors

  • libtoolize: AC_CONFIG_MACRO_DIR([m4]) conflicts with ACLOCAL_AMFLAGS=-I m4

There is probably a carriage return at the end of ACLOCAL_AMFLAGS=-I m4.

If you are using git, add a `.gitattributes` file with the following lines 

*.sh    -crlf
*.ac    -crlf
*.am    -crlf

Note: this is enough for the bootstrap problem, but you will also have building problems with crlf enabled. You should probably change the core.autocrlf setting in your git configuration before cloning the repository. 

git config --global core.autocrlf input

Compilation errors

  • vpp/app/version.h: No such file or directory

See Bootstrap errors and change the git core.autocrlf setting.

Mac OS

Building the First Time

If you are working on a Mac, you will want to stand up a Linux VM.

If you have a Linux VM already, please feel free to simply utilize the Linux' instructions.

If you do not yet have a Linux VM, VPP provides a 'vagrant' setup to help you quickly and simply get one. For more information about using Vagrant on a command-line interface (CLI), see: https://docs.vagrantup.com/v2/cli/index.html

Setting Up Vagrant

Follow the instructions for setting up Vagrant

Choosing alternate hypervisor, distribution, and number of NICs (optional)

By default vagrant will use the Virtualbox provider, and boot an Ubuntu 16.04 VM, and with two extra 'NICs' you can use to try out with VPP.

You can change this by setting environment variables.

Alternate Linux distro environment variable

To boot a Centos 7 VM (rather than the default Ubuntu 16.04 VM) 

export VPP_VAGRANT_DISTRO=centos7
Alternate hypervisor environment variable

To use VMWare Fusion as your alternate vagrant provider: 

export VAGRANT_DEFAULT_PROVIDER=vmware_fusion

Note: If you use vmware please see Vagrant VMWare Provider, and be aware you will have to purchase the VMWare Vagrant plugin.

Alternate number of extra NICs environment variable

To have a different number of external NICs to use with VPP other than the default of 2 (five in this example): 

export VPP_VAGRANT_NICS=5

Starting Vagrant

To start your Vagrant VM: 

cd build-root/vagrant
vagrant up

This will result in a bunch of output as the VM is provisioned, vpp is built, and the vpp packages are installed on the VM and run. Once it completes, you can access the VM with: 

vagrant ssh

Which will ssh you into your Vagrant VM.

Subsequent Builds

From your vagrant VM, to perform subsequent builds: 

cd /vpp

which will take you to the top of your vpp tree, and then follow the Linux instructions for subsequent builds.

Running

Running from package installation

The process for starting vpp varies between systems using upstart (Ubuntu 14.04) and systems using systemd (Centos 7 and Ubuntu 16.04).

Running vpp upstart systems (Ubuntu 14.04)

sudo start vpp

Running vpp on systemd systems (Centos 7, Ubuntu 16.04)

sudo service vpp start

Taking vpp for a spin

Hacking

There are many VPP Tutorials including a lot of content on the fd.io Youtube channel

Pushing

Pushing Code with git review

Installing git review

Instructions for installing git review on many different types of platforms

Initial Setup

Clone your git repository, and in the root directory enter the following: 

git review -s
git config user.name "Firstname Lastname"
git config user.email your_email@some.domain

This will set up your connection to Gerrit as well as your commit author and email. You can also pass the "--global" option if you want this to apply system wide rather then to the repo. For example: 

git config --global user.name "Firstname Lastname"
git config --global user.email your_email@some.domain

Recommended Local Topic Branch Structure

It is recommended that when working on a change locally, you start from 'master' and pull a local topic branch: 

git checkout -b ${branch_name}

Where the ${branch_name} is the name for the local branch for the thing you are working on. Note that generally the ${branch_name} becomes the 'Topic' on the gerrit when you push your code.

Pushing Patches

Commit to your local repo

Once you are happy with your changes, commit them to your local branch: 

git add ${files}
git commit -s

The -s in your git commit adds a 'Signed-off-by' signifying that you have agreed to the standard Developer Certificate of Origin 1.1 (the same one used by the Linux Kernel): 

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.

Pushing Patches with git review

When you are ready to push your commit (or commits) to gerrit, you can simply type: 

git review

and your commits will be pushed up to gerrit for code review.

You have several options with git review, some handy ones include 

git review -f

which will delete your local topic branch once you have pushed to gerrit (useful for keeping your local repo clean).

Note: Gerrit will (unless instructed otherwise) rebase on your local master. It is a good idea to keep your local master synced up to origin/master via: 

git checkout master
git pull

How Do I Get My Patch Reviewed ?

The simplest and most straightforward method is to send a mail to vpp-dev@lists.fd.io with the gerrit link to your patch, short description of the patch and asking to review it.

If you want to find the precise person to look at the changes upfront, then you could use the MAINTAINERS file to figure out who this would be. You can use the script https://gerrit.fd.io/r/c/vpp/+/33139 to make this task easier. Then you can add that person to the reviewer list, and ask them to review your code.

Retrieving a gerrit patch to review it

Every patch in gerrit has a gerrit number, specified in its URL. Example: https://gerrit.fd.io/r/#/c/1282/ is gerrit 1282.

You can retrieve such a patch with: 

git review -d ${patch_number}

Example: For patch 1282 this would be: 

git review -d 1282


Revising a gerrit patch

If you have retrieved a gerrit patch, and wish to revise it, you do not simply want to push a new commit on top of it (which will result in a new gerrit). Instead, if you are revising a gerrit patch, you can simply --amend it with 

git commit -s --amend

Which will reuse the 'ChangeId' in the commit message of the commit you are revising, and add it as a new Patch Set to Gerrit.

Gerrit won't rebase my patch, now what?

Use "git review -d" which makes it reasonably painless to push the results upstream as a new patch-set.

In a fresh tree, do the following: 

git review -d <Gerrit change #>
git rebase origin/master
while (conflicts)
  {
    <fix conflicts>
    git rebase --continue
  }
git review

Jenkins build issues that are not code related?

Try OpenStack jenkins builder

Add the word os-check or os-verify as a gerrit comment on verify jobs.

Add the word os-merge as a gerrit comment on merge jobs.

Try Try Again

Add the word recheck as a gerrit comment.

If your sure the problem is container build related you can direct email to infra-container@fd.io

Open an Infra trouble ticket

Follow https://wiki.fd.io/view/Getting_LF_IT_Help_for_FD.IO

Explain the problem your having and what you have tried.

Random Hints and Kinks for KVM usage

For anyone wishing to build on a virtual machine and use KVM, this information might be useful: VPP/Random Hints and Kinks for KVM usage

Retrieved from "https://wiki.fd.io/index.php?title=VPP/Pulling,_Building,_Running,_Hacking_and_Pushing_VPP_Code&oldid=11702"