env vars, documentation (Was: [jamboost] environment variables)

From: Vladimir Prus (ghost_at_[hidden])
Date: 2003-10-17 00:17:41

brock_peabody wrote:
> How does one access an environment variable in a jam file? For
> instance, I want to stage all of my exe's in one directory on my
> windows box, but in another on my linux box:
>
> stage exe : project : <location>$(EXE_DESTINATION) ;

You can get env var with

import modules ;
local EXE_DESTINATION = [ modules.peek : EXE_DESTINATION ] ;

> Actually, it would be better if there were a different way of doing
> it besides environment variables. Any ideas?

Well... you can put the following in your project-root.jam:

path-constant EXE_DESTINATION : /path/to/your/dir ;

You can then change this string dependencing on platform. For better 
maintainability you can:

1. Create file called "config.jam", or something. Put the above 
"path-constant" line there.

2. Add "include config.jam" to your project-root.jam

3. Write some tool for generating config.jam, or create different versions for 
different boxes, or something else. 

This last approach is better because modifying a single file which only lists 
directories is simpler than the entire project-root.jam, which can be much 
larger.

> Also, I really like Boost.Build, but it is very hard to get going.
> Is there some documentation besides the manual that I don't know
> about? 

There's a lot of comments in the code. You can look at the source, or use the 
nice "bjam --help" option. 

> When I look through the boost jam files for examples most of
> what I see is undocumented. I know this is a work in progress.
> Would it help for a neophyte like me to catalog undocumented
> keywords?

Frankly, I was never told how to write a good documentation. I'm putting 
issues that user raise into my notes with the hope to act on this complains 
one day. I think the best approach would be for you to continue posting 
messages about *any* omissions or obscurities in the documentation. 

In fact, I'd appreciate help about documentation structure, as well. From my 
point of view, the tutorial is okay -- it's better to add an example for each 
tutorial section, but it's okay anyway.

But what should be written next? Complete reference of every feature. I'm 
afraid that it will be overwhelming. That's why the current doc have a 
"reference" section, indended to give only quick reference, and "detailed 
reference", which document every detail. Is this structure OK? Can you 
suggest all stuff which should go into "reference" section? I'd be greatefull 
for suggestions.

- Volodya

- Volodya