[PATCHv2] kconfig: add some Kconfig env variables to make help

  Add a new section "Configuration environment variables" to
`make help` output in order to make it easier for people to
discover KCONFIG_WERROR, etc.

Signed-off-by: Sergey Senozhatsky <senozhatsky@chromium.org>
---
 scripts/kconfig/Makefile | 4 ++++
 1 file changed, 4 insertions(+)
  

On Thu, Feb 22, 2024 at 12:26 PM Sergey Senozhatsky
<senozhatsky@chromium.org> wrote:
>
> Add a new section "Configuration environment variables" to
> `make help` output in order to make it easier for people to
> discover KCONFIG_WERROR, etc.
>
> Signed-off-by: Sergey Senozhatsky <senozhatsky@chromium.org>
> ---
>  scripts/kconfig/Makefile | 4 ++++
>  1 file changed, 4 insertions(+)
>
> diff --git a/scripts/kconfig/Makefile b/scripts/kconfig/Makefile
> index ea1bf3b3dbde..0044d49e149c 100644
> --- a/scripts/kconfig/Makefile
> +++ b/scripts/kconfig/Makefile
> @@ -158,6 +158,10 @@ help:
>                 if help=$$(grep -m1 '^# Help: ' $(f)); then \
>                         printf '  %-25s - %s\n' '$(notdir $(f))' "$${help#*: }"; \
>                 fi;)
> +       @echo  ''
> +       @echo  'Configuration environment variables:'
> +       @echo  '  KCONFIG_WERROR                 - Turn some Kconfig warnings into error conditions'
> +       @echo  '  KCONFIG_WARN_UNKNOWN_SYMBOLS   - Make Kconfig warn about all unrecognized config symbols'
>
>  # ===========================================================================
>  # object files used by all kconfig flavours
> --
> 2.44.0.rc0.258.g7320e95886-goog
>
>


Why only two, while Kconfig supports more env variables?
  

On (24/02/22 13:57), Masahiro Yamada wrote:
> On Thu, Feb 22, 2024 at 12:26 PM Sergey Senozhatsky
> <senozhatsky@chromium.org> wrote:
> >
> > Add a new section "Configuration environment variables" to
> > `make help` output in order to make it easier for people to
> > discover KCONFIG_WERROR, etc.
> >
> > Signed-off-by: Sergey Senozhatsky <senozhatsky@chromium.org>
> > ---
> >  scripts/kconfig/Makefile | 4 ++++
> >  1 file changed, 4 insertions(+)
> >
> > diff --git a/scripts/kconfig/Makefile b/scripts/kconfig/Makefile
> > index ea1bf3b3dbde..0044d49e149c 100644
> > --- a/scripts/kconfig/Makefile
> > +++ b/scripts/kconfig/Makefile
> > @@ -158,6 +158,10 @@ help:
> >                 if help=$$(grep -m1 '^# Help: ' $(f)); then \
> >                         printf '  %-25s - %s\n' '$(notdir $(f))' "$${help#*: }"; \
> >                 fi;)
> > +       @echo  ''
> > +       @echo  'Configuration environment variables:'
> > +       @echo  '  KCONFIG_WERROR                 - Turn some Kconfig warnings into error conditions'
> > +       @echo  '  KCONFIG_WARN_UNKNOWN_SYMBOLS   - Make Kconfig warn about all unrecognized config symbols'
> >
> >  # ===========================================================================
> >  # object files used by all kconfig flavours
> > --
> > 2.44.0.rc0.258.g7320e95886-goog
> >
> >
>
> Why only two, while Kconfig supports more env variables?

Right.  I wanted to add only those that we use (and familiar with) for
starters.  I'm not familiar with things like KCONFIG_PROBABILITY, for
instance, and not sure how to document it (its Documentation/kbuild/kconfig.rst
description is pretty lengthy).
  

