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>

5 files changed, 60 insertions, 2 deletions

diff --git a/build-data/packages/vpp.mk b/build-data/packages/vpp.mk
index 40aa8c79d23..4dd65ecb4fc 100644
--- a/build-data/packages/vpp.mk
+++ b/build-data/packages/vpp.mk
@@ -33,6 +33,9 @@ endif
 ifneq ($(VPP_EXCLUDED_PLUGINS),)
 vpp_cmake_args += -DVPP_EXCLUDED_PLUGINS="$(VPP_EXCLUDED_PLUGINS)"
 endif
+ifneq (${SOURCE_DATE_EPOCH}),)
+vpp_cmake_args += -DVPP_SOURCE_DATE_EPOCH="$(SOURCE_DATE_EPOCH)"
+endif
 
 ifneq ($(VPP_EXTRA_CMAKE_ARGS),)
 vpp_cmake_args += $(VPP_EXTRA_CMAKE_ARGS)
diff --git a/build/external/Makefile b/build/external/Makefile
index d648f4fa1c7..fb3cd94e526 100644
--- a/build/external/Makefile
+++ b/build/external/Makefile
@@ -21,6 +21,7 @@ BUILD_DIR        ?= $(CURDIR)/_build
 INSTALL_DIR      ?= $(CURDIR)/_install
 PKG_VERSION ?= $(shell git describe --abbrev=0 --match 'v[0-9]*' | cut -d- -f1 | cut -dv -f2 | cut -d. -f1,2)
 PKG_SUFFIX ?= $(shell git log --oneline v$(PKG_VERSION)-rc0.. . | wc -l)
+SOURCE_DATE_EPOCH ?= $(shell git log -1 --pretty=%ct .)
 JOBS := $(if $(shell [ -f /proc/cpuinfo ] && head /proc/cpuinfo),\
 	$(shell grep -c ^processor /proc/cpuinfo), 2)
 
@@ -68,7 +69,7 @@ deb/debian/changelog: Makefile
 	@echo "" >> $@
 	@echo "  * Version $(DEB_VER)" >> $@
 	@echo "" >> $@
-	@echo " -- VPP Dev <vpp-dev@lists.fd.io>  $(shell date -R)" >> $@
+	@echo " -- VPP Dev <vpp-dev@lists.fd.io>  $(shell date -R --date=@${SOURCE_DATE_EPOCH})" >> $@
 
 $(DEV_DEB): deb/debian/changelog
 	@cd deb && dpkg-buildpackage -b -uc -us
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
diff --git a/docs/spelling_wordlist.txt b/docs/spelling_wordlist.txt
index 21baa622c7e..e1dbef2eabf 100644
--- a/docs/spelling_wordlist.txt
+++ b/docs/spelling_wordlist.txt
@@ -110,6 +110,7 @@ bufferindex
 bufmon
 Bufmon
 bugfixing
+buildinfo
 buildingrst
 builtin
 builtinurl
diff --git a/src/pkg/CMakeLists.txt b/src/pkg/CMakeLists.txt
index 892ef71fb5e..5fa2826ad9a 100644
--- a/src/pkg/CMakeLists.txt
+++ b/src/pkg/CMakeLists.txt
@@ -18,8 +18,23 @@ endif()
 get_cmake_property(VPP_COMPONENTS COMPONENTS)
 string(REPLACE ";" " " VPP_COMPONENTS "${VPP_COMPONENTS}")
 
+##############################################################################
+# pinned timestamp for reproducible builds
+##############################################################################
+set(VPP_SOURCE_DATE_EPOCH
+   ""
+   CACHE
+   STRING "Artifact build timestamp for reproducible builds"
+)
+
+if(VPP_SOURCE_DATE_EPOCH STREQUAL "")
+   set(VPP_TIMESTAMP_ARG "")
+else()
+   set(VPP_TIMESTAMP_ARG "--date=@${VPP_SOURCE_DATE_EPOCH}")
+endif()
+
 execute_process(
-  COMMAND date -R
+  COMMAND date -R ${VPP_TIMESTAMP_ARG}
   OUTPUT_VARIABLE TIMESTAMP
   OUTPUT_STRIP_TRAILING_WHITESPACE
 )