8 To get started developing with VPP, you need to get the required VPP sources and then build the packages.
9 For more detailed information on the build system please refer to :ref:`buildsystem`.
11 .. _makesureinstalled:
13 VPP for Ubuntu: Environment Setup
14 -------------------------------------------
16 If you are not downloading VPP on Ubuntu with WSL (Windows Subsystem for Linux), please disregard this section
17 and jump to 'Get the VPP Sources'.
19 Before starting on VPP for Ubuntu, make sure WSL2 and Ubuntu are installed.
21 To install WSL2 and Ubuntu, run Windows PowerShell as an administrator and enter this in the terminal:
23 .. code-block:: console
27 Next, go to the 'resolv.conf' file in Ubuntu's '/etc' folder.
28 It should have been automatically generated when Ubuntu was installed; if it doesn't exist, create it.
29 Please use 'sudo' to avoid "File resolv.conf is unwritable" errors.
31 .. code-block:: console
34 $ sudo nano resolv.conf
36 In the file, add the following content in place of the current 'nameserver X.X.X.X' line:
38 .. code-block:: console
42 This replaces the DNS nameserver on your machine with the Google DNS service,
43 resolving any DNS Internet connection issues.
45 Note: by default, the 'resolv.conf' file regenerates every time you restart Ubuntu, so your changes won't be saved.
46 To keep your changes, run the following command to make 'resolv.conf' immutable:
48 .. code-block:: console
50 $ sudo chattr +i /etc/resolv.conf
53 Now copy the following lines from 'resolv.conf':
55 .. code-block:: console
58 generateResolvConf = false
60 Then, go to the 'wsl.conf' file in '/etc' and paste the lines there.
61 Please use 'sudo' here as well to avoid "File wsl.conf is unwritable" errors.
63 .. code-block:: console
67 In order to test your DNS server connection, please ping 8.8.8.8 on the terminal:
69 .. code-block:: console
72 PING 8.8.8.8 (8.8.8.8) 56(84) bytes of data.
73 64 bytes from 8.8.8.8: icmp_seq=1 ttl=116 time=9.58 ms
74 64 bytes from 8.8.8.8: icmp_seq=2 ttl=116 time=45.8 ms
75 64 bytes from 8.8.8.8: icmp_seq=3 ttl=116 time=9.62 ms
76 64 bytes from 8.8.8.8: icmp_seq=4 ttl=116 time=11.4 ms
77 64 bytes from 8.8.8.8: icmp_seq=5 ttl=116 time=12.2 ms
78 64 bytes from 8.8.8.8: icmp_seq=6 ttl=116 time=8.69 ms
79 64 bytes from 8.8.8.8: icmp_seq=7 ttl=116 time=52.4 ms
80 64 bytes from 8.8.8.8: icmp_seq=8 ttl=116 time=11.0 ms
83 While still in /etc, run the following commands:
85 .. code-block:: console
88 $ sudo apt-get dist-upgrade
89 $ sudo apt-get install --reinstall ca-certificates
90 $ sudo update-ca-certificates
93 Finally, head back to your home directory and jump to 'Get the VPP Sources'.
98 --------------------------
100 Depending on the environment you are operating in, proxies may need to be set.
101 Run these proxy commands to specify the *proxy-server-name* and corresponding *port-number*:
103 .. code-block:: console
105 $ export http_proxy=http://<proxy-server-name>.com:<port-number>
106 $ export https_proxy=https://<proxy-server-name>.com:<port-number>
110 -----------------------------------
112 To get the VPP sources that are used to create the build, run the following commands:
114 .. code-block:: console
116 $ git clone https://gerrit.fd.io/r/vpp
119 As VPP version is derived from git description (which is based on git tags),
120 if the github generated tarballs are used, the version information
121 will be missing from the version file (.../src/scripts/.version)
122 which is required by the version script when building
123 in a non-git based workspace or the build will fail.
124 In that case, put the desired version string into
125 .../src/scripts/.version to satisfy the requirements of the version script.
127 Alternatively, the ``make dist`` command in a cloned git workspace
128 will generate an xz compressed tarball of the source
129 including the .../src/scripts/.version file containing the git hash
130 using the standard nomenclature for VPP images.
132 Extract the tarball using the -J option to decompress it using xz. For example,
133 ``tar xvJf ./build-root/vpp-23.10-rc0~184-g48cd559fb.tar.xz``
135 Build VPP Dependencies
136 --------------------------------------
138 Before building a VPP image, make sure there are no FD.io VPP or DPDK packages
139 installed, by entering the following commands:
141 .. code-block:: console
144 $ dpkg -l | grep DPDK
146 There should be no output, or no packages shown after the above commands are run.
148 Please make sure **make** is installed before running the next command.
149 If it is not installed, run the following command first:
151 .. code-block:: console
153 $ sudo apt install make
155 Run the following **make** command to install the dependencies for FD.io VPP.
157 If the download hangs at any point, then you may need to
158 :ref:`set up proxies <setupproxies>` for the download to work.
160 .. code-block:: console
163 Hit:1 http://us.archive.ubuntu.com/ubuntu xenial InRelease
164 Get:2 http://us.archive.ubuntu.com/ubuntu xenial-updates InRelease [109 kB]
165 Get:3 http://security.ubuntu.com/ubuntu xenial-security InRelease [107 kB]
166 Get:4 http://us.archive.ubuntu.com/ubuntu xenial-backports InRelease [107 kB]
167 Get:5 http://us.archive.ubuntu.com/ubuntu xenial-updates/main amd64 Packages [803 kB]
168 Get:6 http://us.archive.ubuntu.com/ubuntu xenial-updates/main i386 Packages [732 kB]
171 Update-alternatives: using /usr/lib/jvm/java-8-openjdk-amd64/bin/jmap to provide /usr/bin/jmap (jmap) in auto mode
172 Setting up default-jdk-headless (2:1.8-56ubuntu2) ...
173 Processing triggers for libc-bin (2.23-0ubuntu3) ...
174 Processing triggers for systemd (229-4ubuntu6) ...
175 Processing triggers for ureadahead (0.100.0-19) ...
176 Processing triggers for ca-certificates (20160104ubuntu1) ...
177 Updating certificates in /etc/ssl/certs...
178 0 added, 0 removed; done.
179 Running hooks in /etc/ca-certificates/update.d...
185 ----------------------------
187 This build version contains debug symbols which are useful for modifying VPP. The
188 **make** command below builds a debug version of VPP. The binaries, when building the
189 debug images, can be found in /build-root/vpp_debug-native.
191 The Debug build version contains debug symbols, which are useful for troubleshooting
192 or modifying VPP. The **make** command below, builds a debug version of VPP. The
193 binaries used for building the debug image can be found in */build-root/vpp_debug-native*.
195 .. code-block:: console
198 make[1]: Entering directory '/home/vagrant/vpp-master/build-root'
199 @@@@ Arch for platform 'vpp' is native @@@@
200 @@@@ Finding source for dpdk @@@@
201 @@@@ Makefile fragment found in /home/vagrant/vpp-master/build-data/packages/dpdk.mk @@@@
202 @@@@ Source found in /home/vagrant/vpp-master/dpdk @@@@
203 @@@@ Arch for platform 'vpp' is native @@@@
204 @@@@ Finding source for vpp @@@@
205 @@@@ Makefile fragment found in /home/vagrant/vpp-master/build-data/packages/vpp.mk @@@@
206 @@@@ Source found in /home/vagrant/vpp-master/src @@@@
209 make[5]: Leaving directory '/home/vagrant/vpp-master/build-root/build-vpp_debug-native/vpp/vpp-api/java'
210 make[4]: Leaving directory '/home/vagrant/vpp-master/build-root/build-vpp_debug-native/vpp/vpp-api/java'
211 make[3]: Leaving directory '/home/vagrant/vpp-master/build-root/build-vpp_debug-native/vpp'
212 make[2]: Leaving directory '/home/vagrant/vpp-master/build-root/build-vpp_debug-native/vpp'
213 @@@@ Installing vpp: nothing to do @@@@
214 make[1]: Leaving directory '/home/vagrant/vpp-master/build-root'
216 Build VPP (Release Version)
217 -----------------------------------------
219 This section describes how to build the regular release version of FD.io VPP. The
220 release build is optimized and does not create any debug symbols.
221 The binaries used in building the release images are found in */build-root/vpp-native*.
223 Use the following **make** command below to build the release version of FD.io VPP.
225 .. code-block:: console
229 Installing External Dependencies
230 -------------------------------------------
231 At this point, there are still some VPP external dependencies left to install. They could be installed
232 using 'make-build', but this only installs them locally in the VPP tree, not in the operating system.
233 In order to fix this and save time, run the following command:
235 .. code-block:: console
237 $ make install-ext-deps
239 -------------------------------------------
240 Building Necessary Packages
241 -------------------------------------------
243 The package that needs to be built depends on the type system VPP will be running on:
245 * The :ref:`Debian package <debianpackages>` is built if VPP is going to run on Ubuntu
246 * The :ref:`RPM package <rpmpackages>` is built if VPP is going to run on Centos or Redhat
250 Building Debian Packages
251 ^^^^^^^^^^^^^^^^^^^^^^^^^
253 To build the debian packages, use the following command:
255 .. code-block:: console
261 Building RPM Packages
262 ^^^^^^^^^^^^^^^^^^^^^^^
264 To build the rpm packages, use one of the following commands below, depending on the system:
266 .. code-block:: console
270 Once the packages are built they can be found in the build-root directory.
272 .. code-block:: console
274 $ ls build-root/*.deb
276 If the packages are built correctly, then this should be the corresponding output:
278 vpp_18.07-rc0~456-gb361076_amd64.deb vpp-dbg_18.07-rc0~456-gb361076_amd64.deb
279 vpp-dev_18.07-rc0~456-gb361076_amd64.deb vpp-api-lua_18.07-rc0~456-gb361076_amd64.deb
280 vpp-lib_18.07-rc0~456-gb361076_amd64.deb vpp-api-python_18.07-rc0~456-gb361076_amd64.deb
281 vpp-plugins_18.07-rc0~456-gb361076_amd64.deb
283 Finally, the created packages can be installed using the following commands. Install
284 the package that corresponds to OS that VPP will be running on:
288 .. code-block:: console
290 $ sudo dpkg -i build-root/*.deb
292 For Centos or Redhat:
294 .. code-block:: console
296 $ sudo rpm -ivh build-root/*.rpm