Re: [jamboost] Targets and projects update

From: Vladimir Prus (ghost_at_[hidden])
Date: 2002-05-11 07:37:32

David Abrahams wrote:

> > Please take a look at the comments at the top of the file. They describe
> 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.

Yes, those three kinds are "top-level" kinds. Main target is just a kind of 
'abstract-target'.

> 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.

Yes, I like them. I'll apply them later.

> # 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?

Any instance of 'abstract-target'.

> # -- 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?

Well, what is actually meant "the rule that is used for declaring main target 
determines what class to use for a variant. It creates an instance of that 
class and adds them to the list of main targets' variants".

> # 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?

I mean that althought variants of main target can be any class derived from 
'abstract-target', we'll use only classes derived from 'basic-target'. I.e. 
every rule that defines a main target will create an instance of some class 
derived from 'basic-target'. For example, 
test/project-test2/project-test2.jam, in rule main-target creates an instance 
of 'main-target-class', which derives from 'basic-target'.

> # 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.

I'll try to clarify. There are abstract, virtual and actual targets, which 
definitions are given at the top of the file.

Abstract targets form a long hierarchy. First, there are
project-targets, they are just containers for main targets.
Main-targets, also derived from abstract-target, are just containers for 
variants, which are derived from 'abstract-target'. Classes that will be used 
for variants are actually the most important. There's class with common 
functionality 'basic-target' and I plan to have two derived classes.

First, 'make-target' will correspond to 'make' rule invocation. Second, 
'typed-target' will correspond to rules such as "exe", "lib", etc. where the 
target type is defined.

Maybe it would be better to describe how tagets will be generated.

1. A 'project-target' for project in "." is retrived and its 'generate' rule 
is called.
2. For all main targets and for all subproject, call they 'generate' rules
3. In each main targets, 'generate' rule for each variant is called. Now only 
one can return non-empty list of virtual targets.
4. Class for main target variant can do anything in general, but those 
derived from 'basic-target' will: 
- refine required properties with requirements
- build source targets
- call 'construct' rule that will be declared in the most derived class

> # 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?

I should.

> So, is local-name really the same as the name of the main target?

Yes. I used this name for variable because of mental connection with 
'declare-local-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?

Oh... We need to decide this. If user gives some build request, are there any 
constaints on what properties can be used for building, except that they must 
be link compatible with the requested ones? 

> # 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.

Agreed. 

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

This means "should remove the following line".

> 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 : * ;

Welll.... but when I comment that line out, project-test2.py fails! Shouldnt' 
the fragment you quote be moved to the 'instance' rule?

>
> if ! $(self.main-target<$(name)>)
>
> Why not just:
>
> if ! $(self.main-target.$(name))
>
> ?? I worry about too many grist-y formats dancing around.

Agreed.

> 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.

The actual problem is that we seem to need a list where each element can be 
list itself. How do we implement that?

> 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.

Oops! I though I've responded that email of yours, but I don't see that 
message either in sent or in drafts. While I'm looking for it, it's enough to 
say that I'm unclear the relationship either.... so this rule might need 
change when we start implementing generators.

> 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?

'generate-source' is what I came up with.

> # 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.

Like the one in project.jam? Yes.

> 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.

You are right in these points and I hope to address them soon.

> > 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!

:-)

- Volodya