[boost] [RFC] Header/namespace policy draft

From: Joel de Guzman (joel_at_[hidden])
Date: 2007-11-30 23:47:40

Hi,

As promised, here's a draft of the proposed
"Boost Header And Namespace Policy" (attached)
Comments, suggestions, etc. very welcome.

Regards,
-- 
Joel de Guzman
http://www.boost-consulting.com
http://spirit.sf.net

Boost Header And Namespace Policy

There has been an unwritten standard practice on header placement and
namespaces that has been developed over the years. The Boost policy
gives library authors a huge amount of freedom to organize and evolve
their libraries as they see fit. Authors of newer libraries, however,
had to try and figure out from the way existing libraries are
structured or ask help from fellow boosters with more boost experience
in "boostifying" their code. With very few exceptions, this worked
well in the past. Library authors stayed within the bounds of the
standard practice. Yet, with the rate Boost is growing, it would be
crucial to put the Boost standard practice in writing to avoid
confusion in the future.

This short document will attempt to formalize the Boost standard
practice on header placement, subdirectory and library organization,
and namespace conventions. One purpose of the review process is to
raise these issues at a proper time. It would be best to add adherence
to the standard practice as part of the review.

* Core libraries whose documented public interface fits in just a few
  headers and a few pages of documentation can put all their public
  headers in boost/ and their components in boost::.

  For a core library named foobar, the convention is as follows:

  - One or more (preferably one) header file(s). Example:

    boost/foobar.hpp

  - foobar components (classes, types, constants etc.) in
    namespace boost. Example:

    namespace boost
    {
        class foo {/*...*/};
        class bar {/*...*/};
    }

The concept of "core library" is not new. boost::shared_ptr, for
example, is a core library. It's pretty much common to all libraries.
Having a core library gives us structure. Typically, "core" libraries
have the highest number of dependencies. Looking at the dependency
diagram of boost, the core libraries will be at the bottommost with
lots of other libraries pointing acyclically at it. It's a must to
avoid having them depend on other libraries in other layers above the
core. More emphasis and constraints must be given to these "core"
libraries as they form the backbone of boost as a whole. For instance,
a broken core library will have disastrous effects on the whole Boost
library --core libraries should be very stable.

Determining wether a library is core can be part of the review. If the
author of a library intends it to be a "core" library, he can
explicitly say so and be subject for the review. A core library will
have to accept more stringent requirements such as stability and
non-dependence on other non-core libraries.

* Utility libraries whose documented public interface fits in just a few
  headers and a few pages of documentation can put all their public
  headers in boost/utility and their components in boost::.

  For a utility library named foobar, the convention is as follows:

  - One or more (preferably one) header file(s). Example:

    boost/utility/foobar.hpp

  - foobar components (classes, types, constants etc.) in
    namespace boost. Example:

    namespace boost
    {
        class foo {/*...*/};
        class bar {/*...*/};
    }

All utility libraries pass through the same Boost review process.
In certain occasions, a small library that are common to one or
more Boost libraries and has already been in extensive use may
undergo a "Fast track" review for inclusion as a boost utility.

* Non-core libraries may place a single consolidated convenience 
  header in boost/, forwarding to files of the form 
  boost/<libraryname>/<header>.hpp.  Regardless, their documented
  public components are not in boost/ or namespace boost::

  For a library named foobar, the convention is as follows:

  - A single boost/foobar.hpp that forwards to all the headers
    of foobar:
    
    boost/foobar.hpp
    
  - foobar components (classes, types, constants etc.) in
    namespace boost::foobar. Example:

    namespace boost { namespace foobar
    {
        class foo {/*...*/};
        class bar {/*...*/};
    }}

  - A subdirectory boost/foobar where all foobar headers are placed.

* Un-reviewed implementation details of libraries have been placed in
  boost/detail if they need to be used by other libraries and a
  subdirectory of boost/<libraryname>/ otherwise. Their documented
  public components are placed in boost/detail and namespace boost::detail.

* Libraries may host sub libraries that may be used by other boost
  libraries. Such sub libraries are typically meant for future boost
  review. Their documented public components are placed in
  boost/<host-libraryname>/<libraryname>/<header>.hpp and
  namespace boost::<libraryname>.

One such example is the proto library that is hosted by xpressive.
Another is fusion. The fusion library was once hosted by spirit. After
passing the boost formal review the fusion library is now a full
fledged boost library.