On (24/02/22 14:16), Sergey Senozhatsky wrote:
> On (24/02/22 13:57), Masahiro Yamada wrote:
> > On Thu, Feb 22, 2024 at 12:26 PM Sergey Senozhatsky
> > <senozhatsky@chromium.org> wrote:
> > >
> > > Add a new section "Configuration environment variables" to
> > > `make help` output in order to make it easier for people to
> > > discover KCONFIG_WERROR, etc.
> > >
> > > Signed-off-by: Sergey Senozhatsky <senozhatsky@chromium.org>
> > > ---
> > >  scripts/kconfig/Makefile | 4 ++++
> > >  1 file changed, 4 insertions(+)
> > >
> > > diff --git a/scripts/kconfig/Makefile b/scripts/kconfig/Makefile
> > > index ea1bf3b3dbde..0044d49e149c 100644
> > > --- a/scripts/kconfig/Makefile
> > > +++ b/scripts/kconfig/Makefile
> > > @@ -158,6 +158,10 @@ help:
> > >                 if help=$$(grep -m1 '^# Help: ' $(f)); then \
> > >                         printf '  %-25s - %s\n' '$(notdir $(f))' "$${help#*: }"; \
> > >                 fi;)
> > > +       @echo  ''
> > > +       @echo  'Configuration environment variables:'
> > > +       @echo  '  KCONFIG_WERROR                 - Turn some Kconfig warnings into error conditions'
> > > +       @echo  '  KCONFIG_WARN_UNKNOWN_SYMBOLS   - Make Kconfig warn about all unrecognized config symbols'
> > >
> > >  # ===========================================================================
> > >  # object files used by all kconfig flavours
> > > --
> > > 2.44.0.rc0.258.g7320e95886-goog
> > >
> > >
> >
> > Why only two, while Kconfig supports more env variables?
> 
> Right.  I wanted to add only those that we use (and familiar with) for
> starters.  I'm not familiar with things like KCONFIG_PROBABILITY, for
> instance, and not sure how to document it (its Documentation/kbuild/kconfig.rst
> description is pretty lengthy).

Masahiro, any opinion?
  

On Wed, Feb 28, 2024 at 1:56 PM Sergey Senozhatsky
<senozhatsky@chromium.org> wrote:
>
> On (24/02/22 14:16), Sergey Senozhatsky wrote:
> > On (24/02/22 13:57), Masahiro Yamada wrote:
> > > On Thu, Feb 22, 2024 at 12:26 PM Sergey Senozhatsky
> > > <senozhatsky@chromium.org> wrote:
> > > >
> > > > Add a new section "Configuration environment variables" to
> > > > `make help` output in order to make it easier for people to
> > > > discover KCONFIG_WERROR, etc.
> > > >
> > > > Signed-off-by: Sergey Senozhatsky <senozhatsky@chromium.org>
> > > > ---
> > > >  scripts/kconfig/Makefile | 4 ++++
> > > >  1 file changed, 4 insertions(+)
> > > >
> > > > diff --git a/scripts/kconfig/Makefile b/scripts/kconfig/Makefile
> > > > index ea1bf3b3dbde..0044d49e149c 100644
> > > > --- a/scripts/kconfig/Makefile
> > > > +++ b/scripts/kconfig/Makefile
> > > > @@ -158,6 +158,10 @@ help:
> > > >                 if help=$$(grep -m1 '^# Help: ' $(f)); then \
> > > >                         printf '  %-25s - %s\n' '$(notdir $(f))' "$${help#*: }"; \
> > > >                 fi;)
> > > > +       @echo  ''
> > > > +       @echo  'Configuration environment variables:'
> > > > +       @echo  '  KCONFIG_WERROR                 - Turn some Kconfig warnings into error conditions'
> > > > +       @echo  '  KCONFIG_WARN_UNKNOWN_SYMBOLS   - Make Kconfig warn about all unrecognized config symbols'
> > > >
> > > >  # ===========================================================================
> > > >  # object files used by all kconfig flavours
> > > > --
> > > > 2.44.0.rc0.258.g7320e95886-goog
> > > >
> > > >
> > >
> > > Why only two, while Kconfig supports more env variables?
> >
> > Right.  I wanted to add only those that we use (and familiar with) for
> > starters.  I'm not familiar with things like KCONFIG_PROBABILITY, for
> > instance, and not sure how to document it (its Documentation/kbuild/kconfig.rst
> > description is pretty lengthy).
>
> Masahiro, any opinion?


I do not need this patch.
  

