Difference between revisions of "VPP/Setting Up Your Dev Environment"

From fd.io
< VPP
Jump to: navigation, search
(Installing on a Mac:)
 
(16 intermediate revisions by 13 users not shown)
Line 1: Line 1:
 +
== Intro ==
 +
 +
This page has been superceded by [[VPP/Pulling,_Building,_Running,_Hacking_and_Pushing_VPP_Code | Pulling, Building, Running, Hacking, and Pushing VPP Code]] which should have more
 +
up to date information.
 +
 
== Install The Enviroment ==
 
== Install The Enviroment ==
  
You will need a virtual machine and Vagrant software to host and launch the build environment.
+
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 ===   
 
=== Install Virtualbox or VMWare ===   
Line 12: Line 17:
  
 
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/.
 
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 Vagrant software. ===
Line 24: Line 32:
 
At the unix command line run:
 
At the unix command line run:
  
<pre>
+
vagrant plugin install vagrant-cachier
vagrant plugin install vagrant-cachier
+
 
</pre>
+
=== Install Vagrant box puppetlabs/ubuntu-14.04-64-nocm ===
 +
 
 +
vagrant box add  --provider virtualbox https://app.vagrantup.com/puppetlabs/boxes/ubuntu-16.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 [https://github.com/sciurus/vagrant-mutate#usage vagrant-mutate] to convert virtualbox vagrant image to other provider formats (virtualbox, kvm, libvirt)
 +
 
 +
vagrant plugin install vagrant-mutate
  
 
== Obtain The VPP Source Code ==
 
== Obtain The VPP Source Code ==
 +
 +
== Using ssh ==
  
 
Make sure you have <span style="background: LightPink">[[DEV/Setting_up_Gerrit|registered your ssh key with gerrit]].</span>
 
Make sure you have <span style="background: LightPink">[[DEV/Setting_up_Gerrit|registered your ssh key with gerrit]].</span>
Line 38: Line 60:
 
b. Change to the directory where you want to install VPP
 
b. Change to the directory where you want to install VPP
  
  cd $HOME/source/vpp
+
cd $HOME/source/vpp
  
