VPP/Setting Up Your Dev Environment

Intro

This page has been superceded by Pulling, Building, Running, Hacking, and Pushing VPP Code which should have more up to date information.

Install The Enviroment

You will need a virtual machine (Linux being the guest) and Vagrant software to host and launch the build environment. Vagrant is optional but makes your life easier.

Install Virtualbox or VMWare

The default configuration supports VMWare and VirtualBox. You will need to install *one* of them.

VirtualBox is free. You can download and install VirtualBox from here.

VMWare runs faster than VirtualBox, but requires purchase. You can acquire VMWare Fusion (Mac) or VMWare Workstation (Windows)

VMware runs faster than VirtualBox. To use VMware you will need to obtain a VMware plugin for Vagrant. You can learn more about support for VMware from the Vagrant documentation: https://docs.vagrantup.com/v2/vmware/.

LibVirt / qemu-kvm has been tested in development but is not officially supported. NOTE: The following vagrant plugin is useful if using libvirt: https://github.com/sciurus/vagrant-mutate

Install Vagrant software.

Install the Vagrant software: https://docs.vagrantup.com/v2/installation/index.html

Install vagrant-cachier

Optional: To cache apt/yum (for faster Vagrant VM rebuild), install vagrant-cachier.

At the unix command line run:

vagrant plugin install vagrant-cachier

Install Vagrant box puppetlabs/ubuntu-14.04-64-nocm

vagrant box add  --provider virtualbox https://atlas.hashicorp.com/puppetlabs/ubuntu-14.04-64-nocm

Install Vagrant box puppetlabs/centos-7.2-64-nocm

vagrant box add --provider virtualbox https://atlas.hashicorp.com/puppetlabs/centos-7.2-64-nocm

Install vagrant-mutate

Optionally install vagrant-mutate to convert virtualbox vagrant image to other provider formats (virtualbox, kvm, libvirt)

vagrant plugin install vagrant-mutate

Using ssh

Make sure you have registered your ssh key with gerrit.

Get the VPP source code.

a. Open a command-line interface (terminal window).

b. Change to the directory where you want to install VPP

cd $HOME/source/vpp

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

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

Using https

Get the VPP source code.

a. Open a command-line interface (terminal window).

b. Change to the directory where you want to install VPP

cd $HOME/source/vpp

c. Type the following git command:

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

Install cscope

cscope is a tool that can make browsing the code base much easier but it is not a requirement to run or to build VPP.

Installing on a Mac:

a. Install cscope on your mac following the instructions at: [http://macappstore.org/cscope/]

b. Go to the directory where you have installed VPP

cd $HOME/source/vpp

c. Run the following commands to create a cscope database file

find . -path .git -prune -o -name "*.[ch]" -print > cscope.files
cscope -b -q -k

d. Now you can explore the code base using cscope (-d command tells it not to regenerate the database)

cscope -d

e. For more information on how to use csocpe, check out http://cscope.sourceforge.net/

Installing on Windows:

Check out http://cscope.sourceforge.net/ for instructions on how to download and install on Windows

Customize Vagrant

The vagrant file included needs to be updated as follows. The file can be found at build-root/vagrant/Vagrantfile

vi ./build-root/vagrant/Vagrantfile

Change the CPU/Memory config of the VM (Optional)

You may wish to increase the number of CPU, amount of memory, or otherwise configure the Vagrant VM you're about to create. You can do so after creating the VM, as well. (note: builds may hang on virtualbox with 4096, increasing to 8092 solves this.)

Depending on which provider you are using, you can edit the appropriate section and set the memory or num of cpus

 
  config.vm.provider "virtualbox" do |vb|
    vb.memory = "4096"
  end
  config.vm.provider "vmware_fusion" do |fusion,override|
    fusion.vmx["memsize"] = "4096"
  end
  config.vm.provider "vmware_workstation" do |vws,override|
    vws.vmx["memsize"] = "8192"
    vws.vmx["numvcpus"] = "4"
  end

Change VPP_VAGRANT_NICS environment

The VPP_VAGRANT_NICS environment variable holds the number of networks to spin up in the guest environment

Configure http proxy (optional)

When running behind a proxy/firewall, you may need to set http_proxy and https_proxy in the environment. You can use the export command to make the following environmental variables available to child processes:

export http_proxy=http://<proxy-server>:<port>
export https_proxy=https://<proxy-server>:<port>

Vagrant can do this for you by installing proxyconf:

vagrant plugin install vagrant-proxyconf

Troubleshoot shared folders

An issue was observed on Mac OS X where shared files are not properly working in Virtual Box. The workaround is to define *absolute* paths in the VagrantFile.

-  config.vm.synced_folder "../../", "/vpp", disabled: false
+  config.vm.synced_folder "/absolute/path/to/vpp/build-root/vagrant/", "/vagrant", disabled: false
+  config.vm.synced_folder "/absolute/path/to/vpp", "/vpp", disabled: false

Next Steps

Try some of the following tutorials:

Build, install, and test images

Accessing gerrit repo from within DMZ machine

How To Connect A PCI Interface To VPP