Re: [Boost-build] Boost.Build Documentation (on Steriods) for Newbies?

From: Mateusz Loskot (mateusz_at_[hidden])
Date: 2007-01-19 11:29:51

Hassan Mehmet wrote:
> Mateusz Loskot <mateusz <at> loskot.net> writes:
> 
>> Here are some simple crash courses I found very helpful:
>> 
>> http://www.brainbell.com/tutorials/C++/Building_C++_Applications.htm
>> 
> 
> Thanks for that link
> 
> It taught me more in one visit than hours of trawling through the
> manual and code.

I started with these tutorials myself, and then I move to the BB manual.

> IMHO There really needs to be some good clear examples about creating
> your own target types (for anyone who wants to do more than a simple
> build.)
> 
> For instance it is still not clear after much investigation how the
> whole system hangs together (for instance how are generators, rules
> and actions related etc?).
> 
> The same problem has been found by most of my colleagues (all
> experienced and busy programmers) who do not have days to spend
> struggling with a build system.

I also found it hard to navigate through the manual and collect all
details in my brain.
Current manual includes most of details, but it's composition is not
newbie friendly.

The content is scattered a bit, so I found that I have to have open
every chapter in separate Firefox tab and jump between :-)

Just to give an example of manual I consider newbie friendly,
I'd suggest to look at the Buildbot manual - the subject is similar -
configuration of something ;-)

http://buildbot.sourceforge.net/manual-0.7.5.html

and in the Boost.Build, I feel the lack of similar chapter like the 3rd
in Buildbot's manual: list of fundamental concepts, explain purpose and
representation of every concept of the system, and then but not earlier,
move to explanation about how to use these concepts to write
configuration - Jamfiles in our case.

I appologize I present only a criticism here, but I have no knowledge to
contribute to such writing.

Cheers
-- 
Mateusz Loskot
http://mateusz.loskot.net