kbuild: doc: improve KBUILD_BUILD_TIMESTAMP documentation

From: Gang Yan <[email protected]>

This patch adds an example of how to set KBUILD_BUILD_TIMESTAMP to a specific date. Also, note that the provided timestamp is used for initramfs mtime fields, which are 32-bit and thus limited to dates between the Unix epoch and 2106-02-07 06:28:15 UTC. Dates outside this range will cause errors.

Suggested-by David Disseldorp <[email protected]>

Signed-off-by Gang Yan <[email protected]>

Reviewed-by David Disseldorp <[email protected]>

---
Changelog:
v2:
- Replace the invalid example with a valid one.
- Apply David's suggestions.

---
 Documentation/kbuild/kbuild.rst | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

Quoted 11 lines · Gang Yan

From: Gang Yan <[email protected]>

This patch adds an example of how to set KBUILD_BUILD_TIMESTAMP to a specific date. Also, note that the provided timestamp is used for initramfs mtime fields, which are 32-bit and thus limited to dates between the Unix epoch and 2106-02-07 06:28:15 UTC. Dates outside this range will cause errors.

Suggested-by David Disseldorp <[email protected]>

Signed-off-by Gang Yan <[email protected]>

Reviewed-by David Disseldorp <[email protected]>

Quoted 9 lines

---
Changelog:
v2:
- Replace the invalid example with a valid one.
- Apply David's suggestions.

---
 Documentation/kbuild/kbuild.rst | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

Thanks to both of you!

I have only found a tiny nit-pick, see below.

Reviewed-by Nicolas Schier <[email protected]>

Documentation/kbuild/kbuild.rst KBUILD_BUILD_TIMESTAMP · line 333

Quoted 13 lines

Documentation/kbuild/kbuild.rst +3 -2

index 3388a10f2dcc..881189ecd0ca 100644
@@ -328,8 +328,14 @@ KBUILD_BUILD_TIMESTAMP
 ----------------------
 Setting this to a date string overrides the timestamp used in the
 UTS_VERSION definition (uname -v in the running kernel). The value has to
-be a string that can be passed to date -d. The default value
-is the output of the date command at one point during build.
+be a string that can be passed to date -d. E.g.::
+
+$ KBUILD_BUILD_TIMESTAMP="Mon Oct 13 00:00:00 UTC 2025" make

Other code blocks in kbuild.rst are indented by four spaces (and accidentally five in one line).

I can add these when applying the patch for kbuild-next, if that is ok for you.

Kind regards
Nicolas

This patch adds an example of how to set KBUILD_BUILD_TIMESTAMP to a specific date. Also, note that the provided timestamp is used for initramfs mtime fields, which are 32-bit and thus limited to dates between the Unix epoch and 2106-02-07 06:28:15 UTC. Dates outside this range will cause errors.

[...]