From: Daryle Walker (darylew_at_[hidden])
Date: 2002-03-14 16:35:36
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. Deal. (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
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, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk