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
259 Reproducible builds on Debian
260 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
262 By default the VPP artifacts have various bits of
263 information in them aimed at simplifying the identification
264 during the development (like, the user name that built
265 the package as well as the build times). By setting
266 a few environment variables one can obtain bit-identical
267 .deb files, assuming that the prerequisites installed
268 in the build environment are identical.
271 Setting and using the SOURCE_DATE_EPOCH variable
272 (see https://reproducible-builds.org/docs/source-date-epoch/)
273 takes care of most of the magic necessary.
275 The package vpp-ext-deps is already being built with that
276 date set to date of the last modification of the
278 (similar to deriving the "number of commits" for the package
279 versioning of vpp-ext-deps)
281 For the rest of the packages, pinning the following
282 three variables should result in bit-identical
283 artifacts across multiple runs in the build environment:
285 .. code-block:: console
287 export SOURCE_DATE_EPOCH=$(date +%s)
288 export VPP_BUILD_HOST="buildhost"
289 export VPP_BUILD_USER="builduser"
291 If you want to reproduce the bit-identical builds across
292 different environments, take a look at "vpp_<BUILD_VERSION>.buildinfo" file
293 which gets created in build-root alongside the .deb repositories -
294 it has the cryptographic hashes for the newly built packages, and
295 the full list of build dependencies and their versions.
299 Building RPM Packages
300 ^^^^^^^^^^^^^^^^^^^^^^^
302 To build the rpm packages, use one of the following commands below, depending on the system:
304 .. code-block:: console
308 Once the packages are built they can be found in the build-root directory.
310 .. code-block:: console
312 $ ls build-root/*.deb
314 If the packages are built correctly, then this should be the corresponding output:
316 vpp_18.07-rc0~456-gb361076_amd64.deb vpp-dbg_18.07-rc0~456-gb361076_amd64.deb
317 vpp-dev_18.07-rc0~456-gb361076_amd64.deb vpp-api-lua_18.07-rc0~456-gb361076_amd64.deb
318 vpp-lib_18.07-rc0~456-gb361076_amd64.deb vpp-api-python_18.07-rc0~456-gb361076_amd64.deb
319 vpp-plugins_18.07-rc0~456-gb361076_amd64.deb
321 Finally, the created packages can be installed using the following commands. Install
322 the package that corresponds to OS that VPP will be running on:
326 .. code-block:: console
328 $ sudo dpkg -i build-root/*.deb
330 For Centos or Redhat:
332 .. code-block:: console
334 $ sudo rpm -ivh build-root/*.rpm