Re: Directory Structure

From: Lois Goldthwaite (loisg_at_[hidden])
Date: 2000-12-12 08:37:54

Surely we can come up with a system flexible enough to accommodate both
the people who want a single all-encompassing libboost.so, and those who
want the granularity of individual mini-libs.

How about this as a directory structure:

boost_v1.19/			// level 0 - argument to -I
    boost/			// level 1
        regex/			// level 2
            src/		// level 3
            doc/
            examples/
        threads/
            src/
            doc/
            examples/
        py_cpp/
            src/

... and so forth. 

The regex directory, to pick one, contains all the headers for John's
regex library. Under it, src contains the .cpp files necessary for this
component alone, plus a makefile which I will discuss further below. doc
and examples should be obvious.

The top-level boost directory contains a _single header_ for each
library, which provides all the declarations necessary to use that
library:

    #include <boost/threads.h>
    #include <boost/regex.h>

and so forth. These headers, of course, just hold #include directives
for all the headers in the relevant subdirectory:

    // boost/regex.h
    #include <boost/regex/header1.h>
    #include <boost/regex/header2.h>
    #include <boost/regex/header3.h>

The idea is that people can conveniently use any class/function in the
library after writing just the single #include statement. Of course
there may be a slight increase in compilation time if the library
headers are very large and complicated, but if this is a burden the
additional granularity is always available by specifying the individual
headers in level 2.

Besides convenience, having a single header for each library has another
advantage: it isolates the user from any subsequent changes in the
directory structure, or other organizational considerations. And it
makes it easy to test against multiple versions of the library, simply
by changing the argument to -I.

As libraries are added to boost or evolve within it, the only
integration effort necessary should be updating index.html. Each library
author provides the single header for the top level, plus the tree that
goes below it, with a makefile which conforms to the pattern, of course.
If that library is divided into sub-components that complicate the tree,
it's up to the library author to handle the situation locally. 

The level 1 boost directory also contains a single index.html file with
links into docs for all the other libraries. And it holds a top-level
Makefile, one which will recursively invoke the Makefiles in level 3,
for convenience in building the whole package at once. (The top level
Makefile just looks for any subdirectory with a src below it, and
invokes its Makefile.) Each library-specific Makefile can be invoked
individually to build its stand-alone version. With some thought in
naming the targets:

        make TOTAL
        make SINGLE

it should be possible to create a single Makefile template which can
cope with the various options we're talking about. 

Note that I've adopted the suggestion to include "boost/" in the header
names. From a code management point of view, I think this is an
excellent idea, and it prevents name clashes with headers from other
libraries.

This idea is stolen from the Objectspace C++ Toolkits, which use a
similar scheme. Another idea worth lifting is that of creating a single
configuration file (again, to be in boost) with macros for all the
compiler options. Each makefile starts by including this config file,
which contains not just CFLAGS but COMPILER_NAME, the target LIBNAME,
possible DEBUG_OPTIONS, MULTITHREAD_OPTIONS, LINKER_ARGS, and so forth.
The makefiles just concatenate these macros to build a command line.

I hope this is clear from the description. I need to do some work on our
makefiles, and I'll try to post some sample "generified" files here when
I do, if people think this sounds worth pursuing.

Lois