[PATCH, v2] kbuild: doc: improve KBUILD_BUILD_TIMESTAMP documentation

[PATCH, v2] kbuild: doc: improve KBUILD_BUILD_TIMESTAMP documentation

[Gang Yan]

From: Gang Yan <yangang@kylinos.cn>

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 <ddiss@suse.de>
Signed-off-by: Gang Yan <yangang@kylinos.cn>
Reviewed-by: David Disseldorp <ddiss@suse.de>
---
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(-)

diff --git a/Documentation/kbuild/kbuild.rst b/Documentation/kbuild/kbuild.rst
index 3388a10f2dcc..881189ecd0ca 100644
--- a/Documentation/kbuild/kbuild.rst
+++ b/Documentation/kbuild/kbuild.rst
@@ -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
+
+The default value is the output of the date command at one point during
+build. If provided, this timestamp will also be used for mtime fields
+within any initramfs archive. Initramfs mtimes are 32-bit, so dates before
+the 1970 Unix epoch, or after 2106-02-07 06:28:15 UTC will fail.
 
 KBUILD_BUILD_USER, KBUILD_BUILD_HOST
 ------------------------------------
-- 
2.43.0

Re: [PATCH, v2] kbuild: doc: improve KBUILD_BUILD_TIMESTAMP documentation

[Nicolas Schier]

On Fri, Oct 17, 2025 at 10:12:09AM +0800, Gang Yan wrote:
> From: Gang Yan <yangang@kylinos.cn>
> 
> 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 <ddiss@suse.de>
> Signed-off-by: Gang Yan <yangang@kylinos.cn>
> Reviewed-by: David Disseldorp <ddiss@suse.de>
> ---
> 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 <nsc@kernel.org>

> diff --git a/Documentation/kbuild/kbuild.rst b/Documentation/kbuild/kbuild.rst
> index 3388a10f2dcc..881189ecd0ca 100644
> --- a/Documentation/kbuild/kbuild.rst
> +++ b/Documentation/kbuild/kbuild.rst
> @@ -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

Re: [PATCH, v2] kbuild: doc: improve KBUILD_BUILD_TIMESTAMP documentation

[GangYan]

> On Fri, Oct 17, 2025 at 09:54:12PM +0200, Nicolas Schier wrote:
> On Fri, Oct 17, 2025 at 10:12:09AM +0800, Gang Yan wrote:
> > From: Gang Yan <yangang@kylinos.cn>
> > 
> > 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 <ddiss@suse.de>
> > Signed-off-by: Gang Yan <yangang@kylinos.cn>
> > Reviewed-by: David Disseldorp <ddiss@suse.de>
> > ---
> > 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 <nsc@kernel.org>
> 
> > diff --git a/Documentation/kbuild/kbuild.rst b/Documentation/kbuild/kbuild.rst
> > index 3388a10f2dcc..881189ecd0ca 100644
> > --- a/Documentation/kbuild/kbuild.rst
> > +++ b/Documentation/kbuild/kbuild.rst
> > @@ -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.
Sure, Thanks alot.
> 
> Kind regards
> Nicolas

Cherrs,
Gang

Re: [PATCH, v2] kbuild: doc: improve KBUILD_BUILD_TIMESTAMP documentation

[Nicolas Schier]

On Fri, 17 Oct 2025 10:12:09 +0800, Gang Yan wrote:
> 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.
> 
> 
> [...]

Applied to kbuild-next, thanks!

[1/1] kbuild: doc: improve KBUILD_BUILD_TIMESTAMP documentation
      (indentation of code example adjusted)
      commit: 5cbfb4da7e063cb82b1ab044465aeff4542a436d

Please note that commit hashes might change in case of issues with
kbuild-next branch.

Best regards,
-- 
Nicolas