Re: directory structure (requirements summary and proposal)

From: Ed Brey (brey_at_[hidden])
Date: 2001-01-03 10:52:32

--- In boost_at_[hidden], John Maddock <John_Maddock_at_c...> wrote:
> Ed,
> 
> >One area that isn't covered specifically by the requirements that 
I'd like to see covered is for separate boost libraries to be easily 
added into end users' revision control systems.  It would be very 
nice to be able to specify at most a single header and a single 
directory to include all of a boost library end an arbitrary revision 
control system.
> 
> Point taken but that doesn't cover library dependencies - and I 
anticipate that this will become more and more of an important issue 
as more libraries are added - especially once the thread library is 
added.  That's why I proposed an automated tool to take care of inter-
library dependencies.  Checking out a single directory for a single 
library sounds nice, but its not that simple IMO.

I agree, there is no free lunch.  The way I envision using the tree, 
which seems like it might be a common practice, is to identify all 
the libraries in use.  This would be the union of those directly in 
use by end users and all dependent libraries.  While it would be nice 
to get the dependencies enumerated and checked into the local 
revision control system automatically, it's really not a big deal.  
It's a manual operation whenusing a new boost library to add it to 
the revision controls system, and it's not much more work to look at 
the boost dependency tree and make sure all dependencies are added, 
too.  The key to keeping it relatively painless (for me anyway) is 
having to go to few places to add the necessarly libraries.

A side note: it turns out that the libraries that are dependencies 
are so useful, they tend to be in use by end user code already.  I 
realize this will become less true as boost expands; however, I 
expect it will still remain largely true.

> 1) I like the idea that the directory containing the headers 
contains nothing but headers - it makes it easy to install the 
headers by copying a single directory to the install location.  I 
appreciate that this can be solved on unix machines with an install 
routine, but on other platforms where there is no standard 
installation methodology for headers/libraries this is less easy.

Could you please fill me in on what role directory with nothing but 
header files serves.  I can't see what value this has.

> 2) I like the idea that the mandatory source files are centrally 
located, if I want to find the source for library X, then looking in 
src/X/ is much more obvious than looking in either boost/libname/src/ 
or libs/libname/src/.
> If I want to know which libraries have mandatory source, then with 
the fat-root structure all I have to do is look in src/ to see a 
complete list (as subdirectories).  With the skinny-root structure, I 
have to scrabble around all over the place looking in each 
boost/libname/ directory to see if it has a src/ sub-directory.  And 
yes I realize that a unix sh solves this with a "ls boost/*/src", but 
that's another unix only solution. This is primarily what I mean 
by "discoverable", if a new user looks at the unzipped distribution, 
it should be blatantly obvious what lives where.

Either way seems pretty discoverable.  As you mentioned, UNIX has a 
solution as you specified for finding which libraries have mandatory 
source under the structure boost/libname/src.  Windows also has 
solutions: either "dir src /s" or opening the find windowe from 
explore, and doing a search for src.  Are there any systems that 
don't have a straightforward solution to this?

> 3) I like the idea that the documentation directory contains docs 
and only  docs - one reason (smart file browsers like KFM) was given 
in the rationale  online, but there is another - if I want to copy 
all the docs to a central location (lets say a network drive), then 
the fat root structure makes it easy - just copy the docs/ 
subdirectory. This isn't possible with the skinny-root structure 
although again this can be partially solved on some platforms with an 
install routine.

I agree that this is an advantage with the fat root.  As you pointed 
out in your previous post, the question is how often does one whant 
to isolate a single catagory (e.g. docs) compared with isloating a 
single library. While easy isolation of docs is nice, I think easy 
isolation of libraries is even nicer (i.e. more useful).  However, I 
realize that I may be missing some needs and focusing too much on end 
user revision control.  I think what we need is a list of uses for 
each layout mode.  Here's a start:

Group by library:
- Access to individual, complete libraries for easy migration into 
end user revision control systems.
- No need for aliases in boost CVS. (So what?)

Group by category:
- Easy to copy documents without accompanying source to separate 
location. (How useful is this? Is it bad that the license files won't 
get copied?)
- All first-level headers by themselves in single directory. (Not 
sure how this is useful.)

The value of each bullet is important.  The only one I consider of 
much merit is the first, but I'd like to hear others' input.