Re: [jamboost] Further development

From: Vladimir Prus (ghost_at_[hidden])
Date: 2002-07-08 05:41:44

David Abrahams wrote:

> OK, I have accepted the task, and I have some questions:
>
> 1. targets.jam says:
>
> # 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'.
> #
> # Actual targets are all derived from 'abstract-target' class.
>
> Whoa, I'm confused! First you say that there are these three distinct
> categories... in particular, that "abstract" targets and "actual" targets
> are not the same thing, but then you go on to say that "actual" targets are
> derived from "abstract" targets. Am I to take it that an "actual" target
> is-a "abstract" target -- IOW, does an "actual" target ALSO correspond to a
> target explicitly defiend in a Jamfile? That would be very strange.

True, that phrase had no sense at all. Corrected.

> I can only imagine that you mean something different by "Actual" as used at
> the beginning of the sentence, or that class "abstract-target" has no
> correspondence to the category of "abstract" targets you're describing.
> Either way, something needs to be clarified/renamed/reworded here. Are you
> sure you don't mean for the first kind of target to be called "main"?

I don't think so. I see a similarity between projects, main targets and main 
targets alternatives. They all correspond to user-defined entities and all 
can be build, yielding a set of virtual targets.

> 2. What is the meaning of main-target.add-variant? Is this a different
> meaning of "variant" than "debug/release"? Oh, I see that explained
> somewhat in the comment at the beginning. I would prefer to pick a
> different name; this overloaded meaning is confusing. I also don't
> understand how these "other variants" will actually get created.

The preliminary user docs I'm secretly writing use "alternative" to mean the 
same. As for their creating: you can have

exe a.exe : a.cpp : <toolset>gcc ;
exe a.cpp : b.cpp ; 

Which would create two alternatives for main target 'a.exe'. The first one 
will be used to the gcc toolset and the other for all other toolsets.

> 3. The comment on main-target.generate isn't a sentence. I can't understand
> what it means:
> # Select a variant return virtual targets that it generates
> rule generate ( properties * )

Clarified.

> 4. You write:
> > it is required that after building every main target, the
> > project target that cause the build
>
> What does it mean for a project target to "cause the build" of a main
> target?
> I guess you mean what it does in its "main-target" method?

Not exactly. I was thinking that main-target.generate computes a list of 
virtual targets for it. Then we need to compare free properties for each 
virtual target with free properties for the main target's project to decide 
if new element should be added to subvariant identifier. 

I originally thought that you can do that in 'project-target.generate', but. 
this is not true, because main targets may be generated during generation of 
other main targets. For example:

make a.exe : a.obj @/boost/c.obj : yfc-compile ;

There, main target corresponding to c.obj will be found and its 'generate' 
rule will be called, but it will happen inside the 'generate' rule for 
'a.exe'. It means that we should compare project's free properties with 
virtual-target's free properties inside 'main-target.generate'. Since 
'main-target' keeps a reference to project it should be quite possible.

Hint: to find all the properties with which a virtual target will be 
generated, you can first get the action for that target, and then call 
'properties' rule for the action.

> > compare free properties
> > for all virtual targets
>
> How do I find "all virtual targets"?

At the place where 'main-target.generate' is going to return all the virtual 
target for it, you have that list readily available.

> > with free properties in its requirements.
>
> Obviously, I still find targets.jam somewhat bewildering. I'm happy to look
> through the code, but it's hard for me to understand the comments. Maybe
> another
> pass through the comments to try to clarify your intention would be
> helpful. Even redundancies like:
>
> # So, main targets
> # keep a list of variants, which are instances of 'abstract-target'.
> #
> # Each variant is an instance of 'abstract-target'.
>
> tend to get in the way of comprehensibility. 

I'll make another pass through the docs. However, you probably know the 
problem that once any text is written and read several times by the author, 
bugs and poor wording tend to become familiar and hard to find :-)

> I still want to see an inheritance diagram.

I'm preparing an UML diagam right now.

- Volodya