[PATCH] Documentation/kbuild: fix empty string KBUILD_BUILD_TIMESTAMP

[PATCH] Documentation/kbuild: fix empty string KBUILD_BUILD_TIMESTAMP

[Daniel Gomez]

From: Daniel Gomez <da.gomez@samsung.com>

The ccache example in llvm.rst uses KBUILD_BUILD_TIMESTAMP='' but the
text says "should be set to a deterministic value". An empty string is
not deterministic because init/Makefile uses $(or) which treats empty
as false and falls through to $(shell LC_ALL=C date), embedding the
current time:

	cat /tmp/test-or.mk
	build-timestamp-auto = fallback
	build-timestamp = $(or $(KBUILD_BUILD_TIMESTAMP),$(build-timestamp-auto))
	all:
	        @echo "[$(build-timestamp)]"

	make --file=/tmp/test-or.mk
	[fallback]

	KBUILD_BUILD_TIMESTAMP='' make --file=/tmp/test-or.mk
	[fallback]

	KBUILD_BUILD_TIMESTAMP="Sun Aug 25 20:57:08 UTC 1991" \
		make --file=/tmp/test-or.mk
	[Sun Aug 25 20:57:08 UTC 1991]

The same applies to a real kernel build:

	make O=../build LLVM=1 CC="ccache clang" tinyconfig
	make O=../build LLVM=1 CC="ccache clang" \
		KBUILD_BUILD_TIMESTAMP='' --jobs=$(nproc)
	cat ../build/include/generated/utsversion.h
	#define UTS_VERSION "#2 Wed Mar  4 12:13:43 CET 2026"

Replace the empty string with an actual date, matching the pattern
in kbuild.rst and reproducible-builds.rst. Use the first public Linux
announcement as example date.

	make O=../build LLVM=1 CC="ccache clang" tinyconfig
	make O=../build LLVM=1 CC="ccache clang" \
		KBUILD_BUILD_TIMESTAMP="Sun Aug 25 20:57:08 UTC 1991" \
		--jobs=$(nproc)
	cat ../build/include/generated/utsversion.h
	#define UTS_VERSION "#4 Sun Aug 25 20:57:08 UTC 1991"

Signed-off-by: Daniel Gomez <da.gomez@samsung.com>
---
Do not use an empty KBUILD_BUILD_TIMESTAMP Makefile variable.
---
 Documentation/kbuild/llvm.rst                    | 2 +-
 Documentation/translations/zh_CN/kbuild/llvm.rst | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/kbuild/llvm.rst b/Documentation/kbuild/llvm.rst
index bc8a283bc44b..ef46533d785f 100644
--- a/Documentation/kbuild/llvm.rst
+++ b/Documentation/kbuild/llvm.rst
@@ -128,7 +128,7 @@ Ccache
 KBUILD_BUILD_TIMESTAMP_ should be set to a deterministic value between builds
 in order to avoid 100% cache misses, see Reproducible_builds_ for more info)::
 
-	KBUILD_BUILD_TIMESTAMP='' make LLVM=1 CC="ccache clang"
+	KBUILD_BUILD_TIMESTAMP="Sun Aug 25 20:57:08 UTC 1991" make LLVM=1 CC="ccache clang"
 
 .. _KBUILD_BUILD_TIMESTAMP: kbuild.html#kbuild-build-timestamp
 .. _Reproducible_builds: reproducible-builds.html#timestamps
diff --git a/Documentation/translations/zh_CN/kbuild/llvm.rst b/Documentation/translations/zh_CN/kbuild/llvm.rst
index f87e0181d8e7..c68fd395f64c 100644
--- a/Documentation/translations/zh_CN/kbuild/llvm.rst
+++ b/Documentation/translations/zh_CN/kbuild/llvm.rst
@@ -116,7 +116,7 @@ Ccache
 KBUILD_BUILD_TIMESTAMP_ 应设置为同一确定值，以避免 100% 的缓存未命中，
 详见 Reproducible_builds_ 获取更多信息）::
 
-	KBUILD_BUILD_TIMESTAMP='' make LLVM=1 CC="ccache clang"
+	KBUILD_BUILD_TIMESTAMP="Sun Aug 25 20:57:08 UTC 1991" make LLVM=1 CC="ccache clang"
 
 .. _KBUILD_BUILD_TIMESTAMP: kbuild.html#kbuild-build-timestamp
 .. _Reproducible_builds: reproducible-builds.html#timestamps

---
base-commit: 11439c4635edd669ae435eec308f4ab8a0804808
change-id: 20260310-fix-llvm-docs-1f91c1ec7608

Best regards,
--  
Daniel Gomez <da.gomez@samsung.com>

Re: [PATCH] Documentation/kbuild: fix empty string KBUILD_BUILD_TIMESTAMP

[Nathan Chancellor]

