| Message ID | 20231023090638.935867-1-vegard.nossum@oracle.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | Documentation: kbuild: clarifications | expand |
On Mon, Oct 23, 2023 at 6:06 PM Vegard Nossum <vegard.nossum@oracle.com> wrote: > > The kconfig language is subtle. Document a few more non-obvious > aspects of it. > > Also fix a small markup issue while we're at it. > > Cc: Arnd Bergmann <arnd@arndb.de> > Cc: Javier Martinez Canillas <javierm@redhat.com> > Cc: Sakari Ailus <sakari.ailus@linux.intel.com> > Cc: Nicolas Schier <nicolas@fjasle.eu> > Signed-off-by: Vegard Nossum <vegard.nossum@oracle.com> > --- > Documentation/kbuild/kconfig-language.rst | 53 ++++++++++++++++++++--- > 1 file changed, 48 insertions(+), 5 deletions(-) > > diff --git a/Documentation/kbuild/kconfig-language.rst b/Documentation/kbuild/kconfig-language.rst > index 0135905c0aa3..f694d90f83d1 100644 > --- a/Documentation/kbuild/kconfig-language.rst > +++ b/Documentation/kbuild/kconfig-language.rst > @@ -42,9 +42,11 @@ Every line starts with a key word and can be followed by multiple > arguments. "config" starts a new config entry. The following lines > define attributes for this config option. Attributes can be the type of > the config option, input prompt, dependencies, help text and default > -values. A config option can be defined multiple times with the same > -name, but every definition can have only a single input prompt and the > -type must not conflict. > +values. > + > +A config option can be defined multiple times (i.e. by multiple menu > +entries) with the same name, but each definition can have only a single > +prompt and their types must not conflict. The kernel code should not do this. Scattering the elements of the same CONFIG option results in unreadable, unmaintainable code. Kconfig supports it, but the actual implementation is incorrect, and the behaviour is obscure. > > Menu attributes > --------------- > @@ -136,7 +138,10 @@ applicable everywhere (see syntax). > below), reverse dependencies can be used to force a lower limit of > another symbol. The value of the current menu symbol is used as the > minimal value <symbol> can be set to. If <symbol> is selected multiple > - times, the limit is set to the largest selection. > + times, the limit is set to the largest selection. In other words, if > + at least one menu selecting another symbol is ``y``, then the selected > + symbol will also be ``y``. > + > Reverse dependencies can only be used with boolean or tristate > symbols. > > @@ -473,6 +478,22 @@ This is a collection of Kconfig tips, most of which aren't obvious at > first glance and most of which have become idioms in several Kconfig > files. > > +Misconceptions about prompts and symbols > +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ > + > +Looking at fragments of common Kconfig usage, it is easy to believe > +that a symbol can depend on another symbol. In fact, it is not the > +symbol itself that has a dependency; it is the visibility of the > +symbol's prompt that has a dependency. The dependency of a symbol and the visibility of a prompt are two different things. Each symbol does track its dependency, so called "direct dependency". (symbol::dir_dep) Prompts can have separate visibility. This is "show by example". config X86_VSYSCALL_EMULATION bool "Enable vsyscall emulation" if EXPERT default y depends on X86_64 When X86_64=n, X86_VSYSCALL is disabled. When EXPERT=n, the prompt becomes invisible, but the symbol itself can be enabled. X86_VSYSCALL_EMULATION is always y due to 'default y'. > + > +Likewise, since each prompt defines its own dependencies, it is quite > +possible to have two prompts for the same symbol with different sets > +of dependencies. As long as the user has at least one visible prompt, > +they can enable that symbol in their config. Conversely, if there are > +no visible prompts for a symbol, the user can not change its value, > +not even by explicitly setting it in their .config. (It may, however, > +still be selected by other prompts.) I do not want to advertise this because there is no beneficial case for doing this. > Adding common features and make the usage configurable > ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ > It is a common idiom to implement a feature/functionality that are > @@ -567,7 +588,7 @@ distro config owners, but also for every single developer or user who > configures a kernel. > > Such a dependency can be relaxed by combining it with the compile-testing rule > -above, leading to: > +above, leading to:: > > config FOO > bool "Support for foo hardware" > @@ -692,6 +713,28 @@ e98062ed6dc4 select A -> depends on A (3) > (2) That seems to be the gist of that fix. > (3) Same error. > > +Experimenting with smaller-scale Kconfigs > +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ > + > +It is fully possible to play around with smaller-scale Kconfig fragments > +instead of using the kernel's full set of Kconfig files. Create a file > +called ``Kconfig.test`` containing e.g.:: > + > + config MODULES > + bool "Modules" > + modules > + > + config FOO > + tristate "foo" > + > + config BAR > + tristate "bar" > + depends on FOO > + > +You can now e.g. use menuconfig on this by simply running: > +``scripts/kconfig/mconf Kconfig.test``. > + > + > Future kconfig work > ~~~~~~~~~~~~~~~~~~~ > > -- > 2.34.1 >
diff --git a/Documentation/kbuild/kconfig-language.rst b/Documentation/kbuild/kconfig-language.rst index 0135905c0aa3..f694d90f83d1 100644 --- a/Documentation/kbuild/kconfig-language.rst +++ b/Documentation/kbuild/kconfig-language.rst @@ -42,9 +42,11 @@ Every line starts with a key word and can be followed by multiple arguments. "config" starts a new config entry. The following lines define attributes for this config option. Attributes can be the type of the config option, input prompt, dependencies, help text and default -values. A config option can be defined multiple times with the same -name, but every definition can have only a single input prompt and the -type must not conflict. +values. + +A config option can be defined multiple times (i.e. by multiple menu +entries) with the same name, but each definition can have only a single +prompt and their types must not conflict. Menu attributes --------------- @@ -136,7 +138,10 @@ applicable everywhere (see syntax). below), reverse dependencies can be used to force a lower limit of another symbol. The value of the current menu symbol is used as the minimal value <symbol> can be set to. If <symbol> is selected multiple - times, the limit is set to the largest selection. + times, the limit is set to the largest selection. In other words, if + at least one menu selecting another symbol is ``y``, then the selected + symbol will also be ``y``. + Reverse dependencies can only be used with boolean or tristate symbols. @@ -473,6 +478,22 @@ This is a collection of Kconfig tips, most of which aren't obvious at first glance and most of which have become idioms in several Kconfig files. +Misconceptions about prompts and symbols +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Looking at fragments of common Kconfig usage, it is easy to believe +that a symbol can depend on another symbol. In fact, it is not the +symbol itself that has a dependency; it is the visibility of the +symbol's prompt that has a dependency. + +Likewise, since each prompt defines its own dependencies, it is quite +possible to have two prompts for the same symbol with different sets +of dependencies. As long as the user has at least one visible prompt, +they can enable that symbol in their config. Conversely, if there are +no visible prompts for a symbol, the user can not change its value, +not even by explicitly setting it in their .config. (It may, however, +still be selected by other prompts.) + Adding common features and make the usage configurable ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ It is a common idiom to implement a feature/functionality that are @@ -567,7 +588,7 @@ distro config owners, but also for every single developer or user who configures a kernel. Such a dependency can be relaxed by combining it with the compile-testing rule -above, leading to: +above, leading to:: config FOO bool "Support for foo hardware" @@ -692,6 +713,28 @@ e98062ed6dc4 select A -> depends on A (3) (2) That seems to be the gist of that fix. (3) Same error. +Experimenting with smaller-scale Kconfigs +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +It is fully possible to play around with smaller-scale Kconfig fragments +instead of using the kernel's full set of Kconfig files. Create a file +called ``Kconfig.test`` containing e.g.:: + + config MODULES + bool "Modules" + modules + + config FOO + tristate "foo" + + config BAR + tristate "bar" + depends on FOO + +You can now e.g. use menuconfig on this by simply running: +``scripts/kconfig/mconf Kconfig.test``. + + Future kconfig work ~~~~~~~~~~~~~~~~~~~
The kconfig language is subtle. Document a few more non-obvious aspects of it. Also fix a small markup issue while we're at it. Cc: Arnd Bergmann <arnd@arndb.de> Cc: Javier Martinez Canillas <javierm@redhat.com> Cc: Sakari Ailus <sakari.ailus@linux.intel.com> Cc: Nicolas Schier <nicolas@fjasle.eu> Signed-off-by: Vegard Nossum <vegard.nossum@oracle.com> --- Documentation/kbuild/kconfig-language.rst | 53 ++++++++++++++++++++--- 1 file changed, 48 insertions(+), 5 deletions(-)