.. toctree::
Building VPP
-============
+=====================
To get started developing with VPP, you need to get the required VPP sources and then build the packages.
For more detailed information on the build system please refer to :ref:`buildsystem`.
+.. _makesureinstalled:
+
+VPP for Ubuntu: Environment Setup
+-------------------------------------------
+
+If you are not downloading VPP on Ubuntu with WSL (Windows Subsystem for Linux), please disregard this section
+and jump to 'Get the VPP Sources'.
+
+Before starting on VPP for Ubuntu, make sure WSL2 and Ubuntu are installed.
+
+To install WSL2 and Ubuntu, run Windows PowerShell as an administrator and enter this in the terminal:
+
+.. code-block:: console
+
+ $ wsl --install
+
+Next, go to the 'resolv.conf' file in Ubuntu's '/etc' folder.
+It should have been automatically generated when Ubuntu was installed; if it doesn't exist, create it.
+Please use 'sudo' to avoid "File resolv.conf is unwritable" errors.
+
+.. code-block:: console
+
+ $ cd /etc
+ $ sudo nano resolv.conf
+
+In the file, add the following content in place of the current 'nameserver X.X.X.X' line:
+
+.. code-block:: console
+
+ nameserver 8.8.8.8
+
+This replaces the DNS nameserver on your machine with the Google DNS service,
+resolving any DNS Internet connection issues.
+
+Note: by default, the 'resolv.conf' file regenerates every time you restart Ubuntu, so your changes won't be saved.
+To keep your changes, run the following command to make 'resolv.conf' immutable:
+
+.. code-block:: console
+
+ $ sudo chattr +i /etc/resolv.conf
+
+
+Now copy the following lines from 'resolv.conf':
+
+.. code-block:: console
+
+ [network]
+ generateResolvConf = false
+
+Then, go to the 'wsl.conf' file in '/etc' and paste the lines there.
+Please use 'sudo' here as well to avoid "File wsl.conf is unwritable" errors.
+
+.. code-block:: console
+
+ $ sudo nano wsl.conf
+
+In order to test your DNS server connection, please ping 8.8.8.8 on the terminal:
+
+.. code-block:: console
+
+ $ ping 8.8.8.8
+ PING 8.8.8.8 (8.8.8.8) 56(84) bytes of data.
+ 64 bytes from 8.8.8.8: icmp_seq=1 ttl=116 time=9.58 ms
+ 64 bytes from 8.8.8.8: icmp_seq=2 ttl=116 time=45.8 ms
+ 64 bytes from 8.8.8.8: icmp_seq=3 ttl=116 time=9.62 ms
+ 64 bytes from 8.8.8.8: icmp_seq=4 ttl=116 time=11.4 ms
+ 64 bytes from 8.8.8.8: icmp_seq=5 ttl=116 time=12.2 ms
+ 64 bytes from 8.8.8.8: icmp_seq=6 ttl=116 time=8.69 ms
+ 64 bytes from 8.8.8.8: icmp_seq=7 ttl=116 time=52.4 ms
+ 64 bytes from 8.8.8.8: icmp_seq=8 ttl=116 time=11.0 ms
+ ...
+
+While still in /etc, run the following commands:
+
+.. code-block:: console
+
+ $ sudo apt-get update
+ $ sudo apt-get dist-upgrade
+ $ sudo apt-get install --reinstall ca-certificates
+ $ sudo update-ca-certificates
+
+
+Finally, head back to your home directory and jump to 'Get the VPP Sources'.
+
.. _setupproxies:
Set up Proxies
$ git clone https://gerrit.fd.io/r/vpp
$ cd vpp
+As VPP version is derived from git description (which is based on git tags),
+if the github generated tarballs are used, the version information
+will be missing from the version file (.../src/scripts/.version)
+which is required by the version script when building
+in a non-git based workspace or the build will fail.
+In that case, put the desired version string into
+.../src/scripts/.version to satisfy the requirements of the version script.
+
+Alternatively, the ``make dist`` command in a cloned git workspace
+will generate an xz compressed tarball of the source
+including the .../src/scripts/.version file containing the git hash
+using the standard nomenclature for VPP images.
+
+Extract the tarball using the -J option to decompress it using xz. For example,
+``tar xvJf ./build-root/vpp-23.10-rc0~184-g48cd559fb.tar.xz``
+
Build VPP Dependencies
--------------------------------------
There should be no output, or no packages shown after the above commands are run.
+Please make sure **make** is installed before running the next command.
+If it is not installed, run the following command first:
+
+.. code-block:: console
+
+ $ sudo apt install make
+
Run the following **make** command to install the dependencies for FD.io VPP.
If the download hangs at any point, then you may need to
$ make build-release
+Installing External Dependencies
+-------------------------------------------
+At this point, there are still some VPP external dependencies left to install. They could be installed
+using 'make-build', but this only installs them locally in the VPP tree, not in the operating system.
+In order to fix this and save time, run the following command:
+
+.. code-block:: console
+
+ $ make install-ext-deps
+-------------------------------------------
Building Necessary Packages
---------------------------------------------
+-------------------------------------------
The package that needs to be built depends on the type system VPP will be running on:
$ make pkg-deb
+Reproducible builds on Debian
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+By default the VPP artifacts have various bits of
+information in them aimed at simplifying the identification
+during the development (like, the user name that built
+the package as well as the build times). By setting
+a few environment variables one can obtain bit-identical
+.deb files, assuming that the prerequisites installed
+in the build environment are identical.
+
+
+Setting and using the SOURCE_DATE_EPOCH variable
+(see https://reproducible-builds.org/docs/source-date-epoch/)
+takes care of most of the magic necessary.
+
+The package vpp-ext-deps is already being built with that
+date set to date of the last modification of the
+build/external/ tree
+(similar to deriving the "number of commits" for the package
+versioning of vpp-ext-deps)
+
+For the rest of the packages, pinning the following
+three variables should result in bit-identical
+artifacts across multiple runs in the build environment:
+
+ .. code-block:: console
+
+ export SOURCE_DATE_EPOCH=$(date +%s)
+ export VPP_BUILD_HOST="buildhost"
+ export VPP_BUILD_USER="builduser"
+
+If you want to reproduce the bit-identical builds across
+different environments, take a look at "vpp_<BUILD_VERSION>.buildinfo" file
+which gets created in build-root alongside the .deb repositories -
+it has the cryptographic hashes for the newly built packages, and
+the full list of build dependencies and their versions.
+
.. _rpmpackages:
Building RPM Packages
.. code-block:: console
- $ ls *.deb
+ $ ls build-root/*.deb
If the packages are built correctly, then this should be the corresponding output:
.. code-block:: console
- $ sudo bash
- # dpkg -i *.deb
+ $ sudo dpkg -i build-root/*.deb
For Centos or Redhat:
.. code-block:: console
- $ sudo bash
- # rpm -ivh *.rpm
+ $ sudo rpm -ivh build-root/*.rpm
Code Review / vpp.git / blobdiff