From: Daryle Walker (darylew_at_[hidden])
Date: 2002-03-24 03:54:01
Due to a recent post that I responded to, I realized that no one knows what
grouping philosophy I like applying to various sub-libraries I work with.
Well, let's try to explain it:
For example, we'll start a talk-show sub-library. To stop the sprawl of
headers in the top boost header directory, components for talk-shows will go
in a "talk_show" namespace (within the "boost" namespace). To make the new
headers easy to find, the headers for stuff in the "talk_show" namespace
will go into the new "BOOST_ROOT/boost/talk_show" directory.
Forward declarations, like <iosfwd>, make some applications of a class
easier. We could make the forward declaration header
<boost/talk_show/fwd.hpp>, but I like <boost/talk_show_fwd.hpp> better
because I don't like a lot of headers with the short name "fwd.hpp". This
header has forward declarations of classes, structures, and class templates
of all the public types in that sub-library's main headers. Any defaults
for class template parameters should be mentioned here, which may require
#including another forwarding declaration header to get the default names.
Typedef-s of the specific versions of the class templates go here too.
However, full class/struct definitions, full class template definitions,
enum definitions, and function or function template declarations or
definitions do _not_ go in the forward declaration header.
Each of the main headers in the "talk_show" namespace should #include the
forward declaration header to enforce consistency. If you used a forward
declaration of a template parameter default, you should #include the header
that fully declares that default.
Note that the previous two paragraphs imply that every time a new component
is added to a sub-library, any other component in that sub-library that you
use will get marked with a dependency recompile when you upgrade your Boost
installation. (I know you could avoid the problem by making a forward
declaration header for each sub-library component, but that would result in
a _lot_ of little FD-headers. I'd rather take advantage of grouping.)
The sub-library's extra files would be in "BOOST_ROOT/libs/talk_show". It
would have the "doc", "test", "example", and possibly "src" subdirectories.
All the components will share those subdirectories. The "doc" subdirectory
will have an "index.html" that lists the FD-header and all the main
component headers. The main component headers listings will have links to
each component's HTML documentation in the same subdirectory.
1. A FD-header may have to #include <boost/config.hpp>.
2. A major example of  would be when some of the components don't work
on some compilers.
3. I may have forgotten stuff, but hopefully your comments and/or flames
will remind me.
4. I'm trying to make the (new) I/O sub-library like this. I've also tried
to make the math and integer sub-libraries approach this.
-- Daryle Walker Mac, Internet, and Video Game Junkie darylew AT mac DOT com
Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk