Re: [Boost-users] Header file granularity policy?

From: Jeff Garland (jeff_at_[hidden])
Date: 2006-08-19 02:39:48

Scott Meyers wrote:
> Some Boost libraries, such as SmartPtr and Variant, offer a single header with 
> declarations for all library functionality as well as a set of headers for 
> subsets of functionality.  For example, smart_ptr.hpp declares all of 
> shared_ptr, shared_array, weak_ptr, scoped_ptr, scoped_array, and intrusive_ptr. 
>   If I don't want all these declarations, I can use more specific headers, e.g., 
> shared_ptr.hpp or scoped_array.hpp.  Such libraries allow me to choose between 
> the convenience of a single comprehensive header or the precision of multiple 
> targeted headers.
> 
> Other libraries seem to offer only the collection of targeted headers.  For 
> example, FileSystem offers five headers, but there doesn't seem to be a 
> comprehensive filesystem.hpp.  

I think you missed  the boost/filesystem.hpp -- I believe it includes 
"everything" except the fstream.hpp.

> Similarly, Lambda seems to offer only targeted 
> headers;  there doesn't seem to be a single "declare everything in Lambda" 
> header.  (There is a lambda.hpp, but it's not comprehensive, e.g., it doesn't 
> declare Lambda's bind.)

Ok.

> I find that this kind of inconsistency among libraries degrades my experience as 
> a Boost user, especially when I'm first learning to use a library.  More than 
> once I've spent time puzzling over a compilation error, only to discover that my 
> mistake was not including a needed header.  (I seem to make this error most 
> commonly when using Lambda.)  

Yeah, that's happened to me before too.

> Is there some kind of Boost convention or policy 
> on whether a library should offer a comprehensive "declare everything in the 
> library" header in addition to more targeted headers?

There are header and directory policies:

http://www.boost.org/more/header.htm
http://www.boost.org/more/lib_guide.htm#Directory_structure

Unfortunately, it doesn't mention these issues.  Overall I'd say that the 
trend is toward granular headers for the usual dependency / design issues with 
a single all-inclusive header...but, as you point out it's not 100% 
consistent. There are special cases -- like libraries that provide 
serialization support normally don't put this in the 'all-inclusive' header 
because they don't want to drag in all of the serialization stuff unless it's 
really needed.  Or the fstream case in filesystem which avoid the iostream 
headers unless you want to use the fstream with filesystem::path.

I think it would be good to improve on this. Care to take a crack at writing 
some guidelines for the docs?

Jeff