Re: Plan for straightening out the include-file mess - Mailing list pgsql-hackers

On Thu, 8 Feb 2001, Alex Pilosov wrote:

> Great! :)
> 
> It might also clean up something that I've been fighting against for
> awhile: when I include files needed for SPI, it drags also a lot of other
> garbage in, which conflicts with other things (namely, trying to get a
> file to simultaneously include SPI and perl headers is impossible). 
> 
> I realise it might be a lot of pain to clean up, but, you may consider
> having a separate top-level include for SPI, which would not define (by
> default) things like DEBUG, USE_LOCALE, union semun, etc. 
> 
> IMHO, it should really include only definitions of relevant data
> structures which interface with SPI code...
> 
> I realize that complete split for SPI/module from "core backend" might be
> very hard, so a thing to consider would be to have (like linux kernel code
> has) #define IN_CORE (you are welcome to come up with better name), and
> include "core backend"-specific things conditionally on that being
> defined.
> 
> 
> -alex
>
> On Thu, 8 Feb 2001, Tom Lane wrote:
> 
> > 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
> > 
> > 
> 
>