On (24/02/29 11:03), Masahiro Yamada wrote:
> > > > > +++ b/scripts/kconfig/Makefile
> > > > > @@ -158,6 +158,10 @@ help:
> > > > >                 if help=$$(grep -m1 '^# Help: ' $(f)); then \
> > > > >                         printf '  %-25s - %s\n' '$(notdir $(f))' "$${help#*: }"; \
> > > > >                 fi;)
> > > > > +       @echo  ''
> > > > > +       @echo  'Configuration environment variables:'
> > > > > +       @echo  '  KCONFIG_WERROR                 - Turn some Kconfig warnings into error conditions'
> > > > > +       @echo  '  KCONFIG_WARN_UNKNOWN_SYMBOLS   - Make Kconfig warn about all unrecognized config symbols'
> > > > >
> > > > >  # ===========================================================================
> > > > >  # object files used by all kconfig flavours
> > > > > --
> > > > > 2.44.0.rc0.258.g7320e95886-goog
> > > > >
> > > > >
> > > >
> > > > Why only two, while Kconfig supports more env variables?
> > >
> > > Right.  I wanted to add only those that we use (and familiar with) for
> > > starters.  I'm not familiar with things like KCONFIG_PROBABILITY, for
> > > instance, and not sure how to document it (its Documentation/kbuild/kconfig.rst
> > > description is pretty lengthy).
> >
> > Masahiro, any opinion?
> 
> 
> I do not need this patch.

Do you agree that putting kconfig env knobs into help makes sense
in general?  Especially those add valuable sanity checks.
  

On Thu, Feb 29, 2024 at 11:10 AM Sergey Senozhatsky
<senozhatsky@chromium.org> wrote:
>
> On (24/02/29 11:03), Masahiro Yamada wrote:
> > > > > > +++ b/scripts/kconfig/Makefile
> > > > > > @@ -158,6 +158,10 @@ help:
> > > > > >                 if help=$$(grep -m1 '^# Help: ' $(f)); then \
> > > > > >                         printf '  %-25s - %s\n' '$(notdir $(f))' "$${help#*: }"; \
> > > > > >                 fi;)
> > > > > > +       @echo  ''
> > > > > > +       @echo  'Configuration environment variables:'
> > > > > > +       @echo  '  KCONFIG_WERROR                 - Turn some Kconfig warnings into error conditions'
> > > > > > +       @echo  '  KCONFIG_WARN_UNKNOWN_SYMBOLS   - Make Kconfig warn about all unrecognized config symbols'
> > > > > >
> > > > > >  # ===========================================================================
> > > > > >  # object files used by all kconfig flavours
> > > > > > --
> > > > > > 2.44.0.rc0.258.g7320e95886-goog
> > > > > >
> > > > > >
> > > > >
> > > > > Why only two, while Kconfig supports more env variables?
> > > >
> > > > Right.  I wanted to add only those that we use (and familiar with) for
> > > > starters.  I'm not familiar with things like KCONFIG_PROBABILITY, for
> > > > instance, and not sure how to document it (its Documentation/kbuild/kconfig.rst
> > > > description is pretty lengthy).
> > >
> > > Masahiro, any opinion?
> >
> >
> > I do not need this patch.
>
> Do you agree that putting kconfig env knobs into help makes sense
> in general?  Especially those add valuable sanity checks.




I cannot accept the attitude:
  "I am interested only in these. I do not care about the rest,
  as keeping the correctness and consistency is the
  work for somebody else (= very likely the maintainer)"


This should be all or nothing.

I do not think all the env variables can be summarized
to fit in help.







--
Best Regards
Masahiro Yamada
  

On (24/02/29 12:36), Masahiro Yamada wrote:
> > On (24/02/29 11:03), Masahiro Yamada wrote:
> > > > > > > +++ b/scripts/kconfig/Makefile
[..]
> > > > > > > +       @echo  ''
> > > > > > > +       @echo  'Configuration environment variables:'
> > > > > > > +       @echo  '  KCONFIG_WERROR                 - Turn some Kconfig warnings into error conditions'
> > > > > > > +       @echo  '  KCONFIG_WARN_UNKNOWN_SYMBOLS   - Make Kconfig warn about all unrecognized config symbols'
> > > > > > >
> > > > > > >  # ===========================================================================
> > > > > > >  # object files used by all kconfig flavours
> > > > > > > --
> > > > > > > 2.44.0.rc0.258.g7320e95886-goog
> > > > > > >
> > > > > > >
> > > > > >
> > > > > > Why only two, while Kconfig supports more env variables?
> > > > >
> > > > > Right.  I wanted to add only those that we use (and familiar with) for
> > > > > starters.  I'm not familiar with things like KCONFIG_PROBABILITY, for
> > > > > instance, and not sure how to document it (its Documentation/kbuild/kconfig.rst
> > > > > description is pretty lengthy).
> > > >
> > > > Masahiro, any opinion?
> > >
> > >
> > > I do not need this patch.
> >
> > Do you agree that putting kconfig env knobs into help makes sense
> > in general?  Especially those add valuable sanity checks.
>
> I cannot accept the attitude:

