[PATCH v3 4/5] change the proposed interface to set the SDE

[Felix Moessbauer <felix.moessbauer@siemens.com>]

To align the handling of source timestamps with OE, we propose to not
set the SOURCE_DATE_EPOCH variable directly, but via
`SOURCE_DATE_EPOCH_FALLBACK`. By that, we internally can use heuristics
to better estimate the value of the SDE, while still having a global
fallback if it cannot be estimated otherwise.

Please note, that change is backwards compatible. You can still set the
SOURCE_DATE_EPOCH variable directly and get the same behavior as before.

This patch also updates the reproducibility test according to the new
interface.

Signed-off-by: Felix Moessbauer <felix.moessbauer@siemens.com>
---
 RECIPE-API-CHANGELOG.md | 6 ++++++
 doc/user_manual.md      | 1 +
 testsuite/cibuilder.py  | 2 +-
 3 files changed, 8 insertions(+), 1 deletion(-)

diff --git a/RECIPE-API-CHANGELOG.md b/RECIPE-API-CHANGELOG.md
index e6861523..4afe8b16 100644
--- a/RECIPE-API-CHANGELOG.md
+++ b/RECIPE-API-CHANGELOG.md
@@ -589,3 +589,9 @@ compilation for a user-provided module when building it for a distro kernel.
 To build against a distributions snapshot mirror, set `ISAR_USE_APT_SNAPSHOT="1"`.
 The mirror to use is specified in `DISTRO_APT_SNAPSHOT_PREMIRROR` and usually
 pre-defined in the distro config.
+
+### Use OE interface to set timestamp for reproducible builds
+
+The `SOURCE_DATE_EPOCH` (SDE) should not be set globally, but on a per-recipe basis
+and to meaningful values. As a global fallback, set the `SOURCE_DATE_EPOCH_FALLBACK`
+bitbake variable to the desired unix timestamp.
diff --git a/doc/user_manual.md b/doc/user_manual.md
index 70741968..b12c7692 100644
--- a/doc/user_manual.md
+++ b/doc/user_manual.md
@@ -425,6 +425,7 @@ Some other variables include:
 
  - `IMAGE_INSTALL` - The list of custom packages to build and install to target image, please refer to relative chapter for more information.
  - `BB_NUMBER_THREADS` - The number of `bitbake` jobs that can be run in parallel. Please set this option according to your host CPU cores number.
+ - `SOURCE_DATE_EPOCH_FALLBACK` - The unix timestamp passed to all tooling to make the results reproducible. This variable is optional.
  - `HOST_DISTRO` - The distro to use for SDK root filesystem. This variable is optional.
  - `HOST_ARCH` - The Debian architecture of SDK root filesystem (e.g., `amd64`). By default set to current Debian host architecture. This variable is optional.
  - `HOST_DISTRO_APT_SOURCES` - List of apt source files for SDK root filesystem. This variable is optional.
diff --git a/testsuite/cibuilder.py b/testsuite/cibuilder.py
index fa30c2f5..7e69dafe 100755
--- a/testsuite/cibuilder.py
+++ b/testsuite/cibuilder.py
@@ -159,7 +159,7 @@ class CIBuilder(Test):
                 f.write('USE_CCACHE = "1"\n')
                 f.write('CCACHE_TOP_DIR = "%s"\n' % ccache_dir)
             if source_date_epoch:
-                f.write('SOURCE_DATE_EPOCH = "%s"\n' % source_date_epoch)
+                f.write('SOURCE_DATE_EPOCH_FALLBACK = "%s"\n' % source_date_epoch)
             if dl_dir:
                 f.write('DL_DIR = "%s"\n' % dl_dir)
             if sstate_dir:
-- 
2.39.2