Don't create Python bytecode when building the kernel

As reported by Andy, kernel-doc.py is creating a __pycache__ directory at build time.

Disable creation of __pycache__ for the libraries used by kernel-doc.py, when excecuted via the build system or via scripts/find-unused-docs.sh.

Reported-by Andy Shevchenko <[email protected]>

Closes https://lore.kernel.org/linux-doc/[email protected]/ open here

Signed-off-by Mauro Carvalho Chehab <[email protected]>

Tested-by Andy Shevchenko <[email protected]>

---
 drivers/gpu/drm/Makefile      | 2 +-
 drivers/gpu/drm/i915/Makefile | 2 +-
 include/drm/Makefile          | 2 +-
 scripts/Makefile.build        | 2 +-
 scripts/find-unused-docs.sh   | 2 +-
 5 files changed, 5 insertions(+), 5 deletions(-)

drivers/gpu/drm/Makefile +0 -0

index ed54a546bbe2..d21d0cd2c752 100644

Quoted 24 lines

As reported by Andy, kernel-doc.py is creating a __pycache__ directory at build time.

Disable creation of __pycache__ for the libraries used by kernel-doc.py, when excecuted via the build system or via scripts/find-unused-docs.sh.

Reported-by Andy Shevchenko <[email protected]>

Closes https://lore.kernel.org/linux-doc/[email protected]/ open here

Signed-off-by Mauro Carvalho Chehab <[email protected]>

Tested-by Andy Shevchenko <[email protected]>

---
 drivers/gpu/drm/Makefile      | 2 +-
 drivers/gpu/drm/i915/Makefile | 2 +-
 include/drm/Makefile          | 2 +-
 scripts/Makefile.build        | 2 +-
 scripts/find-unused-docs.sh   | 2 +-
 5 files changed, 5 insertions(+), 5 deletions(-)

drivers/gpu/drm/Makefile +0 -0

index ed54a546bbe2..d21d0cd2c752 100644

drivers/gpu/drm/Makefile always-$(CONFIG_DRM_HEADER_TEST) += \ · line 239

Quoted 5 lines

drivers/gpu/drm/Makefile +1 -1

@@ -236,7 +236,7 @@ always-$(CONFIG_DRM_HEADER_TEST) += \
 quiet_cmd_hdrtest = HDRTEST $(patsubst %.hdrtest,%.h,$@)
       cmd_hdrtest = \
 		$(CC) $(c_flags) -fsyntax-only -x c /dev/null -include $< -include $<; \
-		$(srctree)/scripts/kernel-doc -none $(if $(CONFIG_WERROR)$(CONFIG_DRM_WERROR),-Werror) $<; \
+		 PYTHONDONTWRITEBYTECODE=1 $(KERNELDOC) -none $(if $(CONFIG_WERROR)$(CONFIG_DRM_WERROR),-Werror) $<; \  

Did someone check if we could add

sys.dont_write_bytecode = True

to the script itself instead of cluttering PYTHONDONTWRITEBYTECODE everywhere [1]?

While the building system doesn't create any Python JIT bytecode, if one manually runs kernel-doc.py or get_abi.py, Python will, by default, create a bytecode and store it under scripts/lib/*.

This is normal, and not controlled by the Kernel itself. So, add *.pyc as an extension to be ignored.

Signed-off-by Mauro Carvalho Chehab <[email protected]>

As reported by Andy, the Kernel build system runs kernel-doc script for DRM, when W=1. Due to Python's normal behavior, its JIT compiler will create a bytecode and store it under scripts/lib/*/__pycache__. As one may be using O= and even having the sources on a read-only mount point, disable its creation during build time.

This is done by adding PYTHONDONTWRITEBYTECODE=1 on every place where the script is called within Kbuild and when called via another script.

This only solves half of the issue though, as one may be manually running the script by hand, without asking Python to not store any bytecode. This should be OK, but afterwards, git status will list the __pycache__ as not committed. To prevent that, add *.pyc to .gitignore.

This series contain 4 patches:

- patch 1 adjusts a variable that pass extra data to scripts/kerneldoc.py;
- patch 2moves scripts/kernel-doc location to the main makefile and exports it, as scripts/Makefile.build will need it;
- patch 3 disables __pycache__ generation and ensure that the entire Kbuild will use KERNELDOC var for the location of kernel-doc;
- patch 4 adds *.pyc at the list of object files to be ignored.