This is entirely wrong interpretation.

>   "I am interested only in these. I do not care about the rest,

It's "I *do NOT know* what the rest do".  I cannot document something
that I have no knowledge of, can I?  So as a reasonable start I added
only those that I'm familiar with (and I have explicitly stated that
in previous emails), and I disagree with the "bad attitude" label.

> This should be all or nothing.
>
> I do not think all the env variables can be summarized
> to fit in help.

So the rational for that was that people run "make help" and find
out about new build targets, for instance, but there is no way for
people to find out about new Kconfig features (and yes, we are talking
"new features" here) that are controlled by env variables.  We need
to do something about it, don't you agree?
  

On Thu, Feb 29, 2024 at 12:47 PM Sergey Senozhatsky
<senozhatsky@chromium.org> wrote:
>
> On (24/02/29 12:36), Masahiro Yamada wrote:
> > > On (24/02/29 11:03), Masahiro Yamada wrote:
> > > > > > > > +++ b/scripts/kconfig/Makefile
> [..]
> > > > > > > > +       @echo  ''
> > > > > > > > +       @echo  'Configuration environment variables:'
> > > > > > > > +       @echo  '  KCONFIG_WERROR                 - Turn some Kconfig warnings into error conditions'
> > > > > > > > +       @echo  '  KCONFIG_WARN_UNKNOWN_SYMBOLS   - Make Kconfig warn about all unrecognized config symbols'
> > > > > > > >
> > > > > > > >  # ===========================================================================
> > > > > > > >  # object files used by all kconfig flavours
> > > > > > > > --
> > > > > > > > 2.44.0.rc0.258.g7320e95886-goog
> > > > > > > >
> > > > > > > >
> > > > > > >
> > > > > > > Why only two, while Kconfig supports more env variables?
> > > > > >
> > > > > > Right.  I wanted to add only those that we use (and familiar with) for
> > > > > > starters.  I'm not familiar with things like KCONFIG_PROBABILITY, for
> > > > > > instance, and not sure how to document it (its Documentation/kbuild/kconfig.rst
> > > > > > description is pretty lengthy).
> > > > >
> > > > > Masahiro, any opinion?
> > > >
> > > >
> > > > I do not need this patch.
> > >
> > > Do you agree that putting kconfig env knobs into help makes sense
> > > in general?  Especially those add valuable sanity checks.
> >
> > I cannot accept the attitude:
>
> This is entirely wrong interpretation.
>
> >   "I am interested only in these. I do not care about the rest,
>
> It's "I *do NOT know* what the rest do".  I cannot document something
> that I have no knowledge of, can I?  So as a reasonable start I added
> only those that I'm familiar with (and I have explicitly stated that
> in previous emails), and I disagree with the "bad attitude" label.


You were aware of:

 - several env variables are listed in the document
 - your patch would introduce a new "inconsistency"
 - somebody else would need to make efforts to solve it



> > This should be all or nothing.
> >
> > I do not think all the env variables can be summarized
> > to fit in help.
>
> So the rational for that was that people run "make help" and find
> out about new build targets, for instance, but there is no way for
> people to find out about new Kconfig features (and yes, we are talking
> "new features" here) that are controlled by env variables.  We need
> to do something about it, don't you agree?


Disagree.

I maintain the entire Kconfig, not like you only caring about
a particular feature.

If you add only two in help, I have no idea about
what it will look like in the end.
I am not convinced that it will be in good shape.
So, it is reasonable for me to reject it.
  

