Re: [boost] Boost policy for putting headers in boost/ Was: #3541Support <boost/ptr_map.hpp>

Subject: Re: [boost] Boost policy for putting headers in boost/ Was: #3541Support <boost/ptr_map.hpp>
From: Joel de Guzman (joel_at_[hidden])
Date: 2009-10-29 10:55:49

John Maddock wrote:
>>> A header such as boost/libname/foo.hpp is only consistent if
>>> libname is monolithic (does not comprise of smaller modules or
>>> sub-libraries). IMHO, that is good only for small libraries.
>>
>> Works for MPL.  Nobody ever wonders where to find anything in MPL.
> 
> Having just included a bunch of mpl header without looking at the manual 
> once, I agree with that.  And no I don't happen to have the names 
> memorized (!), I just thought... "I wonder if the #includes are logical 
> enough that they're called boost/mpl/and.hpp" so I tried it and it all 
> worked first time :-)
> 
> That said there may be a case to be made for splitting into 
> sub-libraries - we did that with Boost.Math to avoid confusion between a 
> distribution called X and a special function called X.  Non-the-less I 
> hope the divisions are obvious enough that most people won't need to 
> look at the manual.
> 
> So +1 for a mpl/type_traits style of organization from me too,

For the record, I am not against this. It is in IMO the logical
choice for most libraries. What I am saying is that for bigger
libraries, it is logical to organize in modules. When you have
modules then that flat organization will start to break. E.g.
if "x.hpp" is a header of module "foo" of library "lib", then,
the logical structure is:

   boost/
     lib/
       foo/
         a.hpp
       foo.hpp
     lib.hpp

Notice that the header for module has the correct header:

     <boost/lib/foo.hpp>

However, components of foo (a.hpp) cannot be hoisted outside
its module. Thus, in this case, this is wrong:

     <boost/lib/a.hpp>

Your example is a prime symptom of the breakage:
"That said there may be a case to be made for splitting
into sub-libraries - we did that with Boost.Math to avoid
confusion between a distribution called X and a special
function called X.".

When a library is modular, clashes are typical, e.g.:

   boost/
     lib/
       foo/
         a.hpp
       bar/
         a.hpp
       foo.hpp
       bar.hpp
     lib.hpp

So, now you have two headers "a.hpp" under different modules,
sharing the same name. It then becomes obvious why this is
wrong:

     <boost/lib/a.hpp>

Regards,
-- 
Joel de Guzman
http://www.boostpro.com
http://spirit.sf.net
http://www.facebook.com/djowel
Meet me at BoostCon
http://www.boostcon.com/home
http://www.facebook.com/boostcon