Re: [jamboost] Re: target references

From: Vladimir Prus (ghost_at_[hidden])
Date: 2004-07-15 07:07:41

David Abrahams wrote:

> Why don't you write up the summary again with the correction and we
> can look at it afresh?

Here it goes:

0. Target-reference refers either to file or a target in some project. The 
decision is made syntantically. If targer reference has "//" in it, it refers 
to a target, otherwise it refers to a file

1 Target reference which refers to file is interpreted as file name relative 
to the source directory of the project where target reference is used.

2. Target reference which refers to target constists of two parts. The part 
after "//" names a target in Jamfile. The part before "//" identifies a 
project.

2.1 2.1 The name of a target should be exactly the name specified in
project referred by the part before "//"

2.2. The part before "//" can identify a project in two ways: by specifying 
directory of Jamfile, or by specifying symbolic project id. There's no 
syntantic differences between those two ways: we first look if project with 
such id exists. If not, we interpret the part before "//" as path to Jamfile.

Project ids are assigned by calling the 'project' rule in Jamfile, passing the 
project id as the first argument. The project ids are always absolute, 
e.g. /boost/python

> >> > 2.2. The part before "//" can identify a project in two ways: by
> >> > specifying directory of Jamfile, or by specifying project id
> >> > previously passed to the invocation of the 'project' rule. There's no
> >> > syntantic differences between those two ways: we first look if project
> >> > with such id exists. If not, we interpret the part before "//" as path
> >> > to Jamfile.
> >>
> >> So project ids are always absolute?
> >
> > Yes.
>
> Then the leading slash is redundant :(

Yea. The question is if we want to just remove the leading slash, or allow 
relative project ids. The latter approach seems better -- while I never 
lacked relative ids much they would make the syntax more "complete".

> >> > I hope I've specified everything. If not, let me know and I'll
> >> > fill the holes.
> >>
> >> How do project ids get assigned?
> >
> > It's assigned when Jamfile calls the 'project' rule. The id passed
> > to the 'project' rule should be always absolute.
>
> Seems like it makes more work in explicitly specifying project ids
> than it should have to, and allows for possibly-confusing errors, like
> a sub-project of /boost named /boast/foo

We sure can make declaring ids relative to parent work. I might do it rather 
quickly if we decide it's needed (though I might decide to refactor 
project.jam at the same time)

OTOH, in either case 'use-project' would need full id if you want to refer to 
specific project.

use-project /boost/python : some-path

> > I see. But those users sent a lot of complaints in other areas, so
> > I'm not sure they'd not mention target id is they were very
> > confusing.
>
> People who "just want to get something done" will accept and
> repeatedly apply a pattern without really understanding it. Not
> everyone can work that way... especially if they're trying to write
> documentation ;-). I hope you agree that someone needs to write the
> rules down in the docs. If the rules are too complicated to
> understand, the docs will confuse people.

Yes, I understand. I think we have two tasks: clarifying the current rules and 
figuring out how they could be improved. I think I've confused those tasks in 
my reply.

> > Anyway, what I'm really trying to do (besides deciding on the right
> > syntax), is avoid asking the users to update Jamfiles once again, so
> > probably we need to support existing syntax (maybe even without
> > docs) for quite some time.
>
> Yes, I was thinking the same thing. We could probably add a
> command-line option that updates Jamfiles automatically ;-)

That would be cool, though maybe hard.

> > In some sense you need to somehow refer to all sub-projects from
> > top-level Jamfile. For example, when installing you need the list of all
> > libraries. In V1, that list is computed via GLOB magic -- which V2 can do
> > as well -- but we still need the list of all libraries. And we we have
> > it, we can load Jamfiles.
>
> I understand... but do you think that's a good idea? If there were
> some rules for searching based on project path it would reduce the
> burden of project maintenance and the chance of error.

What is good idea? Implementing automatic search for library Jamfiles like V1 
install does. Yes, I think this is reasonable and we should do it.

> Maybe it was Ali. I distinctly remember discussing the idea that an
> existing "top-level" project could be moved into another project as a
> sub-project.
>
> > In fact, because some requirements are inherited from Boost Jamfile,
> > moving one project is not possible.
>
> Maybe not in the case of Boost, but perhaps in general?

I suspect that having project-wide requriements in top-level Jamfile is likely 
to be general practice. At least that's what I do in my project, and Jurgen's 
testcases (which, I believe, are based on his project), show the same.

>
> > Likewise, I did not plan that -- or rather, did not though -- about
>
> ^^^^^^
> "think"?

Yes.

> > That never was implemented, though I don't know why -- now it seems
> > straight-forward task.
>
> Right now a top-level project needs to name each of its subprojects,
> and each subproject needs to name itself. I think it would be
> valuable to reduce the amount of redundancy in the system.

In general, top-level project need to name subproject only if it want them to 
be automatically build when you build top-level project. This is common 
behaviour, so maybe the rule to find and subprojects (needed for "install"), 
can have general utility.

But I believe it's possible to want to build only *some* subprojects, so we 
need to retain explicit control.

I'm thinking that some rule like:

build-subprojects ;

which will find of subprojects and call 'build-project' on them will be handy.

- Volodya