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

From fd.io
< VPP
Jump to: navigation, search
(→‎Obtain The VPP Source Code)
(→‎Installing on a Mac:)
 
(31 intermediate revisions by 15 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 ==
  
−
Make sure you have <span style="background:red">[[DEV/Setting_up_Gerrit|registered your ssh key with gerrit]].</span>
+
== Using ssh ==
 +
 
 +
Make sure you have <span style="background: LightPink">[[DEV/Setting_up_Gerrit|registered your ssh key with gerrit]].</span>
  
 
Get the VPP source code.
 
Get the VPP source code.
Line 36: Line 58:
 
a. Open a command-line interface (terminal window).
 
a. Open a command-line interface (terminal window).
  
−
b. Type the following git command (replacing USERNAME with your Linux Foundation username):
+
b. Change to the directory where you want to install VPP
  
−
<pre>git clone ssh://USERNAME@gerrit.fd.io:29418/vpp.git</pre>
+
cd $HOME/source/vpp
  
−
== Customize Vagrant (optional) ==
+
c. Type the following git command (replacing USERNAME with your [https://identity.linuxfoundation.org Linux Foundation] username):
  
−
=== Customize the Vagrantfile (optional) ===
+
git clone ssh://USERNAME@gerrit.fd.io:29418/vpp.git
  
−
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.
+
== Using https ==
  
−
<pre>emacs ./build-root/vagrant/Vagrantfile</pre>
+
Get the VPP source code.
  
 +
a. Open a command-line interface (terminal window).
  
−
=== Configure http proxy (optional) ===
+
b. Change to the directory where you want to install VPP
−
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>
+
  cd $HOME/source/vpp
−
export https_proxy=https://<proxy-server>:<port>
+
  
−
Vagrant can do this for you by installing proxyconf:
+
c. Type the following git command:
  
−
  vagrant plugin install vagrant-proxyconf
+
git clone https://gerrit.fd.io/r/vpp
  
−
== Running  Vagrant ==
+
== Install cscope ==
  
−
For more information about using Vagrant on a command-line interface (CLI), see: https://docs.vagrantup.com/v2/cli/index.html
+
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.  
  
−
=== cd to the vagrant directory ===
+
==== Installing on a Mac: ====
  
−
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.)
+
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
  
−
<pre>$ cd <install_dir>/build-root/vagrant/</pre>
+
cd $HOME/source/vpp
  
−
<blockquote>
+
c. Run the following commands to create a cscope database file
−
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>
+
  
−
=== Start Vagrant ===
+
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/ http://cscope.sourceforge.net/]
 +
 
 +
==== Installing on Windows: ====
 +
Check out [http://cscope.sourceforge.net/ 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
 +
 
 +
<syntaxhighlight lang="ruby">
 +
  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
 +
</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) ===
 +
 
 +
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:
  
−
Use the Vagrant up command to cause Vagrant to start. Vagrant uses the Vagrantfile in the current working directory.
+
vagrant plugin install vagrant-proxyconf
  
−
<pre>$ vagrant up</pre>
+
=== Troubleshoot shared folders ===
  
−
By default this will build an Ubuntu 14.0.4 VM.  If you wish instead to build a Centos7 VM instead:
+
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.
  
−
<pre>$ (export VPP_VAGRANT_DISTRO=centos7;vagrant up)</pre>
+
-  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
  
−
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.
+
== Restconf/Netconf ==
  
−
=== Access the shell ===
+
Lisp ONE functionality can be also used with use of Restconf/Netconf protocols and Honeycomb project.
  
−
Use the Vagrant SSH command to access the running Vagrant machine and give you access to a shell.
+
For further details how to setup Honeycomb with VPP follow  this [https://wiki.fd.io/view/Honeycomb/Releases/1609#Install_guide] guide.
  
−
<pre>$ vagrant ssh</pre>
+
== Next Steps ==
  
−
If you wish to forward X-windows server requests, use this variation:  
+
Try some of the following tutorials:
  
−
<pre>$ vagrant ssh -- -X</pre>
+
[[VPP/Build, install, and test images| Build, install, and test images]]
  
−
Success!
+
[[DEV/Chaining_Git_Over_SSH | Accessing gerrit repo from within DMZ machine]]
  
−
You've set up the basic environment that you need in order to start building the VPP codebase.
+
[[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

Retrieved from "https://wiki.fd.io/index.php?title=VPP/Setting_Up_Your_Dev_Environment&oldid=11757"