Re: [clang-format] [NetBSD Style] Clarification regarding Include files order in NetBSD

[David Holland <dholland-tech%netbsd.org@localhost>]

On Tue, Jun 11, 2019 at 07:49:33PM +0530, Manikishan Ghantasala wrote:
 > After discussing with my mentors @christos, @mgorny and some devs in
 > #netbsd-code IRC channel I came up with a draft of this order of Include
 > files,
 > 
 > *<sys/param.h>* -- should come first.
 > 
 > <sys/types.h> -- should come next

In general .c files in the kernel should have either sys/param.h or
sys/types.h first, but you don't need both. If both are present,
though, it makes more sense for sys/types.h to be first, as roughly
the first thing sys/param.h does is include it.

Also, it's common for sys/cdefs.h to come before either. The only rule
for it is that it must appear before anything (e.g. __BEGIN_DECLS)
that depends on it.

 > <sys/ *.h>        -- followed by <sys/ > block sorted alphdebitcal
 > 
 > <net/ *.h>         -- all blocks sorted alphabetical
 > 
 > <netinet/ *.h>
 > 
 > <protocols/ *.h>

 > There are some other includes such as *<uvm/ *.h> ,  <fs/ *.h>, <dev/
 > *.h> *which
 > are also kernel includes, should they be after *<sys/ *.> *?

They should probably be sorted into the other non-sys/ kernel
includes, like net*/. Especially if you're trying to write rules for
some kind of order checker that isn't too smart.

However, if you have more leeway than that, the "proper" order is to
put infrastructure things before application things, which for the
kernel means what you see in ffs_vnops.c: first a stack of sys/, then
miscfs/, then ufs/ufs/, then ufs/ffs. (Why uvm/uvm.h comes after all
of these (rather than between sys/ and miscfs/) I dunno.) And in say
if_axe.c you'll see there's a stack of sys/, then net/, then dev/mii/,
then generic dev/usb/, then its own header. And when you find
machine/ in a .c file, it's usually towards the end; but in kernel
includes, that varies.

In an ideal world kernel includes would be ordered strictly from
low-level to high-level, by abstraction layer, but this is hard in
general and NetBSD's kernel headers aren't well enough organized to
support it.

Also in the kernel you'll find headers for kernel config options,
which often come before everything else and also often come after
everything else, which depends on what the option is and what (and how
much) it controls.

I very much doubt you'll be able to come up with a single set of rules
that accepts a significant fraction of the kernel source files as they
stand, and rearranging them arbitrarily in the name of rules isn't a
good idea.

Outside the kernel it's somewhat easier because there's no natural
order and the conclusion someone came to long ago was that
alphabetical order would serve.

 > Can I get more details regarding this include files order that I might have
 > missed?

The only rules I would actually recommend trying to _enforce_ are:

(1) all kernel .c files should begin with either sys/types.h or
sys/param.h, but if sys/cdefs.h or opt_*.h appears first that's ok;

(2) for userland .c files, all sys/, net*/, and other kernel-installed
headers should come before ordinary userland headers, and if any of
these appear sys/types.h should be present and be first.

(3) for userland .c files, all system headers should come before all
private headers.

Also if you have the ability to check it, (a) all opt_*.h in the
kernel and (b) sys/featuretest.h in userland should come before any
ifdefs that aren't (i) include guards, or (ii) used to govern when
opt_*.h are used.

Note that a bunch of header files in sys/sys are both userland and
kernel and have to be treated carefully. Hopefully this will be tidied
in the long run, but it's a Big Deal to do so.

-- 
David A. Holland
dholland%netbsd.org@localhost