[PATCH] Documentation: kbuild: Update the debug information notes in reproducible-builds.rst

[PATCH] Documentation: kbuild: Update the debug information notes in reproducible-builds.rst

[Nathan Chancellor]

The debug information part of the "Absolute filenames" section in the
reproducible builds document only mentions providing
'-fdebug-prefix-map' to KCFLAGS but it needs to be provided to KAFLAGS
as well since debug information has been generated for assembly files
for a long time.

Additionally, mention that the build directory may also appear as an
absolute path in the debug information (via DW_AT_comp_dir), so it needs
to be overridden via '-fdebug-prefix-map' as well.

Reported-by: Alexander Coffin <alex@cyberialabs.net>
Closes: https://lore.kernel.org/b8dfe7035d19fd611b9be55ee3145fdb@purelymail.com/
Signed-off-by: Nathan Chancellor <nathan@kernel.org>
---
 Documentation/kbuild/reproducible-builds.rst | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/Documentation/kbuild/reproducible-builds.rst b/Documentation/kbuild/reproducible-builds.rst
index 96d208e578cd..bc1eb82211df 100644
--- a/Documentation/kbuild/reproducible-builds.rst
+++ b/Documentation/kbuild/reproducible-builds.rst
@@ -50,8 +50,10 @@ Absolute filenames
 ------------------
 
 When the kernel is built out-of-tree, debug information may include
-absolute filenames for the source files.  This must be overridden by
-including the ``-fdebug-prefix-map`` option in the `KCFLAGS`_ variable.
+absolute filenames for the source files and build directory.  These must
+be overridden by including a ``-fdebug-prefix-map`` option for each in
+the `KCFLAGS`_ and `KAFLAGS`_ variables to cover both ``.c`` and ``.S``
+files.
 
 Depending on the compiler used, the ``__FILE__`` macro may also expand
 to an absolute filename in an out-of-tree build.  Kbuild automatically
@@ -135,6 +137,7 @@ See ``scripts/setlocalversion`` for details.
 .. _KBUILD_BUILD_TIMESTAMP: kbuild.html#kbuild-build-timestamp
 .. _KBUILD_BUILD_USER and KBUILD_BUILD_HOST: kbuild.html#kbuild-build-user-kbuild-build-host
 .. _KCFLAGS: kbuild.html#kcflags
+.. _KAFLAGS: kbuild.html#kaflags
 .. _prefix-map options: https://reproducible-builds.org/docs/build-path/
 .. _Reproducible Builds project: https://reproducible-builds.org/
 .. _SOURCE_DATE_EPOCH: https://reproducible-builds.org/docs/source-date-epoch/

---
base-commit: 1f318b96cc84d7c2ab792fcc0bfd42a7ca890681
change-id: 20260313-kbuild-docs-repro-builds-fdebug-prefix-map-updates-c4c3c4d69550

Best regards,
--  
Nathan Chancellor <nathan@kernel.org>

Re: [PATCH] Documentation: kbuild: Update the debug information notes in reproducible-builds.rst

[Alexander Coffin]

Hi Nathan,

I finally got around to reviewing the reproducible builds again and I'm 
pretty sure it is supposed to be `-ffile-prefix-map` (not just 
`-fdebug-prefix-map`) with KCPPFLAGS to also handle macros, but I could 
be mistaken. I can try to build the kernel reproducibly again, but it 
has been a while since I did this (sorry).

- Alex

Re: [PATCH] Documentation: kbuild: Update the debug information notes in reproducible-builds.rst

[Nathan Chancellor]

Hi Alex,

On Sat, Mar 14, 2026 at 09:44:31PM -0700, Alexander Coffin wrote:
> I finally got around to reviewing the reproducible builds again and I'm
> pretty sure it is supposed to be `-ffile-prefix-map` (not just
> `-fdebug-prefix-map`) with KCPPFLAGS to also handle macros, but I could be
> mistaken. I can try to build the kernel reproducibly again, but it has been
> a while since I did this (sorry).

Thanks a lot for taking a look! '-ffile-prefix-map' is the same as
'-fdebug-prefix-map' + '-fmacro-prefix-map' and the kernel already sets
the latter in Makefile (this documentation mentions that in the next
paragraph), so it is only necessary for someone to set the debug
variant.

We tried to add '-ffile-prefix-map' instead of just '-fmacro-prefix-map'
but it breaks quite a few things for the average developer so it had to
be reverted.

Cheers,
Nathan