Plan for straightening out the include-file mess

I have been looking at making a split between client-side and server-side
include files as we discussed earlier this week (pghackers thread
"Include files for SPI are not installed", if you missed it). It turns
out that the major issue here is not just divvying up the files; the
problem is that we have never had a clear concept of such a division
before, and so the core include files like postgres.h, c.h, config.h
contain a rather unholy mixture of things that are definitely
backend-only with things that are relevant to both clients and backends.
I think we need to start by clarifying the roles of these include files
and moving their contents around as necessary.

Currently, almost every .c in the distribution starts out by including
postgres.h, which in turn includes these other files:

postgres.h
postgres_ext.h
c.h
config.h
os.h
utils/elog.h
utils/palloc.h

Now elog.h and palloc.h are server-only facilities and certainly don't
belong in a client file's include set. I think what we want to do is
decree that postgres.h is the primary include file for backend .c files
only, and that frontend .c files should include something else.

postgres_ext.h would be a candidate to be that something else, except
that it's included by libpq-fe.h, so anything we add to postgres_ext.h
represents namespace pollution for libpq clients. I think we should be
very wary about adding a lot of stuff to postgres_ext.h. This suggests
that we'd best create a new primary include file for client-side .c files,
say "postgres_fe.h" or "postgres_client.h". (Anyone have a better naming
idea? Does the old 14-character limit still pose a problem anywhere?)

That would leave us with include trees like this:

backend .c file:
postgres.h
postgres_ext.h
c.h
config.h
os.h
utils/elog.h
utils/palloc.h

frontend .c file:
postgres_fe.h
postgres_ext.h
c.h
config.h
os.h

where the include files have these roles:

postgres_ext.h: definitions needed in frontend, backend, *and* by clients;
by design an extremely small file

postgres.h: backend-wide definitions

postgres_fe.h: definitions common to all client-side interface libraries

c.h: basic typedefs and macros needed by both frontend and backend, but
not intended to be exported to clients of frontend libraries

config.h: configuration definitions, not intended to be client-visible

os.h: platform-specific configuration hacks, not intended to be
client-visible (this comes from one of the src/include/port files)

config.h and os.h don't need to change, I think, but I'll go through the
definitions in the other four files and make sure everything is classified
reasonably.

It's possible that postgres_fe.h will end up containing nothing except
the inclusions of postgres_ext.h and c.h, in which case we wouldn't really
need to invent that file, but I'm still inclined to do so. I think it's
good practice to have a single include file that's the basic "must haves"
for all client-side code.

Now, since the intent is that the basic install provide headers needed
for client-side programming, we'd want to add postgres_fe.h to the
installed header set. But the following files can be removed from the
basic install:

access/attnum.h
commands/trigger.h
executor/spi.h
fmgr.h
postgres.h
utils/elog.h
utils/geo_decls.h
utils/palloc.h

We might also remove utils/fmgroids.h. I'm uncertain about this one.
The function OID macros it contains are potentially useful to clients,
but do we really want people hard-wiring function OIDs on the client
side? I doubt it.

There are two or three other include files, such as lib/dllist.h, that are
needed on the client side only because libpq-int.h includes them, and we
want to support client code that includes libpq-int.h. I am going to look
at skinnying that list down too. libpq-fs.h, in particular, looks like
mostly legacy junk ...

As we discussed, there'll be an additional install target (or RPM) that
installs these files and everything else from the src/include tree.

Comments?

regards, tom lane