Re: [boost] New boost user

From: Jeff Squyres (jsquyres_at_[hidden])
Date: 2000-10-13 18:44:38

I appologize for taking so long to reply; I'm fighting deadlines of my
"real" work.  :-)

On Mon, 9 Oct 2000, Beman Dawes wrote:

> There are some requirements which may not be obvious to everyone:
> 
> * The web site, CVS repository, distribution file (.zip), and internal
> web site tool (FrontPage) directory structures must be the same.  
> This allows internal processes (like updating the web site, creating
> the .zip file, backups, and various CVS operations) to work
> automatically.  This also allows anyone to mirror the site (as some
> already do on their internal LAN's) simply by loading and unzipping
> the distribution file.

A model that we have found to be useful here in our lab is to keep our
source code and web trees separate, but have the web tree refer into the
source code tree where appropriate (i.e., if you want to link directly to
the source code).

That is, we have separate CVS modules for our web pages and source trees.
Hence, we publish the two trees differently (and separately).  Keeping
them separate allows us to do several nice things:

Those who wish to mirror our web site use tools like wget, mirrordir, etc.  
This typically also grabs source distribution, too, so a web mirror still
ends up with everything.  The web site rarely needs any automated updating
-- all updates are done manually anyway (we use PHP heavily, so things
like changing the version number is trivial -- just change on top-level
PHP include file.  Note that mirrors only get the output HTML, so there's
no need for them to support PHP, for example).  The only automated changes
are "cvs update" in the "live" checkout directories.

The source code distribution can include a full/partial copy of the web
site in order to get the docs and any other information that's on the web
-- a tar or cp can place an expanded copy in the distribution tree before
archiving it up.  Any automated updates can run over the entire source
code with impunity (e.g., creating a distribution).

This is what works for us.  I'm not saying that it's right for boost
(indeed, I'm quite new to the boost community, so it certainly isn't my
place to demand change! ;-), I'm just describing a different model that
works for us (i.e., keeping the web and development trees separate).

> * Web site size is a factor; that's why we don't post boost_all as
> both .zip and .gz files.  If I can ever get a faster connection,
> particularly an "always on" one, that may change.

No problem.  We unixy people prefer .tar.gz (and many prefer .tar.bz2,
too), but as long as the distribution is available in some form or
another, it doesn't matter too much.

> * While we can and will improve the end user's experience, we can't do
> that at the expense of alienating developers. CVS is bad enough.

Agreed; CVS can be your friend, but CVS can also be your enemy.  :-)

> > [README stuff]
> 
> I think we should stick to HTML as our documentation format.  If we
> add a readme file, it should be totally static and just point people
> to the HTML.  The HTML should already include all of the information
> you mention above.  A readme file which has to change each
> distribution will be a maintenance headache.  We certainly could add a
> readme file that says:
> 
> "For access to all documentation, view index.htm in this directory
> with a web browser program such as Netscape Navigator or Internet
> Explorer."

Sounds good -- a short README file with a pointer to the HTML docs would
be great.

Can we add a bit more, though?  Some hints/guidence about how to build/use
boost?  Or even the directory layout (which isn't likely to change often,
so it won't require too much maintenance), or something?  i.e., we don't
quite want to tackle building boost yet (i.e., the whole
building-a-C++-library portability issue), but *some* guidence --
particularly for new users -- would be good.

>  >- 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...
> 
> Yes, we really could use some help.  Does ND have a law school?

Ugh.  Getting licenses from the ND general counsel for our own software
was painful enough (it took *forever*).  I shrudder to think what they
would do for a software project that originated mostly outside of
nd.edu...  :-(

>  >- 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.
> 
> We need to think about that some more.  Ed Brey's point about being
> able to select a directory for CVS updates is important.

True.  But this model is already broken with the "boost" subdirectory,
isn't it?  i.e., all the .hpp files for a given library are in a different
subtree than implementation, example, and/or test programs.  Hence, if you
want to update just one directory (in the current CVS structure), you can
update just that directory under libs/, but then probably have to update
individual files under boost/ (assuming you don't want to update the rest
of the libraries, for some reason).

If src/timer/src is confusing, how about sources/timer/src?  Or something
else?  I think that I just object to the name "libs", since it tends to
imply that binary files are in there.  Just my $0.02.
 
> Anyhow, thanks for the suggestions!  I want to go back and read the
> CONS docs and the ScCons proposal.  Because they are not as limited as
> make, we may be worrying unnecessarily about some of these directory
> issues.  For example, people won't have such high expectations for
> seeing src and libs directories if they see the high level ScCons file
> in the top level directory.

In terms of building, yes.  But in terms of tooling around in the
directories while trolling through the source, I think it is still
important to have standardized directory/file names to make things easy to
find.  The Law of Least Astonishment applies here; using well-known
standardized named would help new boost users, particularly since there is
not likely to be any kind of build system in boost any time soon.

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