Re: What is the point of project-root.jam/Jamroot?

From: David Abrahams (dave_at_[hidden])
Date: 2004-12-28 15:05:45

Vladimir Prus wrote:
> On Tuesday 28 December 2004 21:01, David Abrahams wrote:
> 
>> >> > Second, what if I have:
>> >> >
>> >> > Jamfile: project p ;
>> >> > libs/Jamfile: project : requirements .... ;
>> >> > libs/foo/Jamfile project foo ;
>> >> >
>> >> > Will libs/foo/Jamfile have if of p/foo?
>> >>
>> >> Sorry, I can't begin to parse that sentence.
>> >
>> > I'm asking what project id of libs/foo/Jamfile will be? Will it be p/foo,
>> > or something else?
>>
>> Actually I think this case is clear: libs/foo/Jamfile is a top-level
>> project called /foo. libs/Jamfile is an unnamed project, and Jamfile is
>> a top-level project called /p.
>>
>> Now if we change libs/foo/Jamfile to:
>>
>> project ../foo ;
>>
>> or
>>
>> subproject foo ;
>>
>> or
>>
>> project p/foo ;
>>
>> it should be an error. It's perfectly detectable. The next Jamfile in
>> the directory tree above any named subproject must be named.
> 
> I don't see why this should be so. Maybe, I just miss what we're trying to 
> achieve. Are we trying to allow a project to declare id relatively to 
> parent's id? 

That is not a direct goal. I'm just trying to eliminate redundancy. I
think there's enough (or should be enough) information to infer where
the project root is just by looking at project declarations without
needing a specially named file to label it.

> In that case:
> 
> project ../foo ;
> 
> makes sense to me. 

Okay.

> Are we also trying to disallow a project to declare arbitrary id? 

That's not a goal, although discouraging it seems wise. I just see no
need to allow arbitrary IDs if it makes it harder to eliminate Jamroot.

> If so, what does it buy us? 

Simplicity (no Jamroot) and understandability: project/subproject IDs
always have a logical relationship. Do not underestimate how much
easier that will make it to grok the documentation.

> And I think that in the case above, it's possible to manually 
> specify p/poo, no matter what intermediate Jamfiles are there.

Sure, but so what? I would make it an error to insert an intermediate
Jamfile, since that's almost certainly not desired.

>> > But it requires every child project to include "project" invocation, and
>> > it's not always needed. I've recently tried to convert to Boost.Build a
>> > large existing project. Each directory defines just one library. Now,
>> > each Jamfile looks like:
>> >
>> > llvm-lib foobar ;
>> >
>> > and that's all. I don't think requiring to define project id is good.
>>
>> That's a one-time investment for the rare case where you're converting a
>> large project, so I think it's a tiny cost to pay compared to the
>> conceptual overhead of requiring a funky special file at the top of a
>> project hierarchy. 
> 
> I don't quite agree. This investment is not for converting a project, it's 
> also for development. It means that whenever you define a new project, you 
> need to declare a project id. Also note that we planned the allow top-level 
> Jamfile to define a rule which maps project ids to directory locations. In 
> that case, all information about project ids will be contained in the 
> top-level Jamfile. What's the use of project id specified in a child project. 
> And if there's no use, why specify id at all?
> 
>> There's no precedent for that in any build system 
>> I've seen, 
> 
> SCons?

SCons requires a file at the root of a project that isn't called
Sconsfile? That's news to me.

>> and it's been a continual sort of mental friction from users. 
>> I remember that Ali had real problems with it, 
> 
> IIRC, his primary problem was that even "hello" example needs *two* files -- 
> Jamfile and project-root.jam -- and that's no longer required.

Yes, but it's weird that the "default" name for a project file is
"Jamfile" yet the simplest project requires "Jamroot." All of this can
be handled with different Jamfile contents rather than introducing an
additional file. The latter is more heavyweight.

>> and *something* recently 
>> spurred you to introduce Jamroot, which is just another expression of
>> that friction.
> 
> That "something" was the fact that you could use some rules (like "constant") 
> only in project-root.jam, and some other rules (like "exe") only in Jamfile, 
> and it was confusing. With a single required file that problem is solved.

Right. You moved closer to the ideal, but not all the way. Having two
different filenames is confusing, too. And having two different options
(Jamroot and project-root.jam) is even more confusing. I'm trying to
eliminate conceptual overhead.

>> As an alternative subprojects could just declare:
>>
>> subproject ;
>>
>> or
>>
>> subproject . ;
>>
>> Or, we could simply require that top-level uses of the project rule all
>> have ids. Any unnamed project will trigger a search up for a parent
>> Jamfile. 
> 
> So, a project is still is required to invoke the "project" rule, right?

There are many ways to eliminate Jamroot. If you take my last
suggestion, yes, the project root at least would have to invoke the
project rule to avoid the warning and upward search... though the
warning might be unobtrusive or even turned off by default.

Alternatively, you could introduce a "subproject" rule and require
subprojects to invoke it.

-- 
Dave Abrahams
Boost Consulting
http://www.boost-consulting.com