From: Vladimir Prus (ghost_at_[hidden])
Date: 2003-05-07 03:38:27
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
> 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
> 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
: <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,
: 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
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
- 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!
Boost-Build list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk