Re: [jamboost] Targets and projects update

From: David Abrahams (david.abrahams_at_[hidden])
Date: 2002-05-08 10:21:38

----- Original Message -----
From: "Vladimir Prus" <ghost_at_[hidden]>
To: <jamboost_at_[hidden]>
Sent: Monday, May 06, 2002 4:44 AM
Subject: [jamboost] Targets and projects update

>
> > Update of /cvsroot/boost/boost/tools/build/new
> > In directory usw-pr-cvs1:/tmp/cvs-serv13933/new
> >
> > Modified Files:
> > project-root.jam project.jam targets.jam
> > Log Message:
> > Work on project/targets modules.
> >
> > * new/targets.jam: Considerably changed.
>
> Please take a look at the comments at the top of the file. They describe
the
> targets interaction in some detail. Please also take a look at
> "test/project-test2". It has first occurence of main targets -- so far,
they
> only create a file with build properties, but 'make' rule is not a long
way
> far.

Comments on your comments:

# There are three kinds of targets: "abstract", which correspond to
# targets explicitly defined in Jamfile; "virtual", which correspond
# to possible build product with defined properties and "actual", which
# are targets in Jam sense. The "virtual" targets are generated during
# search for the best transformation sequence, and some of them can be
# later 'actualized'.

...but below you mention a fourth kind: "main" targets.

FWIW, I realize that most Russians have a hard time with articles
("a", "the"), but I needed to add them below to evaluate the
text. After going through and doing that, I was able to clarify it, I
think. Please tell me if you like the changes.

# Actual targets are all derived from 'abstract-target' class. The first
# abstract target is 'project-target', which is created automatically for
each
# Jamfile, and can be obtained by the 'target' rule in the Jamfile's
module
# (see project.jam). Project targets keep a list of 'main-target'
instances.
# A main target is what the user explicitly defines in a Jamfile. It is
possible
# to have several definitions for a main target, for example to have
# different lists of sources for different platforms. So, main targets
# keep a list of variants, which are instances of 'abstract-target'.
# The precise type of variant can be anything

This is unclear. Do you mean to say that variants can be instances of
'abstract-target' or of any of its derived classes?

# -- each rule that declares
# main targets can do anything.

That's quite vague. Anything, really? Why bother mentioning it at all,
then? Doesn't it have to create a main-target?

# However, we'll use only targets derived from 'basic-target' class,

Usually "however" means something like "but", so there should be a
previous phrase which is in opposition to the above. At this point I
don't know *where* you're saying we'll use 'basic-target'
instances. In main targets?

# which will provide some default behaviour. Now, there's only one
# class, 'make-target', which will be create by 'make' rule.

So now I'm thoroughly confused. You appear to have many different types of
target:

abstract
virtual
actual
main
make-
project-

and I don't understand how they fit together.

# Base class for all abstract targets.
# local-name: name of the target in Jamfile
# project: the project module where the target is declared
#
# Note: it might seem that we don't need either name or project at all.
# However, there are places where we really need it. One example is error
# messages which should name problematic targets. Another is setting
correct
# paths for sources and generated files.
rule abstract-target ( local-name : project )

Shouldn't you use Rene's variable-commenting convention above?
So, is local-name really the same as the name of the main target?

Rewriting the comment below...

# Generates virtual targets for this abstract target which match
# 'properties' as closely as possible.

Hmm, what does "as closely as possible" mean?

# If 'properties' are not specified,
# default values are used. If it is not possible to build anything
# due to some problem, returns a list whose first element is "@error"
# and remainder is an error message. (CONSIDER: need some utilities for
# this method of error reporting? 'is-error'?)
rule generate (
properties * # a list of properties
)
{
# Yes, it is empty.
}

Consider calling

errors.error'derived classes must implement \"generate\" method. ;

here.

# FIXME

If you have to do this, please at least write some explanation.

import class : new ;

This is unneeded because of the following from class.jam:

# always bring in the rules defined from this module, so that
# users can easily call "inherit", for example.
import class : * ;

---
if ! $(self.main-target<$(name)>)
Why not just:
if ! $(self.main-target.$(name))
?? I worry about too many grist-y formats dancing around.
In main-target.generate:
1. the trick with "@" is possibly too tricky. It took me a long
time to grok, and at least needs more explanation.
2. It looks like @error messaages are just discarded. Intentional?
If so, say so in a comment.
I tried to answer your questions posed in the comment above
basic-target.generate the other day. Did that work for you? I'm
actually unclear on the relationship of this generate rule to the
search process we came up with in the design process.
I object to the idea of naming a rule "recurse": it just describes an
implementation technique, not what the rule does. Can you do something
more descriptive?
# Class which represents an action.
Putting this comment on a class called "action" has similar
problems. What kind of action (for example)?
> > * new/project.jam: Projects now return project targets via 'target'
> > rule. Requirements are inherited.
These are not all comments on new things, but:
I still think the "module interface summary" should mostly die, since
Rene's doc stuff will produce that for us someday.
The "project" rule has no comment and accepts almost any arguments (with
very generic argument names) that I want to pass. That's confusing!
assign-option likewise needs comments.
The clarification I asked for about the use of __xxx__ names which seem to
be redundant with member attributes here remains unanswered.
> And error message are issued. Please see proejct-test2.py.
>
> > Renames 'subinclude(s)' to
> > 'subproject(s)'.
>
> I find this name to be considerable more logical, while "subinclude" is
> Jambase legacy. If anybody feels strongly about this, speak now.
I feel strongly... that you made the right choice!
> I have a list of tasks that I see as needed. I'll either commit them or
enter
> in the tracker.... but later.
I'll look at the tracker now.
-Dave