Re: [jamboost] Boost.Build design document

From: Rene Rivera (grafik666_at_[hidden])
Date: 2002-01-22 16:57:56

On 2002-01-22 at 02:19 PM, david.abrahams_at_[hidden] (David Abrahams) wrote:

>
>----- Original Message -----
>From: "Rene Rivera" <grafik666_at_[hidden]>
>
>> Initialization:
>>
>> We check the name used to invoke Jam, and if the name is not the
>recognized
>> Boost.Jam invocation we continue with the execution of the Perforce
>builting
>> Jambase.
>>
>> Otherwise, when we recognize a Boost.Jam invocation, we:
>>
>> 1. We search for "project-root.jam" from the invocation directory up
>to
>> the root of the file-system. When found its location is noted as the
>> PROJECT_ROOT. If not found we exit with an appropriate error message.
>> 2. We load "project-root.jam", within it one can call the
>"boost-build"
>> rule to indicate where to find the Boost.Build files. The "boost-build"
>rule
>> does two things: a) pushes the given path onto the BOOST_BUILD_PATH (if
>> given), b) attempts to load the build system.
>> 3. If the build system isn't loaded yet, load it at this time by
>invoking
>> "boost-build".
>
>Any interesting project-root.jam file will want to use rules made available
>by the build system (e.g. the modules.jam), so the above isn't really a
>viable alternative.

Hmm, it is viable :-] If you want to use Boost.Build constructs in the
project-root.jam file you call "boost-build ;" before you need the constructs.
That makes the load order: Jambase[builtin] -> project-root.jam (boost-build
invocation) -> boost-build.jam (pop back from include) -> project-root.jam
(after boost-build invocation) -> Jamfile.

If one doesn't need to use the Boost.Build constructs, one doesn't call
"boost-build" and then the load order becomes: Jambase[builtin] ->
project-root.jam -> boost-build.jam -> Jamfile.

>> 4. Finally we load the Jamfile in the invocation directory.
>>
>> This procedure has the effect of allowing both simple and complex setup.
>In
>> the "project-root.jam" it's possible to obtain control of the build system
>> both before the system is loaded and before the Jamfile is loaded.
>
>How would this work when multiple users are working on the same project but
>the Boost.Build source is located in different places?

Yes, that is a problem.

>One possibility is
>that in this project, the user is responsible for supplying a
>project-root.jam which invokes boost-build, and then for invoking the real
>"project-root.jam". However, I'm not fond of this idea.

Ah, yuck.

>I suggest instead
>that the project-root directory (or any other directory above the Jamfile?)
>may contain boost-build.jam, which may be used to load the build system.
>That would also handle the problem above; if we can't find boost-build.jam
>above the Jamfile, we assume that BOOST_BUILD_PATH is set up, and let it
>take effect.

That seems reasonable, and it fits with the way I currently implement the
search also.

>[BTW, I'm getting less and less fond of relying on environment variables for
>anything.]

Me too, and currently I can only think of one that is absolutely needed,
BOOST_BUILD_PATH. The ones for the names are mostly frivolous but I though it
worth mentioning because of the name arguments we've had in the past :-\

>At that point, we proceed to load project-root.jam. How's that?

Seems doable as long as we can guarantee one thing: that we don't need to
setup any variables before loading boost-build.jam! But since we want to
remove use of variables for setup anyway it makes sense.

How about this as the modified sequence then:

1. We attempt to load "boost-build.jam" by searching from the current
invocation directory up to the root of the file-system and in the paths
specified by BOOST_BUILD_PATH. Within this, one invokes the "boost-build" rule
to indicate where the Boost.Build system files are, and to load them.
2. If the Boost.Build system isn't loaded yet we error and exit, giving
brief instructions on possible errors.
3. We attempt to load "project-root.jam" by searching from the current
invocation directory up to the root of the file-system. When found its
location is noted as the PROJECT_ROOT.
4. Finally we load the "Jamfile" in the invocation directory. There are
various spellings considered when finding the "Jamfile", the pattern for the
name must fit: (J | j)amfile[.jam].

>> ...some thoughts:
>>
>> To answer your FTJam concern, I would suggest we dump the FTJAm Jambase
>> entirely and use the Perforce one instead. Since we are only using it to
>build
>> jam itself we should only need the functionality from the release. Or does
>the
>> Jamfile in jam_src use FTJam functionality?
>
>I think that it does not. However, some of the toolset description files
>make use of the FTJam JAM_TOOLSET variables (e.g. intel-win32 uses VISUALC).

Doesn't 2.4 have changes to deal with VisualC? Like reading the registry to
setup it up within jam?

>I don't think that really means anything, though. Hmm, the FTJam changes
>does make it easier to build Jam with various compilers, e.g. Borland.
>
>> Naming conventions... given that we want "clean up" the use of user
>> configurable variables we should define some naming conventions.
>Specifically
>> for the initialization there would need to be two variables for possibly
>> overriding the default names for "project-root.jam" and "Jamfile".
>Possibly
>> BOOST_BUILD_PROJECT_ROOT_FILE and BOOST_BUILD_PROJECT_FILE?
>
>Really? Do we really need to allow that?
>If we need to support any environment variables, I guess those would be the
>ones. As I said, environment settings are leaving me with a bad taste.

No we don't need to support that. But it's a question of configurability and
expectation. Is it something users will want to change? Is something users
will expect to be able to change?

Don't know about wanting to change it, as all users are different :-) As for
expecting the ability to change it... currently there is a JAMFILE variable
that does this, so a user familiar with Jam-MR might expect that
functionality.

>> With that in mind one question is wether we want to support multiple file
>> names? That is do we search for both "Jamfile" and "project.jam"?
>
>I think it makes sense to look for "[Jj]amfile" and possibly "JAMFILE". If
>you really want to be able to use extensions, let's also allow
>"[Jj]amfile.jam".

I definitely want to use extensions ;-]

Is that "$(JAMFILE)" the variable or "JAMFILE" all caps?

One though about "include"... We are going to need to abstract out the include
functionality so that we can check for multiple includes, and found not found.
AFAIK the module code does that already but we would not be able to use it in
Jambase. I'd also like to have a variable setup in the included file scope
that tells it where the file is located. That way the PROJECT_ROOT variable is
not needed and if one ever needs to generate absolute paths relative to the
current file it's easily done. It might look something like:

rule include-file ( file : paths * )
{
if ! $(gINCLUDED($(file)))
{
BINRULE on $(file) = set-include-file-location ;
SEARCH on $(file) = $(paths) ;
gINCLUDED($(file)) = TRUE ;
local CWD ;
include $(file) ;
}
return $(gINCLUDED($(file))) ;
}

rule set-include-file-location ( file : path )
{
CWD = $(path:D) ;
}

... That's just a sketch, there is additional checking code needed to handle
not finding the file.

This way it means that the boost-build.jam file could be as simple as:

boost-build $(CWD)/tools/build ;

A better name than "CWD" would be good though :-\

-- grafik - Don't Assume Anything
-- rrivera_at_[hidden] - grafik_at_[hidden]
-- 102708583_at_icq - Grafik666_at_AIM - Grafik_at_[hidden]