Re: [boost] New boost user

From: Jeff Squyres (jsquyres_at_[hidden])
Date: 2000-10-09 12:48:22

On Mon, 9 Oct 2000, Beman Dawes wrote:

> Alternately, a src sub-directory could appear in each library's
> directory in libs.  But I think your suggestion above is better - it
> is probably clearer to someone just looking at the directory tree.
> 
> What do others think?  Should we add a src sub-directory, containing
> sub-directories (with same name as under /libs) for each library which
> needs source code compiled before use?

Jeremy Siek, William Kempf, and I have been discussing this off the list
for a few days now in the attempt to get some working fodder to post back
to the list.  We're not in complete agreement, but this message seems like
a good one to reply to with what we came up with so far.  

It's a bit more than a "least resistance" approach, so there will likely
be some strong feelings here.  :-)  The intent was to make it a "more
standardized" tree overall -- not a *completely* standardized tree (i.e.,
individual library authors should still have a considerable amount of
freedom), but at least have something that can potentially be put in the
boost guidelines.  I can't speak for Windows source code distributions,
but my contributions were strongly influenced by seeing countless unix
.tar.gz source code distributions over the years.

Notation: I use $top_srcdir, below, to indicate the directory that the
boost distribution was expanded into.

(Bill/Jeremy, feel free to chime in if I get anything wrong)

-----

There are 2 issues: a potential build process and the boost directory
structure.  It seems that the directory structure should probably be
discussed first, since it will influence the build process much more than
vice versa.  So I'll save the build process discussion for a different
post.

*** Top-level boost distribution directory:

We're talking about the directory structure, but I specifically mention 2
files since they should also be part of the distribution (and others have
mentioned them, I think), and should have standardized names:

- A brief README file.  It potentially lists the libraries that are
included, gives a very brief overview of each (2-3 sentences), and says
"go see the full docs [wherever they are located] for more information."  
It also has some reference to wherever the build docs are located.  
Probably also lists things like: the date/version of this distribution,
the web site URL, the egroups address, etc.

- A brief LICENSE file.  It either has a top-level license, or -- what
someone mentioned a few posts ago -- lists the minimum requirements that
covers those sub-libraries that don't have a specific license.  Someone
with legal experience would be helpful here...

- Leave the current "boost" subdirectory as it is.

- Rename the "libs" directory to be "src".  The rationale here is that
"lib" and "libs" tend to imply directories that contain binaries.  The
name "src" (or "source", or "sources", or ...?) pretty much states that
this directory will contain files that need to be compiled.

- Move all .gif, .htm files, and the "more" and "people" subdirectories to
a new subdirectory named "html" (or "www", or "docs", or "www.boost.org",
or ...?).  The rationale here is that the docs don't need to start at the
top-level directory (they clutter up $top_srcdir, IMHO); the README file
can point to wherever they begin.

That should be sufficient for the top-level.  To be completely clear,
here's what I'm talking about:

        $top_srcdir/
           README
           LICENSE
           boost/
           src/    (used to be libs)
           html/   (or some other aesthetically pleasing name :-)

*** "html" (or whatever name) subdirectory

We didn't quite finish this discussion, so I don't have a concrete
recomendation here.  The distro currently includes essentially a mirror of
www.boost.org because it contains the docs for all the classes.  This is
Good -- including the class docs by value should probably be maintained in
one form or another.

I'm also of the opinion that any build documentation can go in this
subdirectory, but there's also the idea that the build documentation
should be outside of the main source distribution.  More on this in a
different post.

There's also the thought that this directory can be used to hold the class
documentation for all the boost libraries.  i.e., get the docs out of the
source code trees and put them up here.  This seems logical to me, but I
don't have strong feelings either way.

As such, the contents of this directory are largely undecided yet.  :-)

*** "boost" subdirectory:

As noted above, there probably isn't any need to change this from the way
that it is now.

*** "src" subdirectory:

This directory mainly holds subdirectories, one for each library in boost
(as it does now).  However, it would seem that there would be some
benefits from standardizing the contents of the individual subdirectories.

Indeed, a few posts ago, I mentioned that BGL was the only sub-library
that had its own license.  Since then, I found that at least regex had its
own as well, "license.txt" -- I didn't initially find it because I only
looked for files named "LICENSE".  I'm not saying that either convention
is Right or Wrong -- I'm saying that one convention should be picked and
used consistently (it almost doesn't matter which).

Having consistency is important and beneficial for reasons such as:

1. A boost sub-library is identifiable as a boost sub-library
2. Developers can navigate each other's work easier if we all work to the
   same standards
3. Makes automated scripts for testing/building/running/whatever easier

As such, each library subdirectory in "src" should probably meet some kind
of minimum requirements, such as:

- an optional LICENSE file (or license.txt, or whatever convention is
picked).  If this file is not here, it is assumed that this library
subscribes to the $top_srcdir/LICENSE (whatever) file.

- an optional README file with any particular notes that the author wants
to put in there.

- a "docs" subdirectory with the HTML docs for that library in it (e.g.,
$top_srcdir/src/timer/docs).  I say make a "docs" subdirectory because
.htm files are usually mixed in with the source files in the current
distribution, which seems to clutter up the source trees (IMHO).  
However, there is also the idea that it would be beneficial to assemble
all the docs files in a single top-level "docs" subdirectory (which can be
part of the top-level "html" directory, as described above, or a separate
top-level directory -- I have no firm opinions here).

- a "src" subdirectory, but only if there are any .cpp files that need to
be compiled for this library.  There is probably no need to standardize
anything below "src" -- a library author should be free to structure their
source code as they feel necessary.

- if there are any example programs, put them in an "examples"
subdirectory.  Again, probably no need to standardize below this.

- a "test" subdirectory for regression test programs.  Again, probably no
need to standardize below this.

Note that it should be permissable for libraries to have other files
and/or subdirectories at their top-level; only the above ones are listed
for purposes of standardization.

Here's a diagram to make it all clear (using "timer" as an example -- the
same structure would be used for all the subdirectories in
$top_srcdir/src):

        $top_srcdir/src/timer
           LICENSE
           README
           docs/
           src/         (only if there are .cpp files for the library)
           examples/    (optional)
           test/
           ... possibly other top-level files and/or subdirs ...

-----

This is certainly not a final design; a few of us came up with this, and
it seemed like a good starting point for discussion.

As always, comments/suggestions are welcome.

{+} Jeff Squyres
{+} squyres_at_[hidden]
{+} Perpetual Obsessive Notre Dame Student Craving Utter Madness
{+} "I came to ND for 4 years and ended up staying for a decade"