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>

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)

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

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

docs/spelling_wordlist.txt

@@ -110,6 +110,7 @@ bufferindex
 bufmon
 Bufmon
 bugfixing
+buildinfo
 buildingrst
 builtin
 builtinurl

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
 )