build: allow for reproducible builds

Setting and using the SOURCE_DATE_EPOCH variable takes
care of most of the magic necessary.
https://reproducible-builds.org/docs/source-date-epoch/

vpp-ext-deps packages after this change is being built with that
date set to date of the last modification of the
subtree (similar logic to deriving the "number" for
the package version)

For the rest of the packages, pinning the following
three variables should result in bit-identical
artifacts across multiple runs:

export SOURCE_DATE_EPOCH=$(date +%s)
export VPP_BUILD_HOST="buildhost"
export VPP_BUILD_USER="builduser"

Add a blurb in the docs describing this new functionality.

Type: improvement
Change-Id: I71b085f0577b2358aa98f01dafd8e392239420a6
Signed-off-by: Andrew Yourtchenko <ayourtch@gmail.com>

1 files changed, 38 insertions, 0 deletions

diff --git a/docs/developer/build-run-debug/building.rst b/docs/developer/build-run-debug/building.rst
index 9e9e79db376..6106a710d28 100644
--- a/docs/developer/build-run-debug/building.rst
+++ b/docs/developer/build-run-debug/building.rst
@@ -256,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