Re: [PATCH] doc tools: better handle KBUILD_VERBOSE

[Jacob Keller <jacob.e.keller@intel.com>]

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