doc tools: better handle KBUILD_VERBOSE

[PATCH] doc tools: better handle KBUILD_VERBOSE

Posted by Mauro Carvalho Chehab 6 days, 9 hours ago

As reported by Jacob, there are troubles when KBUILD_VERBOSE is
set at the environment.

Fix it on both kernel-doc and sphinx-build-wrapper.

Reported-by: Jacob Keller <jacob.e.keller@intel.com>
Closes: https://lore.kernel.org/linux-doc/9367d899-53af-4d9c-9320-22fc4dbadca5@intel.com/
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 tools/docs/sphinx-build-wrapper     | 7 ++++++-
 tools/lib/python/kdoc/kdoc_files.py | 7 ++++++-
 2 files changed, 12 insertions(+), 2 deletions(-)

diff --git a/tools/docs/sphinx-build-wrapper b/tools/docs/sphinx-build-wrapper
index 2c63d28f639d..1bb962202784 100755
--- a/tools/docs/sphinx-build-wrapper
+++ b/tools/docs/sphinx-build-wrapper
@@ -238,7 +238,12 @@ class SphinxBuilder:
             self.latexopts = os.environ.get("LATEXOPTS", "")
 
         if not verbose:
-            verbose = bool(os.environ.get("KBUILD_VERBOSE", "") != "")
+            try:
+                verbose = bool(int(os.environ.get("KBUILD_VERBOSE", 0)))
+            except ValueError:
+                # Handles an eventual case where verbosity is not a number
+                # like KBUILD_VERBOSE=""
+                verbose = False
 
         if verbose is not None:
             self.verbose = verbose