c. Type the following git command (replacing USERNAME with your Linux Foundation username):
+
c. Type the following git command (replacing USERNAME with your [https://identity.linuxfoundation.org Linux Foundation] username):
  
<pre>git clone ssh://USERNAME@gerrit.fd.io:29418/vpp.git</pre>
+
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 ==
 
== Install cscope ==
cscope is a tool that can make browsing the code base much easier.  
+
 
 +
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: ====
 
==== Installing on a Mac: ====
  
a. Install cscope on your mac following the instructions at: [[http://macappstore.org/cscope/ http://macappstore.org/cscope/]]
+
a. Install cscope on your mac following the instructions at: [[https://ports.macports.org/port/cscope/ https://ports.macports.org/port/cscope/]]
 
   
 
   
 
b. Go to the directory where you have installed VPP
 
b. Go to the directory where you have installed VPP
  
  cd $HOME/source/vpp
+
cd $HOME/source/vpp
  
 
c. Run the following commands to create a cscope database file
 
c. Run the following commands to create a cscope database file
  
  find . -path .git -prune -o -name "*.[ch]" -print > cscope.files
+
find . -path .git -prune -o -name "*.[ch]" -print > cscope.files
  cscope -b -q -k
+
cscope -b -q -k
  
 
d. Now you can explore the code base using cscope (-d command tells it not to regenerate the database)
 
d. Now you can explore the code base using cscope (-d command tells it not to regenerate the database)
  
  cscope -d
+
cscope -d
  
 
e. For more information on how to use csocpe, check out [http://cscope.sourceforge.net/ http://cscope.sourceforge.net/]
 
e. For more information on how to use csocpe, check out [http://cscope.sourceforge.net/ http://cscope.sourceforge.net/]
Line 70: Line 107:
  
 
== Customize Vagrant  ==  
 
== Customize Vagrant  ==  
 +
 
The vagrant file included needs to be updated as follows. The file can be found at build-root/vagrant/Vagrantfile  
 
The vagrant file included needs to be updated as follows. The file can be found at build-root/vagrant/Vagrantfile  
  
<pre>vi ./build-root/vagrant/Vagrantfile</pre>
+
vi ./build-root/vagrant/Vagrantfile
  
  
 
=== Change the CPU/Memory config of the VM (Optional) ===
 
=== 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.
+
 
 +
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
 
Depending on which provider you are using, you can edit the appropriate section and set the memory or num of cpus
Line 92: Line 131:
 
   end
 
   end
 
</syntaxhighlight>
 
</syntaxhighlight>
 +
 +
=== 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) ===
 
=== 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:
 
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:
  
Line 101: Line 145:
 
Vagrant can do this for you by installing proxyconf:
 
Vagrant can do this for you by installing proxyconf:
  
  vagrant plugin install vagrant-proxyconf
+
vagrant plugin install vagrant-proxyconf
  
== Running  Vagrant ==
+
=== Troubleshoot shared folders ===
  
For more information about using Vagrant on a command-line interface (CLI), see: https://docs.vagrantup.com/v2/cli/index.html
+
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.
  
=== cd to the vagrant directory ===
+
-  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
  
In the command-line interface, navigate to the directory that has the pre-configured Vagrantfile. (In the following sample command, <install_dir> is the directory where you unzipped or cloned the VPP software.)
+
== Restconf/Netconf ==
  
<pre>$ cd <install_dir>/build-root/vagrant/</pre>
+
Lisp ONE functionality can be also used with use of Restconf/Netconf protocols and Honeycomb project.
  
<blockquote>
+
For further details how to setup Honeycomb with VPP follow  this [https://wiki.fd.io/view/Honeycomb/Releases/1609#Install_guide] guide.
NOTE: The .../build-root directory contains the files that make up most of the build
+
system. It contains all of the generic targets, including: xxx-build, xxx-rebuild, xxx-install, xxx-clean, xxx-wipe, xxx-configure, and xxx-find-source.
+
</blockquote>
+
 
+
=== Build the VM with Vagrant ===
+
 
+
By default this will build an Ubuntu 14.0.4 VM.
+
 
+
If you wish instead to build a Centos7 VM instead:
+
<pre>$ (export VPP_VAGRANT_DISTRO=centos7;vagrant up)</pre>
+
 
+
If you wish to use VMWareFusion as your provider, use:
+
<pre>(export VAGRANT_DEFAULT_PROVIDER=vmware_fusion;vagrant up)</pre>
+
 
+
When you first start Vagrant, it is normal for it to run for several minutes, building the VM, building VPP, and then a README will be displayed telling you how to run VPP.
+
 
+
Use the Vagrant up command to cause Vagrant to start. Vagrant uses the Vagrantfile in the current working directory.
+
 
+
<pre>$ vagrant up</pre>
+
 
+
 
+
=== Access the shell ===
+
 
+
Use the Vagrant SSH command to access the running Vagrant machine and give you access to a shell.
+
 
+
<pre>$ vagrant ssh</pre>
+
 
+
If you wish to forward X-windows server requests, use this variation:
+
 
+
<pre>$ vagrant ssh -- -X</pre>
+
 
+
Success!
+
 
+
You've set up the basic environment that you need in order to start building the VPP codebase.
+
  
 
== Next Steps ==
 
== Next Steps ==
  
 
Try some of the following tutorials:
 
Try some of the following tutorials:
 +
 +
[[VPP/Build, install, and test images| Build, install, and test images]]
  
 
[[DEV/Chaining_Git_Over_SSH | Accessing gerrit repo from within DMZ machine]]
 
[[DEV/Chaining_Git_Over_SSH | Accessing gerrit repo from within DMZ machine]]
  
 
[[VPP/How To Connect A PCI Interface To VPP| How To Connect A PCI Interface To VPP]]
 
[[VPP/How To Connect A PCI Interface To VPP| How To Connect A PCI Interface To VPP]]

Latest revision as of 16:14, 10 June 2022

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://app.vagrantup.com/puppetlabs/boxes/ubuntu-16.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

Obtain The VPP Source Code

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: [https://ports.macports.org/port/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

Restconf/Netconf

Lisp ONE functionality can be also used with use of Restconf/Netconf protocols and Honeycomb project.

For further details how to setup Honeycomb with VPP follow this [1] guide.

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