As reported by Andy, the Kernel build system runs kernel-doc script for DRM, when W=1. Due to Python's normal behavior, its JIT compiler will create a bytecode and store it under scripts/lib/*/__pycache__. As one may be using O= and even having the sources on a read-only mount point, disable its creation during build time.

This is done by adding PYTHONDONTWRITEBYTECODE=1 on every place where the script is called within Kbuild and when called via another script.

This only solves half of the issue though, as one may be manually running the script by hand, without asking Python to not store any bytecode. This should be OK, but afterwards, git status will list the __pycache__ as not committed. To prevent that, add *.pyc to .gitignore.

This series contain 4 patches:

- patch 1 adjusts a variable that pass extra data to scripts/kerneldoc.py;
- patch 2moves scripts/kernel-doc location to the main makefile and exports it, as scripts/Makefile.build will need it;
- patch 3 disables __pycache__ generation and ensure that the entire Kbuild will use KERNELDOC var for the location of kernel-doc;
- patch 4 adds *.pyc at the list of object files to be ignored.

This started well, until it becomes a scripts/lib/kdoc.
So, it makes the make O=... builds dirty *). Please make sure this doesn't leave "disgusting turd" )as said by Linus) in the clean tree.

*) it creates that __pycache__ disaster. And no, .gitignore IS NOT a solution.w

I tried before, but I admit, that I have missed something. It was a mess in that case. Now I probably can't repeat as I don't remember what was the environment and settings I had that time. I'm really glad to see it is working this way!

Bothering with might-become-incompatilbe-in-the-future python environment variables in kernel Makefiles looks over-engineering to me. Also, as Mauro says in 3/4, it is incomplete in that it does not cover the cases where those scripts are invoked outside of kernel build. And it will interfere with existing developers who want the benefit of bytecode caching.

I'm not precluding the possibility of incoherent bytecode cache; for example by using a shared kernel source tree among several developers, and only one of them (owner) has a write permission of it. In that case, said owner might update the tree without running relevant python scripts.

I don't know if python can notice outdated cache and disregard it.

In such a situation, setting PYTHONPYCACHEPREFIX as an environment variable should help, for sure, but only in such special cases.

Andy, what do you say if I ask reverts of 1/4, 2/4/, and 3/4?

Em Sat, 26 Apr 2025 11:39:05 +0900
Akira Yokosawa <[email protected]> escreveu:

Quoted 12 lines

Bothering with might-become-incompatilbe-in-the-future python environment variables in kernel Makefiles looks over-engineering to me. Also, as Mauro says in 3/4, it is incomplete in that it does not cover the cases where those scripts are invoked outside of kernel build. And it will interfere with existing developers who want the benefit of bytecode caching.

I'm not precluding the possibility of incoherent bytecode cache; for example by using a shared kernel source tree among several developers, and only one of them (owner) has a write permission of it. In that case, said owner might update the tree without running relevant python scripts.

Quoted 6 lines

I don't know if python can notice outdated cache and disregard it.

In such a situation, setting PYTHONPYCACHEPREFIX as an environment variable should help, for sure, but only in such special cases.

Andy, what do you say if I ask reverts of 1/4, 2/4/, and 3/4?

Patches 1 and 2 are, IMO, needed anyway, as they fix a problem:
KERNELDOC environment is not used consistently.

Now, patch 3 is the one that may require more thinking.

I agree with Andy that, when O=<dir> is used, nothing shall be written to source dir.

There are a couple of reasons for that:

1. source dir may be read only;
2. one may want to do cross compilation and use multiple output directories, one for each version;
3. the source dir could be mapped via NFS to multiple machines with different architectures.

For (3), it could mean that multiple machines may have different Python versions, so, sharing the Python bytecode from source dir doesn't sound a good idea. Also, I'm not sure if the pyc from different archs would be identical.

With that, there are two options:

a. disable cache;
b. set PYTHONCACHEPREFIX.

We're currently doing (a). I guess everybody agrees that this is is not ideal.

So, ideally, we should move to (b). For Spinx, the easiest solution is just to place it under Documentation/output, but this is not generic enough: ideally, we should revert patch 3 and set PYTHONCACHEPREFIX when O is used. Eventually, we can apply my patch for Documentation/output, while we craft such logic.