New boost user

From: Jeff Squyres (jsquyres_at_[hidden])
Date: 2000-10-04 13:39:40

Greetings.

I was introduced to boost from my labmates Jeremy Siek and Rich Lee.

I thought that several of the libraries in boost would be able to help out
in my work (including GGCL :-), so today I downloaded boost_all.zip.  I
was surprised by a few things; Jeremy and Rich told me to post to the list
to ask about them.  I did a quick check through the mail archives and
didn't see anything about this; forgive me if this has already been
covered -- please point me in the right direction and I'll go read... :-)

------

1. The boost_all.zip unzips itself into the current directory (.) -- not
into a subdirectory.  This is typically considered fairly anti-social
behavior.  Indeed, I unzipped boost_all.zip in one of my source
directories, realized what happened, grumbled about it, and then had to
move all the extracted files and directories into their own subdirectory.

--> RECOMENDATION: Have boost_all.zip extract to its own subdirectory.

2. I see ./libs/.#regrtest.py.1.5 in the extracted stuff.  Looks like some
CVS kruft.

--> RECOMENDATION: Remove ./libs/.#regrtest.py.1.5

3. There's no makefiles.  I initially thought that was weird, but then
realized that there is no portable way to make C++ librarie.  So I don't
have a specific question/recomendation here, but it leads into my next
point.

--> RECOMENDATION: Hope that Software Carpentry solves this issue.  :-)

4. There's no README kinds of files.  There's some HTML files, including
documentation of all the classes, but no plain text stuff.  A minimal file
would be sufficient, something like "This is the boost distribution.  For
more information, see the boost web site and the included HTML files."

This might be a somewhat picky request, but a lot of users expect some
kind README/INSTALL/something file.  Indeed, the index.htm in the
top-level directory is just a copy of www.boost.org's top-level page -- it
doesn't give any information on what is included in the distribution, etc.

What I'm getting at is that there is no guidence on how to use the
libraries at all.  Given that the boost group peer reviews just about
every single line in a given library, there is a *lot* of thought devoted
to everything about how the library *works*.  But there doesn't seem to be
any [publicly available] material on how to *use* the libraries.

Granted, a user can put the "boost" subdirectory in some central include
directory somewhere, but what about all the .cpp files (i.e., most of the
stuff under libs)?  Is a user expected to copy these into every source
code tree that they want to use them with (I would assume no, because that
would kinda defeat the point of centralized/reusable code)?  What's the
intent here?

Note that I am not talking about the example and test suite programs --
I'm talking about a "hello world" that Joe User wants to write that uses
some boost library.  Heck, even a minimal Makefile with "INSERT YOUR
COMPILER HERE" and "INSERT YOUR CXXFLAGS HERE" would be great (I don't
know what to say for Windows users -- I'm not a Windows developer)

--> RECOMENDATION: Add some README and/or example usage files describing
    how to use the boost libraries.

5. There does not appear to be a version number anywhere in boost.  
Version numbers are good for multiple reasons:

   a. They are very handy for end-users who don't follow the active
      development of a product -- they can easily tell when they need to
      download the next release.
   b. When you have multiple copies of a product installed in your tree,
      it is very handy to have the directory (or some file in that
      directory) say what version it is.  Indeed, if you have multiple
      copies, how are you to know which one to use?  Which one is "the
      latest version"?  (This is really only relevant if the
      "libs" subdirectory isn't meant to be centralized, and everyone has
      their own copy)
   c. Chances are that the sysadmin or end user who installed boost won't
      remember what version they initially downloaded.  GNU has
      more-or-less standardized the "name-number" directory name notation,
      such as "boost-1.0.3".
   d. When extracting from the distribution, it is social to not overlay
      an old [and presumably working] installation.  i.e., as a sysadmin,
      I would want to install boost in a non-default directory first, test
      it out, and then make it the default only after I am sure that it
      works.

--> RECOMENDATION: Add some kind of version number into boost.

6. There also seems to be a general lack of LICENSE kinds of files.  The
only one that I see is in libs/graph/LICENSE.  Does that apply to just
GGCL (I think it does) or to all of boost?  What about the licensing of
the rest of boost?  For example, can boost be used in closed-source,
proprietary code?

--> RECOMENDATION: Add some license verbage that says who is allowed to
    use boost, and for what.

-----

All in all, it seems if boost_all.zip is oriented towards boost
developers, not end users.  

None of this is intended to be inflamatory; it's all IMHO.
Comments/suggestions would be appreciated.

Thanks for your time.

{+} 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"