[<prev] [next>] [<thread-prev] [day] [month] [year] [list]
Message-ID: <87h6beq1bi.fsf@oracle.com>
Date: Tue, 20 Aug 2024 15:25:21 -0700
From: Stephen Brennan <stephen.s.brennan@...cle.com>
To: Nathan Chancellor <nathan@...nel.org>
Cc: Masahiro Yamada <masahiroy@...nel.org>, Jonathan Corbet
<corbet@....net>,
linux-kernel@...r.kernel.org, linux-doc@...r.kernel.org,
linux-kbuild@...r.kernel.org, Nicolas Schier <nicolas@...sle.eu>
Subject: Re: [PATCH 1/1] Documentation: kbuild: explicitly document missing
prompt
Nathan Chancellor <nathan@...nel.org> writes:
> Hi Stephen,
>
> On Tue, Aug 20, 2024 at 10:09:46AM -0700, Stephen Brennan wrote:
>> There are a few lines in the kbuild-language.rst document which
>> obliquely reference the behavior of config options without prompts.
>> But there is nothing in the obvious location that explicitly calls
>> out that users cannot edit config options unless they have a prompt.
>
> Sure, I think the mention of "non-visible symbols" plus "no prompts
> anywhere" in the select section is both a little cryptic to people who
> are not pretty familiar with Kconfig and slightly disjoint from the
> prompt section, so some clarification and expansion would not be a bad
> idea! I do have some suggestions for the wording below.
>
>> Signed-off-by: Stephen Brennan <stephen.s.brennan@...cle.com>
>> ---
>> Documentation/kbuild/kconfig-language.rst | 3 +++
>> 1 file changed, 3 insertions(+)
>>
>> diff --git a/Documentation/kbuild/kconfig-language.rst b/Documentation/kbuild/kconfig-language.rst
>> index 1fb3f5e6193c3..8e9306b599cd3 100644
>> --- a/Documentation/kbuild/kconfig-language.rst
>> +++ b/Documentation/kbuild/kconfig-language.rst
>> @@ -54,40 +54,43 @@ applicable everywhere (see syntax).
>>
>> - type definition: "bool"/"tristate"/"string"/"hex"/"int"
>>
>> Every config option must have a type. There are only two basic types:
>> tristate and string; the other types are based on these two. The type
>> definition optionally accepts an input prompt, so these two examples
>> are equivalent::
>>
>> bool "Networking support"
>>
>> and::
>>
>> bool
>> prompt "Networking support"
>>
>> - input prompt: "prompt" <prompt> ["if" <expr>]
>>
>> Every menu entry can have at most one prompt, which is used to display
>> to the user. Optionally dependencies only for this prompt can be added
>> with "if".
>> + If a prompt is not set, then the config option cannot be changed by the user.
>
> Would "not present" be cleared than "not set"? It might also be worth
> calling out here no prompt means a "non-visible" symbol since you
> brought up the document brings that term up and does not really tell you
> what it means.
I realized this exact issue re: "non-visible" upon re-reading the cover
letter & patch after sending, so I 100% agree.
> Perhaps something like this might be just as clear while being
> consistent with the terminology? Feel free to disagree though!
>
> If a prompt is not present, the config option is a non-visible symbol,
> meaning its value cannot be directly changed by the user (such as
> altering the value in ``.config``) and the option will not appear in
> any config menus. Its value can only be set via "default" and "select"
> (see below).
I think this better than my suggestion :)
I'll send a v2 with that wording.
Thanks,
Stephen
>> + It will not appear in any menu, and even edits to ``.config`` cannot alter it.
>> + It can still be set via "default" and "select" (see below).
>>
>> - default value: "default" <expr> ["if" <expr>]
>>
>> A config option can have any number of default values. If multiple
>> default values are visible, only the first defined one is active.
>> Default values are not limited to the menu entry where they are
>> defined. This means the default can be defined somewhere else or be
>> overridden by an earlier definition.
>> The default value is only assigned to the config symbol if no other
>> value was set by the user (via the input prompt above). If an input
>> prompt is visible the default value is presented to the user and can
>> be overridden by him.
>> Optionally, dependencies only for this default value can be added with
>> "if".
>>
>> The default value deliberately defaults to 'n' in order to avoid bloating the
>> build. With few exceptions, new config options should not change this. The
>> intent is for "make oldconfig" to add as little as possible to the config from
>> release to release.
>>
>> --
>> 2.43.5
>>
Powered by blists - more mailing lists