diff --git a/tools/lib/python/kdoc/kdoc_files.py b/tools/lib/python/kdoc/kdoc_files.py
index 2428cfc4e843..ed82b6e6ab25 100644
--- a/tools/lib/python/kdoc/kdoc_files.py
+++ b/tools/lib/python/kdoc/kdoc_files.py
@@ -238,7 +238,12 @@ class KernelFiles():
         """
 
         if not verbose:
-            verbose = bool(os.environ.get("KBUILD_VERBOSE", 0))
+            try:
+                verbose = bool(int(os.environ.get("KBUILD_VERBOSE", 0)))
+            except ValueError:
+                # Handles an eventual case where verbosity is not a number
+                # like KBUILD_VERBOSE=""
+                verbose = False
 
         if out_style is None:
             out_style = OutputFormat()
-- 
2.53.0

Re: [PATCH] doc tools: better handle KBUILD_VERBOSE

Posted by Jonathan Corbet 2 days, 23 hours ago

Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:

> As reported by Jacob, there are troubles when KBUILD_VERBOSE is
> set at the environment.
>
> Fix it on both kernel-doc and sphinx-build-wrapper.
>
> Reported-by: Jacob Keller <jacob.e.keller@intel.com>
> Closes: https://lore.kernel.org/linux-doc/9367d899-53af-4d9c-9320-22fc4dbadca5@intel.com/
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
>  tools/docs/sphinx-build-wrapper     | 7 ++++++-
>  tools/lib/python/kdoc/kdoc_files.py | 7 ++++++-
>  2 files changed, 12 insertions(+), 2 deletions(-)

Applied, thanks.

jon

Re: [PATCH] doc tools: better handle KBUILD_VERBOSE

Posted by Jacob Keller 5 days, 21 hours ago

On 3/26/2026 10:57 PM, Mauro Carvalho Chehab wrote:
> As reported by Jacob, there are troubles when KBUILD_VERBOSE is
> set at the environment.
> 
> Fix it on both kernel-doc and sphinx-build-wrapper.
> 
> Reported-by: Jacob Keller <jacob.e.keller@intel.com>
> Closes: https://lore.kernel.org/linux-doc/9367d899-53af-4d9c-9320-22fc4dbadca5@intel.com/
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---

I loaded this on my system and tested the build works as expected both
with V=0 and when I export KBUILD_VERBOSE manually.

Thanks for fixing this quickly!

Tested-by: Jacob Keller <jacob.e.keller@intel.com>

>  tools/docs/sphinx-build-wrapper     | 7 ++++++-
>  tools/lib/python/kdoc/kdoc_files.py | 7 ++++++-
>  2 files changed, 12 insertions(+), 2 deletions(-)
> 
> diff --git a/tools/docs/sphinx-build-wrapper b/tools/docs/sphinx-build-wrapper
> index 2c63d28f639d..1bb962202784 100755
> --- a/tools/docs/sphinx-build-wrapper
> +++ b/tools/docs/sphinx-build-wrapper
> @@ -238,7 +238,12 @@ class SphinxBuilder:
>              self.latexopts = os.environ.get("LATEXOPTS", "")
>  
>          if not verbose:
> -            verbose = bool(os.environ.get("KBUILD_VERBOSE", "") != "")
> +            try:
> +                verbose = bool(int(os.environ.get("KBUILD_VERBOSE", 0)))
> +            except ValueError:
> +                # Handles an eventual case where verbosity is not a number
> +                # like KBUILD_VERBOSE=""

Strictly speaking I think os.environ.get() will handle the case of an
empty KBUILD_VERBOSE by converting to the default value (in this case 0).

The intent of the comment and code is pretty clear though, so I don't
know that deserves a re-roll.

Thanks,
Jake

Re: [PATCH] doc tools: better handle KBUILD_VERBOSE

Posted by Mauro Carvalho Chehab 5 days, 15 hours ago

On Fri, 27 Mar 2026 11:35:39 -0700
Jacob Keller <jacob.e.keller@intel.com> wrote:

> On 3/26/2026 10:57 PM, Mauro Carvalho Chehab wrote:
> > As reported by Jacob, there are troubles when KBUILD_VERBOSE is
> > set at the environment.
> > 
> > Fix it on both kernel-doc and sphinx-build-wrapper.
> > 
> > Reported-by: Jacob Keller <jacob.e.keller@intel.com>
> > Closes: https://lore.kernel.org/linux-doc/9367d899-53af-4d9c-9320-22fc4dbadca5@intel.com/
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> > ---  
> 
> I loaded this on my system and tested the build works as expected both
> with V=0 and when I export KBUILD_VERBOSE manually.
> 
> Thanks for fixing this quickly!
> 
> Tested-by: Jacob Keller <jacob.e.keller@intel.com>
> 
> >  tools/docs/sphinx-build-wrapper     | 7 ++++++-
> >  tools/lib/python/kdoc/kdoc_files.py | 7 ++++++-
> >  2 files changed, 12 insertions(+), 2 deletions(-)
> > 
> > diff --git a/tools/docs/sphinx-build-wrapper b/tools/docs/sphinx-build-wrapper
> > index 2c63d28f639d..1bb962202784 100755
> > --- a/tools/docs/sphinx-build-wrapper
> > +++ b/tools/docs/sphinx-build-wrapper
> > @@ -238,7 +238,12 @@ class SphinxBuilder:
> >              self.latexopts = os.environ.get("LATEXOPTS", "")
> >  
> >          if not verbose:
> > -            verbose = bool(os.environ.get("KBUILD_VERBOSE", "") != "")
> > +            try:
> > +                verbose = bool(int(os.environ.get("KBUILD_VERBOSE", 0)))
> > +            except ValueError:
> > +                # Handles an eventual case where verbosity is not a number
> > +                # like KBUILD_VERBOSE=""  
> 
> Strictly speaking I think os.environ.get() will handle the case of an
> empty KBUILD_VERBOSE by converting to the default value (in this case 0).

It won't. See:

	$ FOO="" python3
	Python 3.14.3 (main, Feb  4 2026, 00:00:00) [GCC 15.2.1 20260123 (Red Hat 15.2.1-7)] on linux
	Type "help", "copyright", "credits" or "license" for more information.
	>>> import os
	>>> os.environ.get("FOO", 0)
	''

	$ FOO="0" python3 
	Python 3.14.3 (main, Feb  4 2026, 00:00:00) [GCC 15.2.1 20260123 (Red Hat 15.2.1-7)] on linux
	Type "help", "copyright", "credits" or "license" for more information.
	>>> import os
	>>> os.environ.get("FOO", 0)
	... 
	'0'

	$ unset FOO; python3 
	Python 3.14.3 (main, Feb  4 2026, 00:00:00) [GCC 15.2.1 20260123 (Red Hat 15.2.1-7)] on linux
	Type "help", "copyright", "credits" or "license" for more information.
	>>> import os
	>>> os.environ.get("FOO", 0)
	... 
	0

it will only get an integer 0 if the env var (at the above example, FOO)
is not on env.

That's basically why we need to first convert it to integer than to
bool.

> The intent of the comment and code is pretty clear though, so I don't
> know that deserves a re-roll.

I opted to add a comment there because having two conversions,
first to int then to bool is not that obvious ;-)

Thanks,
Mauro

Re: [PATCH] doc tools: better handle KBUILD_VERBOSE

Posted by Jacob Keller 2 days, 23 hours ago

On 3/27/2026 5:09 PM, Mauro Carvalho Chehab wrote:
> On Fri, 27 Mar 2026 11:35:39 -0700
> Jacob Keller <jacob.e.keller@intel.com> wrote:
> 
>> On 3/26/2026 10:57 PM, Mauro Carvalho Chehab wrote:
>>> As reported by Jacob, there are troubles when KBUILD_VERBOSE is
>>> set at the environment.
>>>
>>> Fix it on both kernel-doc and sphinx-build-wrapper.
>>>
>>> Reported-by: Jacob Keller <jacob.e.keller@intel.com>
>>> Closes: https://lore.kernel.org/linux-doc/9367d899-53af-4d9c-9320-22fc4dbadca5@intel.com/
>>> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
>>> ---  
>>
>> I loaded this on my system and tested the build works as expected both
>> with V=0 and when I export KBUILD_VERBOSE manually.
>>
>> Thanks for fixing this quickly!
>>
>> Tested-by: Jacob Keller <jacob.e.keller@intel.com>
>>
>>>  tools/docs/sphinx-build-wrapper     | 7 ++++++-
>>>  tools/lib/python/kdoc/kdoc_files.py | 7 ++++++-
>>>  2 files changed, 12 insertions(+), 2 deletions(-)
>>>
>>> diff --git a/tools/docs/sphinx-build-wrapper b/tools/docs/sphinx-build-wrapper
>>> index 2c63d28f639d..1bb962202784 100755
>>> --- a/tools/docs/sphinx-build-wrapper
>>> +++ b/tools/docs/sphinx-build-wrapper
>>> @@ -238,7 +238,12 @@ class SphinxBuilder:
>>>              self.latexopts = os.environ.get("LATEXOPTS", "")
>>>  
>>>          if not verbose:
>>> -            verbose = bool(os.environ.get("KBUILD_VERBOSE", "") != "")
>>> +            try:
>>> +                verbose = bool(int(os.environ.get("KBUILD_VERBOSE", 0)))
>>> +            except ValueError:
>>> +                # Handles an eventual case where verbosity is not a number
>>> +                # like KBUILD_VERBOSE=""  
>>
>> Strictly speaking I think os.environ.get() will handle the case of an
>> empty KBUILD_VERBOSE by converting to the default value (in this case 0).
> 
> It won't. See:
> 
> 	$ FOO="" python3
> 	Python 3.14.3 (main, Feb  4 2026, 00:00:00) [GCC 15.2.1 20260123 (Red Hat 15.2.1-7)] on linux
> 	Type "help", "copyright", "credits" or "license" for more information.
> 	>>> import os
> 	>>> os.environ.get("FOO", 0)
> 	''
> 
> 	$ FOO="0" python3 
> 	Python 3.14.3 (main, Feb  4 2026, 00:00:00) [GCC 15.2.1 20260123 (Red Hat 15.2.1-7)] on linux
> 	Type "help", "copyright", "credits" or "license" for more information.
> 	>>> import os
> 	>>> os.environ.get("FOO", 0)
> 	... 
> 	'0'
> 
> 	$ unset FOO; python3 
> 	Python 3.14.3 (main, Feb  4 2026, 00:00:00) [GCC 15.2.1 20260123 (Red Hat 15.2.1-7)] on linux
> 	Type "help", "copyright", "credits" or "license" for more information.
> 	>>> import os
> 	>>> os.environ.get("FOO", 0)
> 	... 
> 	0
> 
> it will only get an integer 0 if the env var (at the above example, FOO)
> is not on env.

We always export KBUILD_VERBOSE regardless of its content, so we always
have os.environ.get("KBUILD_VERBOSE", 0) returning an empty string..

but the old bool() conversion would return false as expected. I.e. prior
to the change '' was handled as false as expected. but with int() then
we *do* get a ValueError now instead.

Ok.

> 
>> The intent of the comment and code is pretty clear though, so I don't
>> know that deserves a re-roll.
> 
> I opted to add a comment there because having two conversions,
> first to int then to bool is not that obvious ;-)
> 

Yes. I was misunderstanding the intent of the comment, because I was
thinking that KBUILD_VERBOSE was unset, i.e. if you assign
KBUILD_VERBOSE= it would result in an unset value, but set and empty is
distinct from unset.

Prior to the int() conversion the bool() conversion did implicitly
handle the '' to false conversion, but now we'll get an exception first.

Thanks, and apologies for my confusion :D

> Thanks,
> Mauro