Re: [Boost-Users] Slight Alteration to Boost Directory Structure

From: William E. Kempf (wekempf_at_[hidden])
Date: 2003-01-08 09:44:36

> From: "Simon Bailey <conic_at_[hidden]>" <conic_at_[hidden]>
> 
> I've been using boost for about a year now.  I upgraded from 27 to 
> 28 and appreciated the backwards compatability.  But I'm wondering 
> if a slight modification to the directory structure is in order?
> 
> I have written a cross-platform class library.  The library provides 
> high-level business objects and comes bundled with boost 1.28.0 to 
> provide support for threads, CRC, shared_ptr, and function (or 
> whatever else the end user might want).
> 
> Currently, users need to add two directories to their #include 
> search path:
> include/boost
> include/sb_library
> 
> Then, in their source code:
> #include <boost/shared_ptr.hpp>
> #include <boost/thread/thread.hpp>
> #include <sb_library/business_facet/business_object.h>
> 
> Two problems (albeit very minor ones!)
> 1. Boost has two levels of includes (due to it's history of course).

Two levels?  There's only one, $BOOST_ROOT/boost.  To avoid name clashes, many libraries are located in library specific directories off of this, as you see with <boost/thread/thread.hpp>.  Something that many libraries do (and Boost.Threads will be updated to do shortly) is to have a single header in the root include directory that includes all of the headers from the library directory, thus for Boost.Threads you'd include only <boost/thread.hpp> instead of <boost/thread/thread.hpp>, <boost/thread/mutex.hpp> etc.

> 2. Each library bundled with boost means another #include search 
> path needs to be added.

No, there's only one path added for all Boost libraries, $BOOST_ROOT/boost.

> Proposed solution:
> 1. Create a single boost include directory instead of having the two 
> nested ones that there are now.

What two nested ones?

> 2. Put all boost headers into a sub-directory of boost
> eg <boost/ptr/shared_ptr.hpp>, <boost/thread/thread.hpp>.  (It's a 
> small change for existing users to change their includes).

This is mostly how it is now... though many headers don't live in library specific subdirectories (which is probably how it should be).

> 3. Place all src, documentation etc. into a directory within boost 
> called "private" or something.
> 
> Suggested directory structure:
> 
> --include // This is the only directory needed to be specified in 
> the #include search path
> ----other_library1
> ----other_library2
> ----boost 
> -------ptr
> -------thread
> -------private
> ----------documentation
> ----------src
> ----------thread
> 
> In other words, you will have <boost/ptr/...> and <boost/thread/...> 
> but never <boost/private/...>.

This is just a variation on what's currently done, and I can't see how it buys you anything, and actually is a more confusing layout IMHO.
 
> I think it's worth breaking the backwards compatability a little in 
> order to bring the older boost headers in line with the directory 
> structure of the newer ones like thread.  I also think enabling a 
> single include path for multiple libraries is useful.

Boost.Threads followed existing directory guidelines (as do all libraries).  There's no difference between it and "older" libraries (note that Boost.Threads is not that new).
 

William E. Kempf
wekempf_at_[hidden]