[PATCH] docs: kbuild: remove ISDN references in Makefile examples

[PATCH] docs: kbuild: remove ISDN references in Makefile examples

[Ethan Nelson-Moore]

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.

Signed-off-by: Ethan Nelson-Moore <enelsonmoore@gmail.com>
---
 Documentation/kbuild/makefiles.rst | 23 +++++++++--------------
 1 file changed, 9 insertions(+), 14 deletions(-)

diff --git a/Documentation/kbuild/makefiles.rst b/Documentation/kbuild/makefiles.rst
index 24a4708d26e8..dfac8c9611f4 100644
--- a/Documentation/kbuild/makefiles.rst
+++ b/Documentation/kbuild/makefiles.rst
@@ -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
-- 
2.43.0

Re: [PATCH] docs: kbuild: remove ISDN references in Makefile examples

[Julian Braha]

On 6/14/26 00:28, Ethan Nelson-Moore wrote:
> 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.
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/20260527142703.107110-1-andrew.jones@linux.dev/

- Julian Braha

Re: [PATCH] docs: kbuild: remove ISDN references in Makefile examples

[Ethan Nelson-Moore]

Hi, Julian,

On Sun, Jun 14, 2026 at 8:00 AM Julian Braha <julianbraha@gmail.com> wrote:
> 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,

> 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

Re: [PATCH] docs: kbuild: remove ISDN references in Makefile examples

[Nathan Chancellor]

On Sat, 13 Jun 2026 16:28:27 -0700, Ethan Nelson-Moore <enelsonmoore@gmail.com> wrote:
> 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.

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?

>
>
> diff --git a/Documentation/kbuild/makefiles.rst b/Documentation/kbuild/makefiles.rst
> index 7521cae7d56f..ec8de1c20834 100644
> --- a/Documentation/kbuild/makefiles.rst
> +++ b/Documentation/kbuild/makefiles.rst
> @@ -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).

> -  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.

-- 
Cheers,
Nathan

Re: [PATCH] docs: kbuild: remove ISDN references in Makefile examples

[Nicolas Schier]

On Wed, Jun 17, 2026 at 08:18:51PM -0700, Nathan Chancellor wrote:
> On Sat, 13 Jun 2026 16:28:27 -0700, Ethan Nelson-Moore <enelsonmoore@gmail.com> wrote:
> > 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.
> 
> 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?
> 
> >
> >
> > diff --git a/Documentation/kbuild/makefiles.rst b/Documentation/kbuild/makefiles.rst
> > index 7521cae7d56f..ec8de1c20834 100644
> > --- a/Documentation/kbuild/makefiles.rst
> > +++ b/Documentation/kbuild/makefiles.rst
> > @@ -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).
> 
> > -  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.

+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