| Message ID | 20240820171000.1656021-2-stephen.s.brennan@oracle.com (mailing list archive) |
|---|---|
| State | New |
| Headers | show |
| Series | Documentation: kbuild: explicitly document missing prompt | expand |
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@oracle.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. 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). > + 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 >
Nathan Chancellor <nathan@kernel.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@oracle.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 >>
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. + 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.
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. Signed-off-by: Stephen Brennan <stephen.s.brennan@oracle.com> --- Documentation/kbuild/kconfig-language.rst | 3 +++ 1 file changed, 3 insertions(+)