Re: [jamboost] main-target-alternative

From: Vladimir Prus (ghost_at_[hidden])
Date: 2002-11-14 07:12:31

David Abrahams wrote:

>>>Whatever's going on in this rule, it's _way_* too tricky. If it _were_
>>>important to do something this tricky, it's at least way
>>>under-commented:
>>
>>Well, I believe we've concluded long ago that writing comments is
>>not my strong point.
> 
> 
> I have great respect for you, but I think that's a bit of a
> cop-out. 

This is a new view on comments for me. And I think it's true!

> It's a skill we all need to develop, and I think you could do
> much better with a little extra attention. You are usually able to
> explain yourself quite well in emails; if you would just write the
> same kinds of things in your code it would be much more
> understandable.

I'll do me best.

>>Let me explain.
>>
>>General scheme for creating main target is:
>>
>>1. You call some rule:
>>
>> exe hello : hello.cpp ;
>>
>>2. It does some preprocessing of requirements and default build.
>>
>>3. That rules creates an instance of some class derived from 'abstract-target'.
>> In this case, it's 'typed-target'.
>>
>>4. It obtains 'project-target' for the current project, and calls 'add-alternative'
>> method on it.
>>
>>What's in step 2?
>>
>>- If there are any path properties, they should be adjusted.
>>- You should refine parent's requirements with target's requirements.
>>- If no default build is specified, then parent's default build is
>> used instead.
>>
>>You see that steps 2 and 4 are not specific to target type, but look at
>>'main-target-alternative' implementation. Those steps take a lot of code,
>>so it's desirable to not repeat them in all rules that declared targets.
>>I agree that the current solution is tricky.
>>
>>
>>
>>>What the heck is "will be specially processed" supposed to indicate to
>>>the reader?
>>
>>Refer to step 2 description above.
> 
> 
> Thanks.
> 
> However, when I post a remark indicating confusion with the
> code/comments, it isn't enough to post a reply which answers the
> questions; you need to clarify the comments in the code.

I prefer to settle the question first. For example, if I switch to
using "adjust" rules, as below, the comments would be different.

>>There are two aspects. First, it's as tricky as 'main-target-alternative' interface.
>>I did make mistakes with it several times myself. I believe we can use a better way:
>>
>>- Introduce three rules:
>> - 'adjust-main-target-requirements'
>> - 'adjust-main-target-use-requirements'
>> - 'adjust-main-target-default-build'
>>
>>- Call those rules as appropriate. This will make all this "3 : 5 : 4" unneeded.
>>You'd write
>>
>> targets.main-target-alternative $(name)
>> [ new typed-target : $(type:U) : $(sources)
>> : [ adjust-main-target-requirements $(requirements) ]
>> : [ adjust-main-target-use-requirements $(use-requirements) ]
>> : [ adjust-main-target-default-build $(default-build) ]
>> ] ;
>>
>>This is more writing but is much more clear
> 
> 
> I think it's a lot better, but I'm not sure why you need to say
> "adjust" here. What do these adjust-xxx rules return?

They return main target requirements, main target use requirements
and main target default build. I now see that "adjust" is not needed.
(Hmm.. I have to reread your Boost conding guidelines, I remember they
had a section on naming).

I'll change everything according to this scheme later today.

- Volodya