Modules, installing Squid headers, and src layout

Hello,

        To support loadable modules, we may need to alter Squid sources layout
or installation procedure. This email discusses the problem and four
possible solutions. Please review and suggest the best path forward.

All Squid modules will need to use some Squid header files to be able to
register their presence with Squid core code. Moreover, if a module
happens to use Squid code that is unused by Squid core, then the module
will need to be linked against a Squid library as well[1].

While it is possible for a module to use headers and libraries from
Squid sources, doing so is a big and dangerous hack -- the sources are
not designed to be used externally and may be in an inconsistent state,
leading to unusable modules or, worse, subtle bugs.

AFAIK, the solution is for Squid to _install_ everything that a module
may needed. Since a module may manipulate many Squid objects, this
implies that Squid should install all header files (and possibly many
libraries). Currently, Squid does not install any headers.

Installed headers can be placed in /usr/local/squid/include directory.
This is easy to do, but it would be difficult and error prone for a
module to distinguish Squid headers from other installed headers with
the same file name. Conflicts are likely and resolving them by changing
the order of -I options is often very difficult.

The alternative is to install headers in /usr/local/squid/include/squid
directory (note squid at the end). Modules will include such headers as
"squid/foo.h", virtually eliminating the possibility of a conflict. We
use this approach with other projects, and it works well.

Unfortunately for Squid, its code would also have to refer to its
headers using the "squid/foo.h" pattern. As you know, current header
files are in in a "squid" directory. They are in "src". We could move
all files from "src" to "src/squid". We use that design in Factory
projects and it works well. However, CVS will lose all commit history if
we move the files!

We could move just the header files into "src/include/squid", but then
their history will still be lost and separating header files from
sources is awkward, IMO (a few older Factory projects use this approach,
and I do not like it).

A third possibility is some kind of installation script wrapper that
takes existing header files and adds "squid/" prefixes to #include
statements while installing headers. This sounds ugly, and I have not
tried that, but it is probably possible. We could try that approach
until Squid migrates to something better than CVS.

To summarize, we could

0) Install Squid headers in /usr/local/squid/include and hope that there
are no name conflicts with other system-wide headers.

1) Install Squid headers in /usr/local/squid/include/squid and move
src/* to src/squid/, essentially losing commit history for all sources.

2) Install Squid headers in /usr/local/squid/include/squid and move
src/*.h to src/include/squid/, essentially losing commit history for
headers.

3) Install Squid headers in /usr/local/squid/include/squid using some
kind of install script that alters #include paths. Preserve source file
location and, hence, CVS history.

Did I miss any options? Which option is the best (for Squid 3.1)?

N.B. There is also a question of Squid "library" headers outside of
src/, but we should be able to mimic the above decision there as well.

Thank you,

Alex.
[1] A module using Squid code unused in Squid core itself may sound
weird, but we do have that situation in Traffic Spicer, where Spicer
provides functionality that many modules need but that are unused by
Spicer core.

Without linking against the host application library, the loadable
module cannot be loaded due to unresolved symbols -- the linker does not
include them in the executable because they are not needed in the
executable (until the module is loaded). We experimented with a few
linker options, but could not find the one that would force all symbols
to be included in the executable.
Received on Thu Oct 11 2007 - 20:17:16 MDT