Re: [jamboost] Newbie impression of Boost.Build v2

From: Vladimir Prus (ghost_at_[hidden])
Date: 2003-05-07 03:38:27

Hi Zbynek,

Zbynek Winkler wrote:
> Here is an impression I got as a first time user.

Thanks for sending those! First time users are important for any project.

> http://boost.sourceforge.net/boost-build2/boost_build_v2.html claims to
> be "user manual" which I think it is not. First of all it is too long.

I'm not sure there's a problem. "User manual" should describe everything the 
"user" (i.e. not developer) might want. It would probably be best to have 
three documents: "manual for just users", "manual for extenders" and "docs 
for hackers".

> Second, the first part gives overall view of how things work in the
> build system, which is fine. What is not fine is the fact that the
> manual cannot be read from the beginning (without going back and forth).
> One example is "Project hierarchy". It says
> -----------------
> For example, if [top]/Jamfile has
>
> <include>/home/ghost/local
>
> in requirements, then all other projects will have that in their
> requirements too.
> -----------------
> After going through the sources I've found out that you just cannot
> place <include>/home/ghost/local in the jamfile (or can you?). 

On top level? No, you cannot.

> You have
> to put it in project->requirements. When reading this I had no notion
> what an "requirements" could be (or that it is something really really
> special, that it really is a "feature"), neither that it has some
> special syntax.

Actually, both requirements and project requirements are described in the 
previous section, called "properties". Two quotes:

1.
To support such situations, every target is allowed to specify 
requirements -- properties that are required to its building. Consider 
this example: 
exe hello 
: hello.cpp
: <include>/home/ghost/Work/boost <threading>multi

In this case, when hello is build, the two specified properties will
always be present.

2.
Each project (i.e. each Jamfile), can specify a set of attributes,
including requirements: 
project 
: requirements <include>/home/ghost/Work/boost <threading>multi 
;

Could you suggest or, even better, send a patch, that would make the "project 
hierarchy" section more understandable?

> So... It gives the impression that the system is really cool and
> powerfull. But the more you try to do the things in the "tutorial", the
> more this impression changes to "too powerfull to be of any good" or
> "not cool at all" because you cannot just copy&paste the lines and
> expect it to work. 

Could you please detail what lines do not work when copy-pasted. The line 
above is not really meant to be copy-pasted and makes sense only in context 
of the two quotes I gave.

> Not even such a basic command as "bjam --version"
> (from istallation step #2) works out of the box. The catch is that the
> "bjam" needs to find the configuration files. When you happen (as me) to
> run the bjam exe from directory boost/tools/build you get some bullshit as
> d:\devel\boost\boost\tools\build>bjam --version
> Jamfile: No such file or directory
> Jamfile: No such file or directory
> ...found 8 targets...

Oh... that's a embarassing distrubution problem --- it missed top-level 
boost-build.jam file. I'll fix this later today.

> Then there is something that claims to be "Reference" where is a lot of
> theory and no facts. When I almost figured out the overall syntax of the
> jamfile I tried <runtime-link> "feature" only to find out that it is
> <link-runtime>... (found it in the msvc.jam). 

Agh.. that thing was renamed and docs became out of sync. I've corrected this.

> The <link-runtime> feature
> can be set to "shared" which finaly gave me the /MD in the command line.
> Too bad that it is giving me /MD even for debug build (instead of /MDd).

I'll add this to the list of M3 issues, hopefully it can be fixed quickly.

> Often mention option <threading>multi (what I kind of expected to select
> the multithreding runtime) only broke my jamfile when I added it to the
> requirements. 

Could you give more details about this problem?

> I would expect "reference" to be a description of the
> grammar used and a list of things that can be set and how. The things
> there are now claimed to be a reference would be more a decription of
> the architecture.

I think the biggest problem is that we don't have docs for builtin facilities, 
like <link-runtime>, or various main target types, and so on. Actually, some
of those things are documented as comments, but first-time user should be 
forced to look there. I also agree that the first sections of "reference" are 
of little direct value to user. Probably, "reference" can be rearranges like 
this:

- Initialization
- Main target declaration
- Project declaration
- Builtin features
- Exact build semantics (including the way properties are refined and usage
requirements are propagated)
- Builtin rules (maybe with links to comments in code)
- Advanced/detailed topics

> Do not get me wrong. I think that the Boost.Build v2 is The Next Big
> Thing (at least for me :-)). I really like the idea (otherwise I would
> not spend the whole day today trying to get a hold of it :-)). It is
> just that the documentation is not much helpful for a boost.build newbie
> (such as me). So if you think I can help, let me know. I do not have
> much spare time but I can always at least test something here or there...

Thanks for your feedback! 

- Volodya