Re: [boost] directory structure (requirements summary and proposal)

From: John Maddock (John_Maddock_at_[hidden])
Date: 2001-01-02 07:40:46

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 anticipated that this would be partly covered by doing something like
this:

# check out the regex library, this gets us all dependencies:
cvs -dboost-server checkout regex
#
# the regex library is now in a the boost/ subdirectory,
# import into our own system:
cd boost
cvs -dlocal-cvs-server import boost-regex boost-regex-3.02
#
# clean up, we don't need this any more:
cd ..
rm -r boost

As you say though, this means that boost (or a subset of boost) appears a
single library, and not a collection of libraries in the users own version
control system.

>The requirement "Individual boost libraries can be checked out from the
cvs
>repository" comes close; however, it is specific to cvs.  I'd prefer this
>requirement to be dropped, and more detail added to the "Boost is a
>collection of separate libraries" requirement.
>
>Other revision control systems may or may not have an alias feature, but
>even for the ones that do, it would be undesirable for each end user to
have
>to set up aliases for each library in use.

Point taken, if someone wants to mirror all of boost in their own version
control system then this would get more difficult.  Again though,
inter-library dependencies means that it was never all that simple in the
first place.

>John, regarding your opinion concern that the "skinny root structure" is
>less "discoverable", in what context is that?  I don't think we should
>consider how will the new system look versus the current, since the
current
>system will soon be fogotten.  The important question is how will the new
>system look in the context of what a new user is probably already familiar
>with from general experience.

OK, I called this the "skinny root structure" because it has fewer root
directory entries than now, as opposed to the proposed version which has
more than now - so lets call it the "fat root structure" .

The rationale goes like this:

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.

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.

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.

4) Suppose that I want to check in just the headers and source into my own
version control system - I don't want to clutter it up with docs or example
programs, I just want the stuff that essential to be able to build my
application.  With the fat-root system, this is easy - just check in boost/
and src/, with the skinny-root structure, the things I want are scattered
all over the place.

Ed, I can accept that none of the above may mean a thing to you, this is
the essential problem here - either you organize by sub-library - or you
organize by file type - either way someone is going to be upset, the
question is which structure upsets the fewest people, and which is easier
for new users to use and understand.  I also appreciate that the
skinny-root structure was proposed as a way to have both viewpoints, but I
feel that while it partly succeeds, it has many of the disadvantages of
both.

Then again I have been know to be wrong :-)

- John.