build: allow for reproducible builds

[vpp.git] / docs / developer / build-run-debug / building.rst

diff --git a/docs/developer/build-run-debug/building.rst b/docs/developer/build-run-debug/building.rst
index d01eff7..6106a71 100644 (file)
--- a/docs/developer/build-run-debug/building.rst
+++ b/docs/developer/build-run-debug/building.rst
@@ -116,6 +116,22 @@ To get the VPP sources that are used to create the build, run the following comm
     $ 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
 --------------------------------------
 
@@ -240,6 +256,44 @@ To build the debian packages, use the following command:
 
     $ 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
@@ -255,7 +309,7 @@ Once the packages are built they can be found in the build-root directory.
 
 .. code-block:: console
 
-    $ ls *.deb
+    $ ls build-root/*.deb
 
     If the packages are built correctly, then this should be the corresponding output:
 
@@ -271,12 +325,10 @@ For Ubuntu:
 
 .. 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