docs: kbuild: remove ISDN references in Makefile examples
Subsystems (2)
PATCH 1/1 docs: kbuild: remove ISDN references in Makefile examples
Documentation/kbuild/makefiles.rst uses some extracts from now-removed ISDN code as examples. While they are harmless, they appeared in my checks for CONFIG_* symbols referenced but not defined in the kernel. Replace them with generic examples.
--- Documentation/kbuild/makefiles.rst | 23 +++++++++-------------- 1 file changed, 9 insertions(+), 14 deletions(-)
Documentation/kbuild/makefiles.rst +9 -14
@@ -127,11 +127,8 @@ controllers are detected, and thus your disks are renumbered. Example:: - #drivers/isdn/i4l/Makefile - # Makefile for the kernel ISDN subsystem and device drivers. - # Each configuration option enables a list of files. - obj-$(CONFIG_ISDN_I4L) += isdn.o - obj-$(CONFIG_ISDN_PPP_BSDCOMP) += isdn_bsdcomp.o + obj-$(CONFIG_FOO) += foo.o + obj-$(CONFIG_BAR) += bar.o Loadable module goals - obj-m -----------------------------
@@ -145,10 +142,9 @@ simply adds the file to $(obj-m). Example:: - #drivers/isdn/i4l/Makefile - obj-$(CONFIG_ISDN_PPP_BSDCOMP) += isdn_bsdcomp.o + obj-$(CONFIG_FOO) += foo.o -Note: In this example $(CONFIG_ISDN_PPP_BSDCOMP) evaluates to "m" +Note: In this example $(CONFIG_FOO) evaluates to "m". If a kernel module is built from several source files, you specify that you want to build a module in the same way as above; however,
@@ -158,13 +154,12 @@ variable. Example:: - #drivers/isdn/i4l/Makefile - obj-$(CONFIG_ISDN_I4L) += isdn.o - isdn-y := isdn_net_lib.o isdn_v110.o isdn_common.o + obj-$(CONFIG_FOO) += foo.o + foo-y := foo_1.o foo_2.o foo_3.o -In this example, the module name will be isdn.o. Kbuild will -compile the objects listed in $(isdn-y) and then run -``$(LD) -r`` on the list of these files to generate isdn.o. +In this example, the module name will be foo.o. Kbuild will +compile the objects listed in $(foo-y) and then run +``$(LD) -r`` on the list of these files to generate foo.o. Due to kbuild recognizing $(<module_name>-y) for composite objects, you can use the value of a ``CONFIG_`` symbol to optionally include an
Signature · 1 line
2.43.0
Quoted 3 lines · Ethan Nelson-Moore
Documentation/kbuild/makefiles.rstuses some extracts from now-removed ISDN code as examples. While they are harmless, they appeared in my checks for CONFIG_* symbols referenced but not defined in the kernel.
Hi Ethan, are you using the kconfig-sym-check[1] that was recently merged? This dead symbol check should not have the false positives on documentation.
Though maybe your check also catches dead symbols in C, Rust, Makefiles?
[1]
https://lore.kernel.org/all/[email protected]/
- Julian Braha
Hi, Julian,
Quoted 3 lines · Julian Braha
Hi Ethan, are you using the kconfig-sym-check[1] that was recently merged? This dead symbol check should not have the false positives on documentation.
No, I'm not - I had heard about the Kconfirm project, but not about this similar tool. Thanks for letting me know,
Quoted 1 line
Though maybe your check also catches dead symbols in C, Rust, Makefiles?
Yes, it does; it has orthogonal functionality to kconfig-sym-check, which only operates within Kconfig files.
My script checks for CONFIG_* symbols that are referenced in code or documentation, but that are not defined in any Kconfig file. The decision to include documentation is intentional and has revealed several instances of outdated documentation.
It also filters out symbols that are defined in a Makefile or hardcoded with #define, and also attempts to filter out structs and enums (and typedefs thereof) named CONFIG_*, though I need to improve this further.
I will post it publicly once I have done so.
Ethan
Nathan Chancellor
maintainerQuoted 4 lines · Ethan Nelson-Moore
Documentation/kbuild/makefiles.rstuses some extracts from now-removed ISDN code as examples. While they are harmless, they appeared in my checks for CONFIG_* symbols referenced but not defined in the kernel. Replace them with generic examples.
While I am fine with adjusting these examples to make it easier on tools such as yours, how does this solve your problem? CONFIG_FOO and CONFIG_BAR are still not defined anywhere. Are you adding exceptions for these symbols? I ask because I would like these to be a little more "kernel specific" if that makes sense.
Maybe it is not worth even checking Documentation/ for dead configurations at all since that is probably not going to be a bug very often but I guess it helps with cleaning up dead documentation?
Documentation/kbuild/makefiles.rst controllers are detected, and thus your disks are renumbered. · line 132
Quoted 13 lines
Documentation/kbuild/makefiles.rst +0
-3@@ -127,11 +127,8 @@ controllers are detected, and thus your disks are renumbered. Example:: - #drivers/isdn/i4l/Makefile - # Makefile for the kernel ISDN subsystem and device drivers. - # Each configuration option enables a list of files.
I think I would keep these comment, it is still relevant (at least to me).
Documentation/kbuild/makefiles.rst controllers are detected, and thus your disks are renumbered. · line 131
Quoted 4 lines
Documentation/kbuild/makefiles.rst +2
-2- obj-$(CONFIG_ISDN_I4L) += isdn.o - obj-$(CONFIG_ISDN_PPP_BSDCOMP) += isdn_bsdcomp.o + obj-$(CONFIG_FOO) += foo.o + obj-$(CONFIG_BAR) += bar.o
For instance, I think using a more descriptive symbol illustrates the example a little better.
obj-$(CONFIG_DRIVER_ONE) += driver_one.o obj-$(CONFIG_DRIVER_TWO) += driver_two.o
Same thing for the other examples. I just don't find these variable names to be particularly good when illustrating actual real world examples as opposed to conceptual ones. Not sure if others feel the same way.
Signature · 2 lines
Cheers, Nathan
Nicolas Schier
maintainerQuoted 41 lines · Nathan Chancellor
Quoted 4 lines · Ethan Nelson-Moore
Documentation/kbuild/makefiles.rstuses some extracts from now-removed ISDN code as examples. While they are harmless, they appeared in my checks for CONFIG_* symbols referenced but not defined in the kernel. Replace them with generic examples.While I am fine with adjusting these examples to make it easier on tools such as yours, how does this solve your problem?
CONFIG_FOOandCONFIG_BARare still not defined anywhere. Are you adding exceptions for these symbols? I ask because I would like these to be a little more "kernel specific" if that makes sense.Maybe it is not worth even checking
Documentation/for dead configurations at all since that is probably not going to be a bug very often but I guess it helps with cleaning up dead documentation?Documentation/kbuild/makefiles.rst controllers are detected, and thus your disks are renumbered. · line 132
Quoted 13 lines
Documentation/kbuild/makefiles.rst +0
-3@@ -127,11 +127,8 @@ controllers are detected, and thus your disks are renumbered. Example:: - #drivers/isdn/i4l/Makefile - # Makefile for the kernel ISDN subsystem and device drivers. - # Each configuration option enables a list of files.I think I would keep these comment, it is still relevant (at least to me).
Documentation/kbuild/makefiles.rst controllers are detected, and thus your disks are renumbered. · line 131
Quoted 4 lines
Documentation/kbuild/makefiles.rst +2
-2- obj-$(CONFIG_ISDN_I4L) += isdn.o - obj-$(CONFIG_ISDN_PPP_BSDCOMP) += isdn_bsdcomp.o + obj-$(CONFIG_FOO) += foo.o + obj-$(CONFIG_BAR) += bar.oFor instance, I think using a more descriptive symbol illustrates the example a little better.
Quoted 7 lines
obj-$(CONFIG_DRIVER_ONE) += driver_one.o obj-$(CONFIG_DRIVER_TWO) += driver_two.oSame thing for the other examples. I just don't find these variable names to be particularly good when illustrating actual real world examples as opposed to conceptual ones. Not sure if others feel the same way.
+1
I liked that the examples were taken from actual Linux kconfigs, so it was possible to look them up and check the context as well. So, yes, I think updating these is a good idea!
Kind regards,
Nicolas