Re: [boost] Why Boost.Build?

Subject: Re: [boost] Why Boost.Build?
From: Edward Diener (eldiener_at_[hidden])
Date: 2011-03-27 11:34:43

On 3/26/2011 5:03 PM, Artyom wrote:
>>>
>>> Is there a reason why Boost uses Boost.Jam/Boost.Build for reasons  other
>> than tradition?
>>
>>
>> Boost.Build works great for those around here  caring enough to maintain a
>> build system for boost.
>
> In other words it work for thous who:
>
> 1. Maintain the system
> 2. Already has BBv2 support (existing Boost.Lobraries).
>
>> Also it seams to work  well enough that a new build system is not a top
>> priority for people willing
>> to  do something about it.  That said I think the fact that it is not as common
>> and well known as
>> some alternatives, and that it is missing some features people  are expecting
>> causes people to ask for CMake.
>>
>
> If fact BBv2 is total nightmare.
>
> It took me 3 work days to make unit-tests work for Boost.Locale
> using BBv2 and I had to add a workaround changing the test
> sources itself.
>
> 1. Documentation is just missing.
>
> 2. Half of functionality Boost.Locale uses for build is undocumented
>     and works only because it was originally  written by Vladimir Prus.
>
>     And this is by-the-way after several patches applied to it in trunk.
>
> 3. Simple tasks that every normal build system supports undocumented
>     and unclear (search library for example)

It's the documentation, not the tool itself, which is really difficult 
and makes Boost Build a nightmare for you.

The functionality in Boost Build is very adequate and often very good. 
The documentation is generally poor because it does not attempt to 
explain all of the information in Boost Build, and what it does explain 
is spread out in many different areas of the documentation to the 
detriment of the documentation's organization. Finally, what passes for 
an index in the documentation indexes practically nothing and is 
essentially completely worthless. Added to this is that what is 
presented online is almost never up to date with the latest changes in 
the documentation, and one has a nightmare produced not by bad software 
but more by an attitude about the lack of importance of the 
documentation in actually using the system.

Your comment is shooting the messenger because you don't understand the 
message. The message, Boost Build itself, is very neat software. The 
messenger, the documentation, makes it very hard to understand the 
message because it is not organized in a thorough way, and that makes it 
very hard to use the software itself except if you already know a great, 
great deal.

When software is very good, but very complicated, it is often hard to 
get developers to realize that it is to their interest to explain the 
software as methodically and as thoroughly as they should. They often 
resent it because they have produced this wonderful software system 
which they understand, and worked very hard on, and they can not 
understand why others should not understand it as well as they do with 
the explanation they produce to suit their own needs. I honestly believe 
this is the mindset into which the developers of Boost Build have 
settled. The system itself is wonderful, and does a tremendous number of 
things automatically for the developer, but when the developer needs to 
do something outside the normal way the Boost Build system operates, it 
is next to impossible finding this information in the documentation, 
because so much is missing or just assumes that the programmer should 
somehow know.

So I would say to you that your troubles with Boost Build are the same 
as my troubles with it have been periodically and those of so many Boost 
developers, which is not the software itself, which works wonderfully, 
but with understanding how to do things with the system for which the 
documentation simply does not provide answers or even adequate explanations.

I do not have an answer for this because, like you, I am not really 
interested in writing the Boost Build documentation for the developers 
just to use the system. When I am stumped, I ask on the Boost Build 
mailing list, get my answer, then move on to the next time I am stumped 
using the system. This is not the way I like to develop but "it is what 
it is". But I do understand your frustration.