Difference between revisions of "VPP/Pulling, Building, Running, Hacking and Pushing VPP Code"
Dwallacelf (Talk | contribs) (Clean up formatting.) |
|||
Line 14: | Line 14: | ||
You can pull the code anonymously using: | You can pull the code anonymously using: | ||
− | + | git clone https://gerrit.fd.io/r/vpp | |
− | 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. | 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. | ||
Line 37: | Line 35: | ||
Type the following git command (replacing USERNAME with your [https://identity.linuxfoundation.org Linux Foundation] username): | Type the following git command (replacing USERNAME with your [https://identity.linuxfoundation.org Linux Foundation] username): | ||
− | + | git clone ssh://USERNAME@gerrit.fd.io:29418/vpp.git | |
− | git clone ssh://USERNAME@gerrit.fd.io:29418/vpp.git | + | |
− | + | ||
== Pulling code via authenticated https == | == Pulling code via authenticated https == | ||
Line 46: | Line 42: | ||
The invocation for this would look like: | The invocation for this would look like: | ||
− | + | git clone https://USERNAME:APITOKEN@gerrit.fd.io/r/a/vpp | |
− | git clone https://USERNAME:APITOKEN@gerrit.fd.io/r/a/vpp | + | |
− | + | ||
Again, replace USERNAME with your [https://identity.linuxfoundation.org Linux Foundation] username. APITOKEN is a Gerrit feature; In among your user settings there is a section entitled "[https://gerrit.fd.io/r/#/settings/http-password 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 | Again, replace USERNAME with your [https://identity.linuxfoundation.org Linux Foundation] username. APITOKEN is a Gerrit feature; In among your user settings there is a section entitled "[https://gerrit.fd.io/r/#/settings/http-password 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 | |
− | 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. | 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. | ||
Line 80: | Line 72: | ||
=== Subsequent Builds === | === Subsequent Builds === | ||
− | Once you've gone through your first build successfully, there are detailed instructions on building, installing, and testing packages | + | Once you've gone through your first build successfully, there are detailed instructions on building, installing, and testing packages : |
− | + | [[VPP/Build,_install,_and_test_images#Build_A_VPP_Package | Build A VPP Package]] | |
== Mac OS == | == Mac OS == | ||
Line 107: | Line 99: | ||
To boot a Centos 7 VM (rather than the default Ubuntu 14.04 VM) | To boot a Centos 7 VM (rather than the default Ubuntu 14.04 VM) | ||
− | + | export VPP_VAGRANT_DISTRO=centos7 | |
− | export VPP_VAGRANT_DISTRO=centos7 | + | |
− | + | ||
===== Alternate hypervisor environment variable ===== | ===== Alternate hypervisor environment variable ===== | ||
To use VMWare Fusion as your alternate vagrant provider: | To use VMWare Fusion as your alternate vagrant provider: | ||
− | + | export VAGRANT_DEFAULT_PROVIDER=vmware_fusion | |
− | export VAGRANT_DEFAULT_PROVIDER=vmware_fusion | + | |
− | + | ||
'''Note:''' If you use vmware please see [https://www.vagrantup.com/docs/vmware/ Vagrant VMWare Provider], and be aware you will have to purchase the VMWare Vagrant plugin. | '''Note:''' If you use vmware please see [https://www.vagrantup.com/docs/vmware/ Vagrant VMWare Provider], and be aware you will have to purchase the VMWare Vagrant plugin. | ||
Line 122: | Line 110: | ||
===== Alternate number of extra NICs environment variable ===== | ===== 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): | 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 | + | export VPP_VAGRANT_NICS=5 |
− | + | ||
==== Starting Vagrant ==== | ==== Starting Vagrant ==== | ||
Line 130: | Line 117: | ||
To start your Vagrant VM: | To start your Vagrant VM: | ||
− | + | cd build-root/vagrant | |
− | cd build-root/vagrant | + | vagrant up |
− | 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. | 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: | Once it completes, you can access the VM with: | ||
− | + | vagrant ssh | |
− | vagrant ssh | + | |
− | + | ||
Which will ssh you into your Vagrant VM. | Which will ssh you into your Vagrant VM. | ||
Line 147: | Line 130: | ||
From your vagrant VM, to perform subsequent builds: | From your vagrant VM, to perform subsequent builds: | ||
− | + | ||
− | cd /vpp | + | cd /vpp |
− | + | ||
which will take you to the top of your vpp tree, and then follow the [[VPP/Pulling,_Building,_Running,_Hacking_and_Pushing_VPP_Code#Subsequent_Builds |Linux instructions for subsequent builds. ]] | which will take you to the top of your vpp tree, and then follow the [[VPP/Pulling,_Building,_Running,_Hacking_and_Pushing_VPP_Code#Subsequent_Builds |Linux instructions for subsequent builds. ]] | ||
Line 160: | Line 143: | ||
=== Running vpp upstart systems (Ubuntu 14.04) === | === Running vpp upstart systems (Ubuntu 14.04) === | ||
− | + | sudo start vpp | |
− | sudo start vpp | + | |
− | + | ||
=== Running vpp on systemd systems (Centos 7, Ubuntu 16.04) === | === Running vpp on systemd systems (Centos 7, Ubuntu 16.04) === | ||
− | + | sudo service vpp start | |
− | sudo service vpp start | + | |
− | + | ||
== Taking vpp for a spin == | == Taking vpp for a spin == | ||
Line 176: | Line 155: | ||
= Hacking = | = Hacking = | ||
− | There are many [VPP#Tutorials|VPP Tutorials] including a lot of content on the [https://www.youtube.com/channel/UCIJ2OP6_i1npoHM39kxvwyg/playlists fd.io Youtube channel] | + | There are many [[VPP#Tutorials|VPP Tutorials]] including a lot of content on the [https://www.youtube.com/channel/UCIJ2OP6_i1npoHM39kxvwyg/playlists fd.io Youtube channel] |
= Pushing= | = Pushing= | ||
Line 189: | Line 168: | ||
Clone your git repository, and in the root directory enter the following: | Clone your git repository, and in the root directory enter the following: | ||
− | + | ||
− | git review -s | + | git review -s |
− | git config user.name Firstname Lastname | + | git config user.name Firstname Lastname |
− | git config user.email your_email@some.domain | + | 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: | 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.name Firstname Lastname | + | git config --global user.email your_email@some.domain |
− | git config --global user.email your_email@some.domain | + | |
− | + | ||
=== Recommended Local Topic Branch Structure === | === 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: | 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} | + | 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. | 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. | ||
Line 215: | Line 191: | ||
One you are happy with your changes, commit them to your local branch: | One you are happy with your changes, commit them to your local branch: | ||
− | + | ||
− | git add ${files} | + | git add ${files} |
− | git commit -s | + | 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): | 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): | ||
Line 252: | Line 227: | ||
When you are ready to push your commit (or commits) to gerrit, you can simply type: | When you are ready to push your commit (or commits) to gerrit, you can simply type: | ||
− | + | ||
− | git review | + | git review |
− | + | ||
and your commits will be pushed up to gerrit for code review. | and your commits will be pushed up to gerrit for code review. | ||
You have several options with git review, some handy ones include | You have several options with git review, some handy ones include | ||
− | + | git review -f | |
− | git review -f | + | |
− | + | ||
which will delete your local topic branch once you have pushed to gerrit (useful for keeping your local repo clean). | 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: | 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 checkout master |
− | git pull | + | git pull |
− | + | ||
==== Retrieving a gerrit patch to review it ==== | ==== Retrieving a gerrit patch to review it ==== | ||
Line 279: | Line 251: | ||
You can retrieve such a patch with: | You can retrieve such a patch with: | ||
− | + | ||
− | git review -d ${patch_number} | + | git review -d ${patch_number} |
− | + | ||
Example: | Example: | ||
For patch 1282 this would be: | For patch 1282 this would be: | ||
− | + | ||
− | git review -d 1282 | + | git review -d 1282 |
− | + | ||
==== Revising a gerrit patch ==== | ==== 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). | 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 | Instead, if you are revising a gerrit patch, you can simply --amend it with | ||
− | + | ||
− | git commit -s --amend | + | 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. | 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. |
Revision as of 20:46, 28 June 2016
Contents
- 1 Intro
- 2 Pulling
- 3 Building
- 4 Running
- 5 Hacking
- 6 Pushing
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
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 14.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 14.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
- Create a tuntap interface and trace a basic ping command
- Try out some of the other use cases
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
One 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
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.