Boost logo

Boost-Build :

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.

> 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:

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.

Each project (i.e. each Jamfile), can specify a set of attributes,
including requirements:
: 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

- 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 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


Boost-Build list run by bdawes at, david.abrahams at, gregod at, cpdaniel at, john at