Re: [jamboost] Re: RFC: Fixing project-ids and use-project

From: Vladimir Prus (ghost_at_[hidden])
Date: 2005-01-18 03:55:37

On Monday 17 January 2005 22:23, David Abrahams wrote:
> Vladimir Prus <ghost_at_[hidden]> writes:
> > I'm trying the clean up doc areas when Dave marked as problematic,
> > and is stuck because I can't reasonably explain the current
> > behaviour of project-ids and use-project. I think it's a sign that
> > we really need to fix them up.
> >
> > How, I'm unsure how to fix theml without breaking every existing
> > project
>
> That may not be so terrible ;-)

This may not be terrible, if we can do it only once. So I'd rather be careful 
with changes, so that we don't break all projects every week.

> > so I'd appreciate some help:
> >
> > Use case 1 ("external project"). I want to use C++ Boost. I'd expect
> > to write
> >
> > use-project /home/ghost/boost/cvs ;
> >
> > and then have convenient ids for all boost libraries.
>
> That's good, but for what it's worth, I don't think it would be an
> unreasonable burden to ask users to specify the "local" project ID
> (the one that can be used in the specifying project and all
> subprojects) in use-project:
>
> use-project boost : /home/ghost/boost/cvs ;

Actually, I was stuck trying to describe why you need to specify project id 
both in 'use-project' and in the referred project.

> > Use case 2 ("internal project"). I want to use project id to refer to
> > some directory inside my project, to protect against directory
> > reorganisation.
>
> use-project internal-project-id : some/relative/path ;
>
> > Use case 3 ("aliases"). I want to use two different project id for the
> > same project. Or, I want two use two different project ids for two
> > different project, even if they define the same project id.
>
> use-project project-id-1 : some/relative/path ;
> use-project project-id-2 : some/relative/path ;
>

> > But then we have:
> > Question 1. Should there be any meaning of "relative" project ids. Now,
> > all ids start with "/". If ids can be local, it's reasonable to drop "/"
> > from them. But that would require updating of all Jamfiles, which is not
> > desirable.
>
> I don't understand. The fact that dropping the leading "/" is allowed
> doesn't make it required. Users can choose whether to switch to
> relative IDs or not.

I can try to split the question.

1. If the project id introduced by the 'use-project' rule is available only in 
the project which contains 'use-project' call and in children of that 
project, is it good idea to have "/" in the project-id. Won't users assume 
that ids with slash are 'global'. 

2. If we allow to drop "/", won't user be confused as well, and assume such 
project-id are relative to the *current* project -- i.e. project where such 
id is *used*?

Today, I think that the right approach would be to make project id local for 
each project, but still require leading slash. So, you can have '/boost' mean 
different things in different projects.

> > Problem 4. Subprojects. After
> >
> > use-project /home/ghost/boost/cvs ;
> >
> > I want to use all Boost libraries. I also want to be able to use them
> > after
> >
> > use-project boost-cvs : /home/ghost/boost/cvs ;
> >
> > There are two ways to make it work: automatically translate ids of
> > subprojects
>
> Sounds good.
>
> > or add a number of "alias" targets to Jamroot.
>
> Sounds inconvenient. Which Jamroot? The one in boost or in my
> project?

The one in boost.

> > In the first case, one will be able to use
> > "/boost-cvs/filesystem//boost_filesystem", and in the second case:
> > "/boost-cvs//filesystem".
>
> ?? Why are the target names different in these two cases?

It was a attempt to further simplify things -- the Jamroot can use arbitrary 
names for alias, for example

alias filesystem : libs/filesystem//boost_filesystem ;

> > The first case requires that Jamroot somehow provide the list of all
> > the subprojects (we don't have a documented way to do that),
>
> Only in the case where subprojects are not located in a direct
> subdirectory, right?

I don't think it matters. We don't have any automatic mechanism which will 
look at direct subdirectories and load projects there. Or you meant something 
else?

> > and the second case requires manual changes for each new
> > library. But maybe, it can be automated.
> >
> > Question 2. Which variant is better?
>
> I don't think you've described them clearly enough. I believe some
> sets of example projects may be required in order clearly illustrate.

Ok, here we go. 

Example 1.

Boost Jamroot:

project boost ;

# 'subproject' is a new rule. It specifies that whenever this project is
# used via 'use-project', the project id specified in this rule must also
# be made available.
subproject boost/filesystem : libs/filesystem/build ;

Client Jamfile:

using boost-cvs : /home/ghost/Work/boost ;
# Makes two project ids avaiable:
# '/boost-cvs' and '/boost-cvs/filesystem'. This requires
# that we walk though the list of subprojects defined in Boost's
# Jamroot and replace 'boost' with 'boost-cvs'.

exe a : a.cpp /boost-cvs/filesystem//boost_filesystem ;

Instead of creating a new 'subproject' rule we can use 'use-project'. So, 
Boost Jamroot will be:

use-project boost/filesystem : libs/filesystem/build ;

This will at the same time make '/boost/filesystem' available for all boost 
subprojects, and make it available tf all clients of Boost.

Example 2. 

Boost Jamroot:

project boost ;

alias filesystem : libs/filesystem/build//boost_filesystem ;

Client Jamfile:

using boost-cvs : /home/ghost/Work/boost ;

# Here it's possible to use '/boost-cvs//filesystem' to refer to a library

exe a : a.cpp /boost-cvs/filesystem ;

Example 3.

Boost Jamroot:

project boost ;

# given a project id, relative to 'boost', returns
# the directory where that project is located.
rule project-id-to-location ( id )
{
.............
}

exe a : a.cpp /boost-cvs/filesystem//boost_filesystem ;

Client Jamfile is just like in example 1:

Client Jamfile:

using boost-cvs : /home/ghost/Work/boost ;
# Makes two project ids avaiable:
# '/boost-cvs' and '/boost-cvs/filesystem'. This requires
# that we walk though the list of subprojects defined in Boost's
# Jamroot and replace 'boost' with 'boost-cvs'.

Implementation-wise, example 2 is a piece of cake, example 1 is a bit harder 
and example 3 is more hard. The problem with example 3 is that today, when 
resolving '/boost/filesystem' we handle this id just like string, not as 
'filesystem' subproject of '/boost'. There's just a global id -> project map 
that we consult. 

To handle example 3, lookup of '/boost/filesystem' will include these steps:

1. Search '/boost/filesystem' in the local id->project map
2. Search '/boost' and then try invoking the rule to perform the mapping.

which is certainly doable, though some extra work.

Now the question is what examples do we want to support.

- Volodya