Re: [PATCH] kbuild: add header check facility as a manually run static analyzer

[Nathan Chancellor]

On Wed, Sep 16, 2026 at 03:24:09PM -0700, Randy Dunlap wrote:
> On 9/15/26 3:43 AM, Jani Nikula wrote:
> > There have been various attempts at adding a header test or check
> > mechanism in the kernel build system. The header check primarily
> > consists of ensuring headers are self-contained, have include guards,
> > and, in some cases, pass kernel-doc.
> > 
> > The main problems have been:
> > 
> > - The dependency tracking creates undesirable artefacts (infamously also
> >   known as disgusting turds) in the build directory.
> > 
> > - Gating the feature behind a kconfig option is complicated due to
> >   allyesconfig builds. It's possible, but requires a verbose and
> >   confusing negative proxy config option.
> > 
> > - Naming the dependency tracking files with a dot prefix or placing them
> >   in a dot prefixed subdirectory in the build directory to hide them has
> >   been exceedingly difficult to achieve. (In part due to some Makefiles
> >   building files in subdirectory hierarchies.)
> > 
> > - The debate which headers, if any, should really be self-contained is
> >   virtually open-ended.
> 
> I would expect that headers in include/uapi/*.h should be self-contained,
> but apparently that's just a pipe dream on my part, or maybe it's just
> a maintainer option.
> 
> With 'make HEADER_CHECK="include/uapi/" headercheck'
> I see over 70 errors (mostly typedefs or defined constants, but not only
> those), such as:
> 
> In file included from <command-line>:
> ./../include/uapi/linux/hdlc/ioctl.h:74:21: error: ‘IFNAMSIZ’ undeclared here (not in a function)
>    74 |         char master[IFNAMSIZ];  /* Name of master FRAD device */
>       |                     ^~~~~~~~
> In file included from <command-line>:
> ./../include/uapi/linux/input.h:29:6: warning: ‘__BITS_PER_LONG’ is not defined, evaluates to ‘0’ [-Wundef]
>    29 | #if (__BITS_PER_LONG != 32 || !defined(__USE_TIME_BITS64)) && !defined(__KERNEL__)
>       |      ^~~~~~~~~~~~~~~
> ./../include/uapi/linux/input.h:34:9: error: unknown type name ‘__kernel_ulong_t’
>    34 |         __kernel_ulong_t __sec;
>       |         ^~~~~~~~~~~~~~~~
> In file included from ./../include/uapi/linux/papr_pdsm.h:14,
>                  from <command-line>:
> ../include/linux/ndctl.h:19:33: error: ‘PAGE_SIZE’ undeclared here (not in a function)
>    19 |         ND_MIN_NAMESPACE_SIZE = PAGE_SIZE,
>       |                                 ^~~~~~~~~
> In file included from <command-line>:
> ./../include/uapi/linux/patchkey.h:15:2: error: #error "patchkey.h included directly"
>    15 | #error "patchkey.h included directly"
>       |  ^~~~~
> In file included from <command-line>:
> include/uapi/xen/gntdev.h:159:25: error: unknown type name ‘grant_ref_t’
>   159 |                         grant_ref_t ref;
>       |                         ^~~~~~~~~~~
> include/uapi/xen/gntdev.h:161:25: error: unknown type name ‘domid_t’
>   161 |                         domid_t domid;
>       |                         ^~~~~~~

include/uapi already has its own header checking infrastructure under
CONFIG_UAPI_HEADER_TEST and usr/include/Makefile, which avoids this with
a no-header-test list that includes many of the files listed in these
messages. To be honest, we should probably forbid HEADER_CHECK from
including 'include/uapi' and refer people to use CONFIG_UAPI_HEADER_TEST
instead, as there are other differences like being built under a
different C standard or C++ and such that the existing infrastructure
handles.

That said, I think the overall idea seems fine and relatively clean, at
least from my Kbuild perspective, as it is completely opt in, so the
previous objection to CONFIG_HEADER_CHECK_DISABLE and widely exposing
this to builds is pretty much moot.

-- 
Cheers,
Nathan