[Boost-build] bjam -s option variable access documentation

From: Sebastian Schulz (sschulz_at_[hidden])
Date: 2007-09-12 13:57:08

Switching from perforce jam to bjam, I am slightly confused by the way
bjam's access to variables passed by the -s option.

My (simplified ;-)) Jamfile/Jamroot:
Echo $(X) ;

Calling with jam/bjam:

$> jam -sX=12
12
...

$> bjam -sX=12

...

To access X in Jamroot with bjam, I have to "peek" the variable first:

local X = [ modules.peek : X ] ;
Echo $(X) ;

$> bjam -sX=12
12
...

This is quite ok, but it took me some time to figure this out (found
http://lists.boost.org/boost-build/2005/04/9377.php).

IMHO the documentation at
http://boost.org/doc/html/jam/usage.html#jam.usage.options
describes the perforce-jam behavior, not bjam's:

"-s   var=value
     Set the variable var to value, overriding both internal variables
and variables imported from the environment."

Further more, http://boost.org/doc/html/jam.html#jam.intro states the
backward compatibility to perforce jam, so I thought the access to
variables would be the same.

I think a hint on how to access variables passes by -s within a Jamfile
in the "Boost.Build V2 User Manual" would be quite helpful for bjam
newbies like me.

Or maybe I overlooked a section in the documentation?
Thanks for any hints to documentation on this topic (modules.peek).

-Seb