[OpenAFS-devel] Refactoring the Solaris libafs code base

[Marcus Watts]

Jim Rees <rees@umich.edu> writes:
...
> If anyone is seriously considering refactoring the includes, I wish you good
> luck.  It's a job that needs doing.
> 
> Please try to stick to the original unix include guidelines:
> 
> first either sys/types or sys/param but not both
> then sys/*
> then net/* and other system includes
> then stdio and other user includes
> 
> Most modern systems don't care, but some do.  The complete guidelines used
> to be in style(9).

[  For what it's worth, style(9) is a netbsd-ism -- it didn't exist in
   4.4bsd or 386bsd.  Nor is it in solaris (where I think man9 was
   first invented).  The convention I've usually followed is to list
   most of the userland include files first (such as stdio.h etc.)
   then the system include files (<sys/), then net/ netinet/, then arpa/.
   As far as I can recall, early BSD & system V did the same thing.
   Of course, style(9) specifically says "kernel source style sheet" and
   is in the kernel man pages.  I don't know why they think stdio.h
   is likely to appear in kernel source in the first place.  ]

If someone does this, they may also want to do something
about the "h/" stuff, especially in rxgen.  In V7 unix
(way way back when) h/ held what then got copied into
/usr/include/sys .  Modern OpenBSD perpetuates this interesting
design decision in the symlink farm that's created inside
of libafs, and rxgen has incredibly detailed knowlege of
what's here & what it defines.

For openafs, this means any header file generated by rxgen needs to be
included after any system include files.  So that means files like
"afs/vldbint.h", "include/afs/ptint.h" etc. need to be last, or at
least after any sys/ includes.  It also means files that include those
files, such as "afs/vlserver.h", "afs/ptuser.h", that include these
files should also be nearly last.

OpenAFS has its own local set of conventions which have evolved but
don't seem to be well documented or consistently followed.  There's
some stuff in README.DEVEL (from jhutz@? ) but it's missing anything on
include files.  It's nearly always a good idea to include "afsconfig.h"
first thing, and afs/stds.h soon after -- BEFORE ANY OTHER INCLUDE
FILES.  Including afs/stds.h obliviates any need to include afs/param.h
- which is the older convention.  It also obliviates any need to
include sys/types.h (of course, this violates's the BSD style layout
Rees was recommending.) There are plenty of exceptions of this,
speaking of which, I can see some spots in rxk5 already...

					-Marcus