On Tue, Mar 10, 2026 at 12:48:43PM +0100, Daniel Gomez wrote:
> From: Daniel Gomez <da.gomez@samsung.com>
> 
> The ccache example in llvm.rst uses KBUILD_BUILD_TIMESTAMP='' but the
> text says "should be set to a deterministic value". An empty string is
> not deterministic because init/Makefile uses $(or) which treats empty
> as false and falls through to $(shell LC_ALL=C date), embedding the
> current time:
> 
> 	cat /tmp/test-or.mk
> 	build-timestamp-auto = fallback
> 	build-timestamp = $(or $(KBUILD_BUILD_TIMESTAMP),$(build-timestamp-auto))
> 	all:
> 	        @echo "[$(build-timestamp)]"
> 
> 	make --file=/tmp/test-or.mk
> 	[fallback]
> 
> 	KBUILD_BUILD_TIMESTAMP='' make --file=/tmp/test-or.mk
> 	[fallback]
> 
> 	KBUILD_BUILD_TIMESTAMP="Sun Aug 25 20:57:08 UTC 1991" \
> 		make --file=/tmp/test-or.mk
> 	[Sun Aug 25 20:57:08 UTC 1991]
> 
> The same applies to a real kernel build:
> 
> 	make O=../build LLVM=1 CC="ccache clang" tinyconfig
> 	make O=../build LLVM=1 CC="ccache clang" \
> 		KBUILD_BUILD_TIMESTAMP='' --jobs=$(nproc)
> 	cat ../build/include/generated/utsversion.h
> 	#define UTS_VERSION "#2 Wed Mar  4 12:13:43 CET 2026"
> 
> Replace the empty string with an actual date, matching the pattern
> in kbuild.rst and reproducible-builds.rst. Use the first public Linux
> announcement as example date.
> 
> 	make O=../build LLVM=1 CC="ccache clang" tinyconfig
> 	make O=../build LLVM=1 CC="ccache clang" \
> 		KBUILD_BUILD_TIMESTAMP="Sun Aug 25 20:57:08 UTC 1991" \
> 		--jobs=$(nproc)
> 	cat ../build/include/generated/utsversion.h
> 	#define UTS_VERSION "#4 Sun Aug 25 20:57:08 UTC 1991"
> 
> Signed-off-by: Daniel Gomez <da.gomez@samsung.com>
> ---
> Do not use an empty KBUILD_BUILD_TIMESTAMP Makefile variable.
> ---
>  Documentation/kbuild/llvm.rst                    | 2 +-
>  Documentation/translations/zh_CN/kbuild/llvm.rst | 2 +-
>  2 files changed, 2 insertions(+), 2 deletions(-)
> 
> diff --git a/Documentation/kbuild/llvm.rst b/Documentation/kbuild/llvm.rst
> index bc8a283bc44b..ef46533d785f 100644
> --- a/Documentation/kbuild/llvm.rst
> +++ b/Documentation/kbuild/llvm.rst
> @@ -128,7 +128,7 @@ Ccache
>  KBUILD_BUILD_TIMESTAMP_ should be set to a deterministic value between builds
>  in order to avoid 100% cache misses, see Reproducible_builds_ for more info)::

To be entirely honest, I don't think this is quite valid anymore, at
least not with fairly modern ccache versions.

  $ ccache --version | head -1
  ccache version 4.12.3

  $ ccache -C

  $ make -skj"$(nproc)" ARCH=arm64 CC="ccache clang" HOSTCC="ccache clang" LLVM=1 mrproper defconfig all

  $ ccache -z
  Statistics zeroed

  $ make -skj"$(nproc)" ARCH=arm64 CC="ccache clang" HOSTCC="ccache clang" LLVM=1 clean all

  $ ccache -s
  Cacheable calls:   10497 / 10554 (99.46%)
    Hits:            10496 / 10497 (99.99%)
      Direct:        10488 / 10496 (99.92%)
      Preprocessed:      8 / 10496 ( 0.08%)
    Misses:              1 / 10497 ( 0.01%)
  Uncacheable calls:    57 / 10554 ( 0.54%)
  Local storage:
    Cache size (GB):   1.2 / 100.0 ( 1.21%)
    Hits:            10496 / 10497 (99.99%)
    Misses:              1 / 10497 ( 0.01%)

I think we should just remove mention of KBUILD_BUILD_TIMESTAMP all together.

Ccache
------

``ccache`` can be used with ``clang`` to improve subsequent builds::

	make LLVM=1 CC="ccache clang"

> -	KBUILD_BUILD_TIMESTAMP='' make LLVM=1 CC="ccache clang"
> +	KBUILD_BUILD_TIMESTAMP="Sun Aug 25 20:57:08 UTC 1991" make LLVM=1 CC="ccache clang"
>  
>  .. _KBUILD_BUILD_TIMESTAMP: kbuild.html#kbuild-build-timestamp
>  .. _Reproducible_builds: reproducible-builds.html#timestamps
> diff --git a/Documentation/translations/zh_CN/kbuild/llvm.rst b/Documentation/translations/zh_CN/kbuild/llvm.rst
> index f87e0181d8e7..c68fd395f64c 100644
> --- a/Documentation/translations/zh_CN/kbuild/llvm.rst
> +++ b/Documentation/translations/zh_CN/kbuild/llvm.rst
> @@ -116,7 +116,7 @@ Ccache
>  KBUILD_BUILD_TIMESTAMP_ 应设置为同一确定值，以避免 100% 的缓存未命中，
>  详见 Reproducible_builds_ 获取更多信息）::
>  
> -	KBUILD_BUILD_TIMESTAMP='' make LLVM=1 CC="ccache clang"
> +	KBUILD_BUILD_TIMESTAMP="Sun Aug 25 20:57:08 UTC 1991" make LLVM=1 CC="ccache clang"
>  
>  .. _KBUILD_BUILD_TIMESTAMP: kbuild.html#kbuild-build-timestamp
>  .. _Reproducible_builds: reproducible-builds.html#timestamps
> 
> ---
> base-commit: 11439c4635edd669ae435eec308f4ab8a0804808
> change-id: 20260310-fix-llvm-docs-1f91c1ec7608
> 
> Best regards,
> --  
> Daniel Gomez <da.gomez@samsung.com>
>