Re: [jamboost] Re: Refactoring progress report

From: Ali Azarbayejani (ali_at_[hidden])
Date: 2003-05-12 10:29:07

David Abrahams wrote:
> 
> Rene Rivera <grafik666_at_[hidden]> writes:
> 
> Much appreciated.

Ditto.

First, apologies to David for misrepresenting a couple of points.
Thanks for clarifying. Also, David pretty much answered the
questions...
I'll just add a couple clarifying points...

> >>o Refactoring feature.jam, property.jam
> >
> > [snip]
> >
> > Yea better names are good ;->
> >
> >>o Refactoring classes
> >>
> >> We propose that each class have its own file.
> >>
> >> This will have implications for module dependencies, because current
> >> implementations are rather sloppy about what depends on what.
> >> Classes depend on functions in the module they exist in and other
> >> functions in the module depend on the class. These circular
> >> dependencies are probably not necessary. Re-factoring will
> >> highlight more clearly where circular dependencies exist. Trying to
> >> eliminate circular dependencies will probably lead to a clearer
> >> design and better concepts.
> >
> > I just don't see how this will be all that beneficial, but again I
> > haven't looked at code as much as others. Just having good names for
> > classes would go a long way. But the general idea of less classes
> > per file seems like it would help in clarifying interfaces.
> 
> Yeah, I agree on all counts. I was a little surprised to read that I
> was proposing a "one file per class rule" ;-), though I think it's
> probably a very good idea in most cases.
> 
> I think Ali was probably confused about a different suggestion I made,
> which was that it feels like there might be some advantage to having a
> way of defining modules which act like classes in and of themselves.
> But it was a vague suggestion.

A number of times both of us expressed displeasure and confusion with
the number of classes that were embedded in targets.jam
(abstract-target, project-target, main-target, basic-target,
typed-target) and virtual-target.jam (virtual-target,
abstract-file-target, file-target, action) and I believe we both
thought it would be better if some or all of these classes were in
their own files. I guess I was too bold in extending that thought to
one-class-per-file, in general.

As in C++, I don't think it should be a requirement, and should be
violated when appropriate, but it is usually good style and good
modularization. I believe it will help elucidate (along with a
stricter modules.import) the design and interaction of classes not
only to readers, but also to implementors.

It's true, I only vaguely remember the module/class suggestion, but
the above proposal simply stemmed from a generalization of our desire to
break particular classes out into their own files.

> >>o Project-root/Jamfile
> >>
> >> The requirement of having a "project-root.jam" file in addition to a
> >> "Jamfile" for every project means that each simple single-Jamfile
> >> project requires an additional file.
> >
> > Not true. The only requirement is that there be at least "one"
> > project-root.jam. For example boost should only have one
> >>project-root.jam...

My point was you can't have
simple projects with just the Jamfile. Compare to "make"...all the
simple things for simple projects that you can do with "make"
shouldn't be hard or more complicated to do in Jam/BBv2. One of these
simple things is creating a single build description file to build a
simple program.

> > At the logical BOOST_ROOT/project-root.jam.
> 
> Yes, that's precisely what we're saying. Ali's usage model is not one
> which needs or wants subprojects most of the time, and the arrangement
> where each project can stand on its own is a very important model.

Yes. Most software modules of mine stand on their own or can be part
of a bigger tree (or many different trees). So each module must be a
project in its own right and by the current implementation requires
not only a Jamfile but also its own project-root.jam. This is
annoying.

> >> In fact, the Jamfile is the unnecessary one of the two, which leads
> >> us to propose that the file performing the function of the current
> >> "project-root.jam" be called "Jamfile", allowing simple projects to
> >> exist with a single Jamfile.
> 
> Actually, I'm surprised again. I talked about this idea and one other
> with Volodya, and agreed that the other idea was the one to go with
> [see below **]. I talked this over with Ali, but maybe our wires got
> crossed.

[snip]

> ** The "right" approach, IMO, is to allow project-root.jam to fulfill
> the functions of a top-level Jamfile if no such Jamfile exists. I'm
> not sure how much infrastructure is required to implement that; maybe
> it already works (though I doubt it).

Sorry, again, that I didn't express this very well, but I was trying
to express exactly this last idea with the addition that, if this is
the solution to my problem, we might want to change the name of
"project-root.jam" to something else.

(1) "project-root.jam" doesn't look as much like a "Makefile" as does
"Jamfile". A user transitioning from "make" (i.e. virtually
everyone), or even earlier versions of Jam, will assume that
"Jamfile" is what they should be writing for their simple
single-directory project, not "project-root.jam".

(2) Currently there is a build-system file called "project-root.jam"
(boost/tools/build/new/project-root.jam), which in fact is not a
model of the "project-root.jam" that you put at the root of your
project (cf. "new/boost-build.jam" is a model of a user's
"boost-build.jam", "new/user-config.jam" is a model of a user's
"user-config.jam", etc). Hopefully, a new directory organization
and some re-naming will solve these particular confusions, but in
general it seems to me that the "project-root.jam" file serves a
purpose much more associated with "Jamfile" than with *.jam in the
build system. Therefore it is confusing that it looks like a .jam
file rather than looking like a build description file with a name
like "Jamroot" or some such thing. The two files "project-root.jam"
and "Jamfile" work together to provide the build description and they
should look like they work together. (Perhaps "project-root.jam" and
"subproject.jam"?...I don't care so much about the naming as the fact
that it should be clear that these files work together and that it
should be possible to create a stand-alone, single-directory
project with single build description file that builds a simple
program
or library or whatever).

--Ali