Re: [jamboost] Bugs/Moratorium

From: David Abrahams (david.abrahams_at_[hidden])
Date: 2002-03-26 19:33:51

----- Original Message -----
From: "Rene Rivera" <grafik666_at_[hidden]>
> >Vladimir wrote a snazzy
> >python testing system but I never got around to trying to use it.
We'd
> >need a dummy toolset definition for testing purposes. All it would
have
> >to do is echo or cat some simple data into files.
>
> Great! Is that the *.py files in tools/build/test? And I'd be willing
to add
> some of the test cases I've had to write when encountering bugs.

I hope that he and Steve K. will work out the "perfect" build system
testing environment. Wait a coupla days for their conversation to settle
down, I suggest.

> >What do you think needs to be covered in the top-level docs which
> >currently isn't?
>
> What I'd like to see is a better division between documentation for
users of
> Boost.Build, and the rest of the documentation.

Agreed.

> Since I was looking at the docs tonight here are some things that I
saw...
>
> - Even though we document description of main targets, we don't really
> document the various main targets that are possible.One description
for all of
> them doesn't cut it from a users point of view.
>
> - There are a few non main targets we don't describe. "unit-test" is
one, and
> is one that I was unaware of for some time. That's the most glaring
and there
> are probably others I don't know.

That one's really provisional. It should be replaced with the "run" rule
from status/Jamfile. Someone (Joerg) was going to break out the
functionality of status/Jamfile so it could be re-used, but I think he
got discouraged.

> - All the python targets, pyd, testing, etc. aren't documented, as far
as I
> can tell.

Yeah; that's partly because it's a bit messy. The Python testing code,
again, ought to be integrated with what's in status/Jamfile, but right
now it's working for me and I don't want to rock the boat while we do
v2.

> - We describe what features and, briefly, properties are. But we don't
> describe what they all are and what effect they have. The only thing
we do is
> point to the features.jam, which is in no way documented.

True. That's a bigger problem, too. How will features get added to the
system? They may creep in from various toolset/platform/library support
files. In a modular system, how do you document those components?

> - This applies only to V1, but we certainly lack in describing even
the
> minimal set of variables we have to set in order to get Boost to
build. And
> therefore aren't even close to documenting what all the various
variables one
> can set to change the behavior of things. Ones that immediately come
to mind
> are GCC*, STLPORT*, and PYTHON*.

I completely agree; however, we could spend weeks documenting all this
stuff which is going to be thrown out (soon, I hope!)

> >From both a user and developer viewpoint what I'd like to see is
documentation
> divided into three audiences: users, programmers, developers.
>
> Users are those writing their own Jamfiles, and nothing else. This
group needs
> a good description of all the possible constructs the can make use of
and how
------------------------^^^^^^^^^^^^^^^^^^^^^^^^^^^
> the work from a production aspect. I consider this the cause and
effect
> viewpoint, they have an intended effect and want to know the cause so
they can
> make use of it.

I think that's a tall order. As you know, the constructs are limitless,
because users can start programming. What we /can/ do for users is show
them the basic usage, and tell them that supplied modules (e.g. for
STLPort support) will add their own capabilities. It would be worth
having a way to get help from the command-line:

bjam --help-stlport

to dump information about how to use the stlport module.

> Programmers are users that are supporting either an extended
Boost.Build
> system or a custom one using Boost.Jam. They want to know some of the
> internals of the system, but usually just enough to get their stuff
working.
> For example they would not be interested in the v2 architecture doc,
but would
> be interested in the "Internals" doc section we currently have.

Good.

> Developers, that's us, are the ones doing the base coding. We need to
know
> everything, but we also don't need info to be totally digested to make
use of
> it. Also in this group would be anyone providing patches to new
features
> they've implemented.
>
> I know that's a lot, and that few of us like writing documentation but
we have
> to do it eventually.

Totally agreed.

> I'm not suggesting we do this now, that would be just
> very bad

Not even extremely bad? ;-)

> , but thinking about it at minimum. And at best coming up with a
> structure for the documentation would be good.
>
> And lastly, I think testing and docs are parallel tasks. If we are
testing
> something we should be documenting that something.

I'm ready to start doing that.

-Dave