Re: [jamboost] Some comments on Boost.Jam and Boost.Build

From: Vladimir Prus (ghost_at_[hidden])
Date: 2003-09-01 03:16:34

Hi Jurko,

Jurko "Gospodentiæ" wrote:

> I've been trying to get a grip on Boost.Build for the last two days
> and here are some my notes I took down while exploring it. Hopefully
> someone will find them helpful.

Sure! We're very interested in your feedback.

> Note: I've been using the Milestone 6 tarball on a Windows XP
> machine with BCB 5.0 and VC 6.0 compilers.
>
> 1. In the 'examples_v2/hello' project there are two extra lines in the
> Jamfile file not mentioned in the docs. They try to set up some
> symbolic links, however they also cause the build for that project to go
> differently than specified in the docs. Because of them both release
> and debug variants of the project are built every time (I'm not sure
> whether that's intentional or not) even if you build it using 'bjam debug'.
> The docs explicitly use this project to demonstrate how you can build
> just one of those targets if you want to and which is built by default.

Good catch. I'm about to remove the lines to avoid confusion.

> 2. File new/user-config.jam that comes with the tarball has some
> libraries specified (uncommented) by default which causes my clean
> install of bjam to fail because those libraries (related to docbook) could
> not be found on my system.
> When I comment out these lines then all works fine but the user
> docs say that you can run 'bjam --version' before getting into any
> details on how to make modifications to the build system and here
> that command was failing before modifying new/user-config.jam.

:-((( 
That's really and unfortunately is true. For now, I'll comment out everything 
from user-config.jam. 

> 3. Boost.Jam docs (Make(1)-redux) say that on Unix and NT machines
> $(var:P) and $(var:D) are the same. But that is not true because on my
> machine $(var:P) contains the grist while $(var:D) doesn't.
> Example:
> aaa = "<xxx>yyy/shoot.me" ;
> ECHO Without grist: $(aaa:D) ; ECHO With grist: $(aaa:P) ;

You're right. I've corrected our docs, as well as notified original Jam 
developers, who introduced this statement.

> 4. Modules don't work as Boost.Jam docs say they do and the code
> given in those docs fails to work as well. There are no 'fully qualified'
> 'module.rule' names for rules in modules in Boost.Jam. In other
> words the following code fails:
> module mmm { rule rrr { ECHO Wambadidu... ; } }
> mmm.rrr ;
> Those 'fully qualified names' are an artifact added manually by the
> Boost.Build system when using their modules.import rule for
> importing modules instead of the built-in IMPORT rule.

That's true. Dave, what's your opinion on how to fix the docs?

> 5. I believe there is a bug at the end of kernel/bootstrap.jam in the
> code for handling multiple --build-system command line options. The
> comment there says that the last specified build system is used.
> However, the second to last is used there ([-2] index instead of [-1]).
> I tried this out:
> bjam --build-system=aaa --build-system=bbb --build-system=ccc
> bbb.jam: No such file or directory

You're right again. I wonder, though, if we should issue an error if there are 
several --build-system switches?

> 6. I didn't find the :T variable modifier mentioned anywhere in the
> docs. It seems to only turn all forward and backward slashes into
> forward ones and is used for normalizing path strings.

I can't find it in docs, either. Dave, what's the best place?

> 7. The IMPORT built-in rule is used in kernel/modules.jam with an
> extra fifth parameter LOCALIZE which I can not find documented
> anywhere and I have no idea what it does. Any hints?

The rule which is localized will access variables from the module to which 
it's imported. I've attaches a small example to illustrate the different, 
which can be run with

bjam -flocalization.jam

This was undocumented for some time already, unfortunately.

> 8. A funny side effect of the help system. If you do
> bjam --help --help
> the help screen is displayed twice :-))

Funny... but how to fix it. For example, should

bjam --help doc --help doc

produce help on "doc" twice, or not ;-)

> So much from me for now. Please don't flame if any of the
> comments sound to newbie-like - I'll get the hang of it eventually.

Thanks for your comments! They all are well to the point.

- Volodya
 --Boundary-00=_iBwU/b+g5jdN65U Content-Type: text/plain;
charset="iso-8859-1";
name="localization.jam"
Content-Transfer-Encoding: 7bit
Content-Disposition: attachment;
filename="localization.jam"

module m 
{
a = 10 ;
rule first ( ) { ECHO "FIRST:" $(a) ; }
rule second ( ) { ECHO "SECOND:" $(a) ; } 
}

module s
{
a = 14 ; 

IMPORT m : first : s : first ;
IMPORT m : second : s : second : localize ;
rule do ( )
{
first ;
second ;
}
}

IMPORT s : do : : do ;
do ; --Boundary-00=_iBwU/b+g5jdN65U--