Revisiting the Directory Structure Proposal

From: Jens Maurer (Jens.Maurer_at_[hidden])
Date: 2001-02-12 16:39:33

First of all, I would like to thank John Maddock for the writing his
paper "A Proposal for the Boost Directory Structure", available
in the CVS at development/more/directory-structure.html .  I like
the requirements-based approach very much.

The ultimate goal should be the implementation of a new directory
structure for boost.  Thus, we need general agreement or at least
a strong majority for a proposed structure.

I would like to discuss a few points in John's paper which I do
not agree with.

In general, I put a lot of emphasis on the requirement "Boost is a
collection of separate libraries".  For me, this overrules other
requirements such as "Mandatory Source code is centrally located".
I would like to find all components of a library in a central spot,
which makes hierarchical decomposition (think "numeric" domain)
much easier to grasp, oversee and manage.

Due to other strong requirements, we're unable to group the include
files in the library directory, however this is not the case for
mandatory source files, I believe. In short,
boost-root/.../library1/src  and  boost-root/.../library2/src
is my preferred way, where the "src" component signals to any
external build system that all files therein are mandatory source code
for the library build.  The "src" component is to be defined for
that purpose exclusively.

Similarly, the requirement "Boost supports installation to a
central location" does not preclude putting the documentation
into   boost-root/.../libraryX/doc .  Even copying the docs
by hand into the central location is feasible that way.

In short, I believe that a structure
  boost-root/.../libraryX/doc
  boost-root/.../libraryX/src
  boost-root/.../libraryY/doc
  boost-root/.../libraryY/src
  boost-root/.../subdomain/libraryZ/doc
  boost-root/.../subdomain/libraryZ/src
is more manageable as
  boost-root/.../doc/libraryX
  boost-root/.../doc/libraryY
  boost-root/.../doc/subdomain/libraryZ
  boost-root/.../src/libraryX
  boost-root/.../src/libraryY
  boost-root/.../src/subdomain/libraryZ
and the former is much more "discoverable" by the casual end-user,
because everything pertaining to "regex" is in one place (plus,
unavoidably, the headers in another).  I believe end-users will
want to look at the collection of all source files less often than
they wish to explore a certain specific domain or library.

Btw, the same arguments apply to tests: They should be within their
respective library subdirectories.

I'd like to make clear that I'm in favor of prescribing standard
subdirectory names under the "libraryX" directory, so that automated
tools require less metadata.

I would like to have one point clarified in John's paper:
When we define a subdomain, it's similar to adding a library except
that the sub-directory structure within the subdomain directory
is not that of a library, but essentially that of the parent directory.

If this sounds very similar to what we have now, you're about right.
Except that we formally define this structure so that future tools
can rely on it.

I'd like to also enquire how we proceed in this matter so that the
discussion doesn't simply die off without having moved John's
paper from the development to the main boost section (with the
appropriate changes, of course).

Jens Maurer