Re: [boost] Revisiting the Directory Structure Proposal

From: Beman Dawes (bdawes_at_[hidden])
Date: 2001-02-13 15:05:29

Jens Maurer wrote:

 >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.

I agree wholeheartedly.  John did a great job of identifying the 
requirements.

 >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.

I agree.  John's Discoverability requirement is important, but I think can 
be met with an "all components for a library (except headers) centralized" 
approach, too.  Notice that Discoverability works at both a directory and 
file level.  Many systems I've seen that are very discoverable at the 
directory level (all source files to be compiled in a single "src" 
directory for the entire project) are then miserably non-discoverable at 
the file level because there are so many files in that single src directory 
you can't see the forest for the trees.

Originally it seemed there was a serious problem with boost test programs 
being spread over separate library centric directories.  But we solved that 
(see regression.cpp), and now it is a non-issue.  We can use similar 
approaches to meet other needs.

There are some things we can do to improve human discoverablity.  Put the 
header files in boost-root/include/boost instead of boost-root/boost, for 
example.

 >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.

I agree.

 >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.

Do you think those subdirectories should always be used, even if they just 
contain a single file?   In the past I've argued that this was overkill, 
but I'm wavering.  Even the simplest library, which starts out with a 
single doc file (say index.htm) and a single test file (say foo_test.cpp), 
will often grow to have additional docs and tests.  And always having the 
directory structure does aid automated tools, and does aid human 
discoverability.

 >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.

Yes.  That should be made explicit with an example.

I also have a sense that having sub-namespaces follow the same pattern as 
the sub-domain.  But I guess that doesn't have to be decided right now - we 
are having a hard-enough time just with directories.

 >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.

The standardization of directory names are important too.  So while the 
structure may generally look a lot like our current structure, the details 
may vary quite a bit.  And there will be new directories (build tools, etc) 
not in the current structure.

 >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).

How about this?  Using the same format as John's "The Directory Structure" 
table, add your proposal to his paper.  Don't remove or change John's 
table, just add your own.

Then we will decide on one or the other.  How?  I don't know.  Let's see 
what the response is to your proposal.  But we will make a decision one way 
or another.  Directory structure uncertainties are holding up other 
important things (like a build system.)

Thanks to John for his paper, and Jens for his response!

--Beman