-
Notifications
You must be signed in to change notification settings - Fork 707
Pulling,_Building,_Running,_Hacking_and_Pushing_VPP_Code
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.
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.
You can pull the code anonymously using:
git clone
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.
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.
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.
Make sure you have registered your ssh key with gerrit.
Type the following git command (replacing USERNAME with your Linux Foundation username):
ssh://[email protected]:29418/vpp.git
git clone
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:
https://USERNAME:[email protected]/r/a/vpp
git clone
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
https://[email protected]/r/a/vpp
git clone
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.
VPP can be built, packaged and run on either Debian based (Ubuntu,etc) or RPM based (Centos,etc) out of the box.
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.
Once you've gone through your first build successfully, there are detailed instructions on building, installing, and testing packages : Build A VPP Package
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`
- **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
- **vpp/app/version.h: No such file or directory **
See **Bootstrap errors **and change the git **core.autocrlf **setting.
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
Follow the instructions for setting up Vagrant
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.
To boot a Centos 7 VM (rather than the default Ubuntu 16.04 VM)
export VPP_VAGRANT_DISTRO=centos7
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.
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
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.
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.
The process for starting vpp varies between systems using upstart (Ubuntu 14.04) and systems using systemd (Centos 7 and Ubuntu 16.04).
sudo start vpp
sudo service vpp start
- Create a tuntap interface and trace a basic ping command
- Try out some of the other use cases
There are many VPP Tutorials including a lot of content on the fd.io Youtube channel
Instructions for installing git review on many different types of platforms
Clone your git repository, and in the root directory enter the following:
[email protected]
git review -s
git config user.name "Firstname Lastname"
git config user.email
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:
[email protected]
git config --global user.name "Firstname Lastname"
git config --global user.email
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.
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.
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
The simplest and most straightforward method is to send a mail to [email protected] 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.
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
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.
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
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.
Add the word recheck as a gerrit comment.
If your sure the problem is container build related you can direct email to [email protected]
Follow view/Getting_LF_IT_Help_for_FD.IO.md
Explain the problem your having and what you have tried.
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