On (24/03/01 00:35), Masahiro Yamada wrote:
> > >   "I am interested only in these. I do not care about the rest,
> >
> > It's "I *do NOT know* what the rest do".  I cannot document something
> > that I have no knowledge of, can I?  So as a reasonable start I added
> > only those that I'm familiar with (and I have explicitly stated that
> > in previous emails), and I disagree with the "bad attitude" label.
> 
> 
> You were aware of:
> 
>  - several env variables are listed in the document
>  - your patch would introduce a new "inconsistency"
>  - somebody else would need to make efforts to solve it

OK.

> > So the rational for that was that people run "make help" and find
> > out about new build targets, for instance, but there is no way for
> > people to find out about new Kconfig features (and yes, we are talking
> > "new features" here) that are controlled by env variables.  We need
> > to do something about it, don't you agree?
> 
> Disagree.
> 
> I maintain the entire Kconfig, not like you only caring about
> a particular feature.
> 
> If you add only two in help, I have no idea about
> what it will look like in the end.
> I am not convinced that it will be in good shape.
> So, it is reasonable for me to reject it.

Yes, OK.  I wasn't talking about this patch in particular at that
point, I was more curious whether you agreed that we need to document
in some way those vars in `make help` or not.  If you see value in
documenting them then I can sit down and try to come up with v3 that
will (in one way or another) give a simple "help" description for
each of Kconfig's vars.
  

On Fri, Mar 01, 2024 at 01:33:16PM +0900, Sergey Senozhatsky wrote:
> On (24/03/01 00:35), Masahiro Yamada wrote:
> > > >   "I am interested only in these. I do not care about the rest,
> > >
> > > It's "I *do NOT know* what the rest do".  I cannot document something
> > > that I have no knowledge of, can I?  So as a reasonable start I added
> > > only those that I'm familiar with (and I have explicitly stated that
> > > in previous emails), and I disagree with the "bad attitude" label.
> > 
> > 
> > You were aware of:
> > 
> >  - several env variables are listed in the document
> >  - your patch would introduce a new "inconsistency"
> >  - somebody else would need to make efforts to solve it
> 
> OK.
> 
> > > So the rational for that was that people run "make help" and find
> > > out about new build targets, for instance, but there is no way for
> > > people to find out about new Kconfig features (and yes, we are talking
> > > "new features" here) that are controlled by env variables.  We need
> > > to do something about it, don't you agree?
> > 
> > Disagree.
> > 
> > I maintain the entire Kconfig, not like you only caring about
> > a particular feature.
> > 
> > If you add only two in help, I have no idea about
> > what it will look like in the end.
> > I am not convinced that it will be in good shape.
> > So, it is reasonable for me to reject it.
> 
> Yes, OK.  I wasn't talking about this patch in particular at that
> point, I was more curious whether you agreed that we need to document
> in some way those vars in `make help` or not.  If you see value in
> documenting them then I can sit down and try to come up with v3 that
> will (in one way or another) give a simple "help" description for
> each of Kconfig's vars.

Perhaps it might be a compromise to let 'make help' point to the
kbuild/kconfig documentation?

Kind regards,
Nicolas
  

On (24/03/01 12:04), Nicolas Schier wrote:
> Perhaps it might be a compromise to let 'make help' point to the
> kbuild/kconfig documentation?

Yes, I was thinking the same. A one-liner description per-env var
and point to documentation if one-liner is not enough

	KCONFIG_BARREL_ROLL	- kconfig does a barrel roll
	KCONFIG_FOO_BAR		- kconfig does foo and then bar (see
	documentation for details)
  

On Fri, Mar 01, 2024 at 11:28:44PM +0900, Sergey Senozhatsky wrote:
> On (24/03/01 12:04), Nicolas Schier wrote:
> > Perhaps it might be a compromise to let 'make help' point to the
> > kbuild/kconfig documentation?
> 
> Yes, I was thinking the same. A one-liner description per-env var
> and point to documentation if one-liner is not enough
> 
> 	KCONFIG_BARREL_ROLL	- kconfig does a barrel roll
> 	KCONFIG_FOO_BAR		- kconfig does foo and then bar (see
> 	documentation for details)

No, I thought about leaving out any concrete examples but just adding a
sentence like:

  kconfig and kbuild allow tuning and checks by settings various
  environment variables, cp. Documentation/kbuild/ for details.

Then there is no need to re-document each variable in 'make help' but
those who are new are explicitly pointed to the maintained
documentation.

Kind regards,
Nicolas