docs/developer/build-run-debug/building.rst

   1 .. _building:
   2
   3 .. toctree::
   4
   5 Building VPP
   6 =====================
   7
   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`.
  10
  11 .. _makesureinstalled:
  12
  13 VPP for Ubuntu: Environment Setup
  14 -------------------------------------------
  15
  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'.
  18
  19 Before starting on VPP for Ubuntu, make sure WSL2 and Ubuntu are installed.
  20
  21 To install WSL2 and Ubuntu, run Windows PowerShell as an administrator and enter this in the terminal:
  22
  23 .. code-block:: console
  24
  25     $ wsl --install
  26
  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.
  30
  31 .. code-block:: console
  32
  33     $ cd /etc
  34     $ sudo nano resolv.conf
  35
  36 In the file, add the following content in place of the current 'nameserver X.X.X.X' line:
  37
  38 .. code-block:: console
  39
  40     nameserver 8.8.8.8
  41
  42 This replaces the DNS nameserver on your machine with the Google DNS service,
  43 resolving any DNS Internet connection issues.
  44
  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:
  47
  48 .. code-block:: console
  49
  50     $ sudo chattr +i /etc/resolv.conf
  51
  52
  53 Now copy the following lines from 'resolv.conf':
  54
  55 .. code-block:: console
  56
  57     [network]
  58     generateResolvConf = false
  59
  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.
  62
  63 .. code-block:: console
  64
  65     $ sudo nano wsl.conf
  66
  67 In order to test your DNS server connection, please ping 8.8.8.8 on the terminal:
  68
  69 .. code-block:: console
  70
  71     $ ping 8.8.8.8
  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
  81     ...
  82
  83 While still in /etc, run the following commands:
  84
  85 .. code-block:: console
  86
  87     $ sudo apt-get update
  88     $ sudo apt-get dist-upgrade
  89     $ sudo apt-get install --reinstall ca-certificates
  90     $ sudo update-ca-certificates
  91
  92
  93 Finally, head back to your home directory and jump to 'Get the VPP Sources'.
  94
  95 .. _setupproxies:
  96
  97 Set up Proxies
  98 --------------------------
  99
 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*:
 102
 103 .. code-block:: console
 104
 105     $ export http_proxy=http://<proxy-server-name>.com:<port-number>
 106     $ export https_proxy=https://<proxy-server-name>.com:<port-number>
 107
 108
 109 Get the VPP Sources
 110 -----------------------------------
 111
 112 To get the VPP sources that are used to create the build, run the following commands:
 113
 114 .. code-block:: console
 115
 116     $ git clone https://gerrit.fd.io/r/vpp
 117     $ cd vpp
 118
 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.
 126
 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.
 131
 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``
 134
 135 Build VPP Dependencies
 136 --------------------------------------
 137
 138 Before building a VPP image, make sure there are no FD.io VPP or DPDK packages
 139 installed, by entering the following commands:
 140
 141 .. code-block:: console
 142
 143     $ dpkg -l | grep vpp
 144     $ dpkg -l | grep DPDK
 145
 146 There should be no output, or no packages shown after the above commands are run.
 147
 148 Please make sure **make** is installed before running the next command.
 149 If it is not installed, run the following command first:
 150
 151 .. code-block:: console
 152
 153     $ sudo apt install make
 154
 155 Run the following **make** command to install the dependencies for FD.io VPP.
 156
 157 If the download hangs at any point, then you may need to
 158 :ref:`set up proxies <setupproxies>` for the download to work.
 159
 160 .. code-block:: console
 161
 162     $ make install-dep
 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]
 169     ...
 170     ...
 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...
 180
 181     done.
 182     done.
 183
 184 Build VPP (Debug)
 185 ----------------------------
 186
 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.
 190
 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*.
 194
 195 .. code-block:: console
 196
 197     $ make build
 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 @@@@
 207     ...
 208     ...
 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'
 215
 216 Build VPP (Release Version)
 217 -----------------------------------------
 218
 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*.
 222
 223 Use the following **make** command below to build the release version of FD.io VPP.
 224
 225 .. code-block:: console
 226
 227     $ make build-release
 228
 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:
 234
 235 .. code-block:: console
 236
 237     $ make install-ext-deps
 238
 239 -------------------------------------------
 240 Building Necessary Packages
 241 -------------------------------------------
 242
 243 The package that needs to be built depends on the type system VPP will be running on:
 244
 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
 247
 248 .. _debianpackages:
 249
 250 Building Debian Packages
 251 ^^^^^^^^^^^^^^^^^^^^^^^^^
 252
 253 To build the debian packages, use the following command:
 254
 255 .. code-block:: console
 256
 257     $ make pkg-deb
 258
 259 Reproducible builds on Debian
 260 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 261
 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.
 269
 270
 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.
 274
 275 The package vpp-ext-deps is already being built with that
 276 date set to date of the last modification of the
 277 build/external/ tree
 278 (similar to deriving the "number of commits" for the package
 279 versioning of vpp-ext-deps)
 280
 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:
 284
 285    .. code-block:: console
 286
 287     export SOURCE_DATE_EPOCH=$(date +%s)
 288     export VPP_BUILD_HOST="buildhost"
 289     export VPP_BUILD_USER="builduser"
 290
 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.
 296
 297 .. _rpmpackages:
 298
 299 Building RPM Packages
 300 ^^^^^^^^^^^^^^^^^^^^^^^
 301
 302 To build the rpm packages, use one of the following commands below, depending on the system:
 303
 304 .. code-block:: console
 305
 306     $ make pkg-rpm
 307
 308 Once the packages are built they can be found in the build-root directory.
 309
 310 .. code-block:: console
 311
 312     $ ls build-root/*.deb
 313
 314     If the packages are built correctly, then this should be the corresponding output:
 315
 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
 320
 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:
 323
 324 For Ubuntu:
 325
 326 .. code-block:: console
 327
 328    $ sudo dpkg -i build-root/*.deb
 329
 330 For Centos or Redhat:
 331
 332 .. code-block:: console
 333
 334    $ sudo rpm -ivh build-root/*.rpm