Boost logo

Boost :

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 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
> 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 unzips itself into the current directory (.) --
> into a subdirectory. This is typically considered fairly anti-
> behavior. Indeed, I unzipped 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

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 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 extract to its own
> 2. I see ./libs/ in the extracted stuff. Looks
like some
> CVS kruft.
> --> RECOMENDATION: Remove ./libs/
> 3. There's no makefiles. I initially thought that was weird, but
> realized that there is no portable way to make C++ librarie. So I
> have a specific question/recomendation here, but it leads into my
> 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,
> 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

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
> This might be a somewhat picky request, but a lot of users expect
> kind README/INSTALL/something file. Indeed, the index.htm in the
> top-level directory is just a copy of'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
> 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
> Granted, a user can put the "boost" subdirectory in some central
> 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
> 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
> some boost library. Heck, even a minimal Makefile with "INSERT YOUR
> 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
> 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
> it is very handy to have the directory (or some file in that
> directory) say what version it is. Indeed, if you have
> 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
> remember what version they initially downloaded. GNU has
> more-or-less standardized the "name-number" directory name
> such as "boost-1.0.3".
> d. When extracting from the distribution, it is social to not
> an old [and presumably working] installation. i.e., as a
> 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
> 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 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

Boost list run by bdawes at, gregod at, cpdaniel at, john at