Re: New boost user

From: William Kempf (sirwillard_at_[hidden])
Date: 2000-10-04 14:29:40

--- In boost_at_[hidden], Jeff Squyres <jsquyres_at_l...> wrote:
> 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... :-)

I'm fairly new myself, so some of what I say is guess work (though 
logical).  Others will likely correct me where I'm wrong.

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

Actually, I've never seen a trend one way or another to 
indicate "anti-social behavior".  In fact, I personally hate zip 
files that create a subdirectory.  I *always* create the directory 
myself, unzip there, and in the (about 50%) cases where it created 
another subdirectory underneath mine I copy the stuff back.

That said, the VAST majority of stuff in the boost_all.zip does go to 
numerous subdirectories.  In the root you get a sum total of 4 
files... all html documentation files.  I personally don't think this 
is a problem or needs changing.
 
> --> 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.  :-)

Initially there was little need for makefiles.  The vast majority of 
Boost was template header files, so there was nothing to "make".  
With the recent additions of Regex and BGL things have changed 
dramatically.  Unfortunately the "solution" isn't very easy to come 
up with here.  People are looking into the issue for both short term 
solutions (so far there's been talk on the list, but little in the 
way of actual solutions) and long term (waiting on Software 
Carpentry, as you said).
 
> 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."

I think that Index.html suffices for this.  I see no need for a 
README file in addition, though there could be some changes made to 
index.html to address some of your issues about the lack of README 
here.
 
> 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.

It does give such information.  The very first link is to "libraries" 
which details this info.
 
> What I'm getting at is that there is no guidence on how to use the
> libraries at all.

The library documentation discusses this.  What's really lacking is 
documentation on how to build those libraries that require some 
building.  Until we've got a portable way of doing this, it seems 
like something very difficult to do ;).

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

Again, useage was intuitive until Regex and BGL.  I believe the 
submitters of these are looking into this, though there's no easy 
answer.
 
> 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)?

For the most part that's all test harness code.  It has little to do 
with useage of the libraries.  The one exception that I'm aware of is 
the Regex stuff... which is documented in a README within that 
directory.  Not necessarily intuitive, I agree, but it is documented.

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

It's simply not that simple, even on *nix systems ;).  That's why 
*nix relies so heavily on autoconf et. al.
 
> --> 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.

I agree with the concept.  With the use of CVS the only thing that 
makes sense is to use RCS tags within comments in the source files.  
Version management goes well beyond just "did I instal version 1.18?" 
for many people who grab snapshots of work in progress, after all.  
The RCS tags can also be placed in the HTML file. 

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

Documented in boost/more/lib_guide.htm#License.  Each submission may 
have it's own liscensing (that's why you find a LICENSE file in 
libs/graph) but said licensing must abide by Boost restrictions, 
which includes the ability to be used in closed-source proprietary 
commercial 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.  

Well, Boost is attempting to develop libraries for the next 
generation of C++, so there's a reason for that bias, though I'd 
agree that it should be better than it is today.
 
> None of this is intended to be inflamatory; it's all IMHO.
> Comments/suggestions would be appreciated.

I agree that it could be more "user friendly", but if you explore 
what's there you'll find that most of what you think is missing is 
actually there.  I agree that Boost has gotten to a size where it 
needs to be easier to find this information lest users give up in the 
frustration of trying to find the proverbial needle in the haystack.  
This is a new phase for Boost, IMHO, and I expect that people will be 
addressing these issues shortly.  After all, not only has Boost 
recently more than doubled in size but it's user base has also 
recently undergone a very large growth.  Both because of the 
additions of Regex and BGL.

Bill Kempf