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.