Re: [jamboost] [BBv2 doc editorial] Tutorial

From: Andrey Melnikov (melnikov_at_[hidden])
Date: 2005-09-21 11:10:29

Vladimir Prus wrote:
> On Wednesday 21 September 2005 00:55, Andrey Melnikov wrote:
> 
>>The examples don't demonstrate the key BB features and don't have a big
>>practical usage for a newbie.
> 
> 
> In fact, they was not meant to demonstrate everything. IMO, tutorial should 
> guide though basic tasks in a project (building, testing, installing) so that
> user gets familiar with the tool.

I don't see a big diffenence between "guide through" and "demonstrate". 
But the tasks should be really "basic".

IMO the the following tasks are rather advanced and are required only if 
a user is going to support multiple toolsets and/or build configurations:

- build variants
- folder naming algorithm (chaining of free properties)
- linking a single cpp file into many executables
- cleaning specific targets

The tutorial can be much simpler and demonstrate more basic features.

As the first step in improving, I suggest to remove the features I 
listed and move them to a more advanced chapter of the tutorial. Or even 
to the reference.

------
Hello, world

The simplest project that Boost.Build can construct is stored in 
example/hello/ directory. The project is described by a file called 
Jamroot that contains:

exe hello : hello.cpp ;

Now let's remove all the built products (hello.obj and hello.exe on 
Windows):

bjam --clean

To rebuild the exe, run

bjam -a

Boost.Build will rebuild all (hence "-a") the targets unconditionally.
------

> 
> 
>>Look at my Getting Started Guide: http://tinyurl.com/bcgwf
>>It isn't perfect, but I think some ideas can be taken from there.
> 
> 
> I think those key advanges section complements, but does not override, the 
> tutorial. Users to need a simple self-contained and very commented examples.
> And as you say yourself:
> 
> 
>>The sections are for managers and their goal is to help them to evaluate 
>>pros and cons quickly and to sell the idea to use Boost.Build to the 
>>team and to the top management.
> 
> 
> - Volodya
>