[PATCH] docs: Makefile: Inherit PYTHONPYCACHEPREFIX setting as env variable

[PATCH] docs: Makefile: Inherit PYTHONPYCACHEPREFIX setting as env variable

[Akira Yokosawa]

Commit 6c2f0b28d76e ("docs: Makefile: store __pycache__ at the output
directory") assigns a new path to PYTHONPYCACHEPREFIX for building
kernel documentation.

However, it is not necessarily optimal for everyone.

If you find PYTHONPYCACHEPREFIX is already set, it strongly suggests
that the developer has selected the setting as best suited for one's own
workflow.

Use "?=" in the assignment to PYTHONPYCACHEPREFIX so that the path of
$(abspath $(BUILDDIR)/__pycache__) works only as a safeguard.

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Cc: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Mauro,

I left other Makefiles commit 5c5c32d7abd9 ("scripts/kernel-doc.py:
don't create *.pyc files") has touched, as I'm not sure which path to
assign in them.

Additional Notes:

Python's default behavior, which is safe in cases where the source tree
is never shared heterogeneously, can be restored by defining it empty
by saying:

    export PYTHONPYCACHEPREFIX=

As the path in the env var can have white spaces, a quote pair is added
to make it a single token.

Thanks,
Akira
--
 Documentation/Makefile | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 59e95ebae786..d30d66ddf1ad 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -82,9 +82,11 @@ loop_cmd = $(echo-cmd) $(cmd_$(1)) || exit;
 # $5 reST source folder relative to $(src),
 #    e.g. "userspace-api/media" for the linux-tv book-set at ./Documentation/userspace-api/media
 
+PYTHONPYCACHEPREFIX ?= $(abspath $(BUILDDIR)/__pycache__)
+
 quiet_cmd_sphinx = SPHINX  $@ --> file://$(abspath $(BUILDDIR)/$3/$4)
       cmd_sphinx = $(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/userspace-api/media $2 && \
-	PYTHONPYCACHEPREFIX=$(abspath $(BUILDDIR)/__pycache__) \
+	PYTHONPYCACHEPREFIX="$(PYTHONPYCACHEPREFIX)" \
 	BUILDDIR=$(abspath $(BUILDDIR)) SPHINX_CONF=$(abspath $(src)/$5/$(SPHINX_CONF)) \
 	$(PYTHON3) $(srctree)/scripts/jobserver-exec \
 	$(CONFIG_SHELL) $(srctree)/Documentation/sphinx/parallel-wrapper.sh \

base-commit: c0fe189b590c754f69e0cb87c5b5674cad535cf6
-- 
2.43.0

Re: [PATCH] docs: Makefile: Inherit PYTHONPYCACHEPREFIX setting as env variable

[Jonathan Corbet]

Akira Yokosawa <akiyks@gmail.com> writes:

> Commit 6c2f0b28d76e ("docs: Makefile: store __pycache__ at the output
> directory") assigns a new path to PYTHONPYCACHEPREFIX for building
> kernel documentation.
>
> However, it is not necessarily optimal for everyone.
>
> If you find PYTHONPYCACHEPREFIX is already set, it strongly suggests
> that the developer has selected the setting as best suited for one's own
> workflow.
>
> Use "?=" in the assignment to PYTHONPYCACHEPREFIX so that the path of
> $(abspath $(BUILDDIR)/__pycache__) works only as a safeguard.
>
> Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
> Cc: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

Applied, thanks.

jon

Re: [PATCH] docs: Makefile: Inherit PYTHONPYCACHEPREFIX setting as env variable

[Mauro Carvalho Chehab]

Em Thu, 1 May 2025 17:21:07 +0900
Akira Yokosawa <akiyks@gmail.com> escreveu:

> Commit 6c2f0b28d76e ("docs: Makefile: store __pycache__ at the output
> directory") assigns a new path to PYTHONPYCACHEPREFIX for building
> kernel documentation.
> 
> However, it is not necessarily optimal for everyone.
> 
> If you find PYTHONPYCACHEPREFIX is already set, it strongly suggests
> that the developer has selected the setting as best suited for one's own
> workflow.
> 
> Use "?=" in the assignment to PYTHONPYCACHEPREFIX so that the path of
> $(abspath $(BUILDDIR)/__pycache__) works only as a safeguard.
> 
> Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
> Cc: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

Sorry for not answering it earlier... I took a quick vacation last week
to rest after a long trip abroad.

It is a little late for that, as Jon already applied, but the change
looks good to me:

Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

> ---
> Mauro,
> 
> I left other Makefiles commit 5c5c32d7abd9 ("scripts/kernel-doc.py:
> don't create *.pyc files") has touched, as I'm not sure which path to
> assign in them.

Well, O= sets some environment var, but granted it requires some time
to understand kernel Makefiles and see where exactly it stores the
dest directory. I won't have any time this week or the next one to
check it, but I can try to write a patch for that later on, if nobody
does that before.

> Additional Notes:
> 
> Python's default behavior, which is safe in cases where the source tree
> is never shared heterogeneously, can be restored by defining it empty
> by saying:
> 
>     export PYTHONPYCACHEPREFIX=
> 
> As the path in the env var can have white spaces, a quote pair is added
> to make it a single token.

Perhaps it makes sense to place it somewhere at the documentation.

Regards,
Mauro

> 
> Thanks,
> Akira
> --
>  Documentation/Makefile | 4 +++-
>  1 file changed, 3 insertions(+), 1 deletion(-)
> 
> diff --git a/Documentation/Makefile b/Documentation/Makefile
> index 59e95ebae786..d30d66ddf1ad 100644
> --- a/Documentation/Makefile
> +++ b/Documentation/Makefile
> @@ -82,9 +82,11 @@ loop_cmd = $(echo-cmd) $(cmd_$(1)) || exit;
>  # $5 reST source folder relative to $(src),
>  #    e.g. "userspace-api/media" for the linux-tv book-set at ./Documentation/userspace-api/media
>  
> +PYTHONPYCACHEPREFIX ?= $(abspath $(BUILDDIR)/__pycache__)
> +
>  quiet_cmd_sphinx = SPHINX  $@ --> file://$(abspath $(BUILDDIR)/$3/$4)
>        cmd_sphinx = $(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/userspace-api/media $2 && \
> -	PYTHONPYCACHEPREFIX=$(abspath $(BUILDDIR)/__pycache__) \
> +	PYTHONPYCACHEPREFIX="$(PYTHONPYCACHEPREFIX)" \
>  	BUILDDIR=$(abspath $(BUILDDIR)) SPHINX_CONF=$(abspath $(src)/$5/$(SPHINX_CONF)) \
>  	$(PYTHON3) $(srctree)/scripts/jobserver-exec \
>  	$(CONFIG_SHELL) $(srctree)/Documentation/sphinx/parallel-wrapper.sh \
> 
> base-commit: c0fe189b590c754f69e0cb87c5b5674cad535cf6