Re: [scons-devel] scons vs cmake vs bjam ...

From: David Abrahams (dave_at_[hidden])
Date: 2003-02-28 10:25:06

Bram Moolenaar <Bram_at_[hidden]> writes:

> David Abrahams wrote:
>
>> > May the info at
>> >
>> > http://www.a-a-p.org/tools_build.html
>> >
>> > is useful.
>> 
>> The description there does Boost.Build a great disservice. The status
>> is "mature and used in several projects outside Boost that we know of;
>> also nearing release of a complete rewrite with many new features and
>> new documentation."
>
> I wrote that remark almost a year ago. There appears to be a lot more
> useful information now. 

I got into the same sort of trouble with a comparisons page for the
Boost.Python library. You have to be careful to maintain these
things or provide a big disclaimer at the beginning, or you're going
to be leading people astray, because things change.

> The jamfile syntax looks a bit like what I use for a recipe (but
> different enough). Browsing through the web site now I'm confused
> about what the difference is between Boost.Build and Boost.Jam.

Boost.Jam is the tool which implements the build system (an
interpreted language with build-tool primitives built in).
Boost.Build is the high-level system built around Boost.Jam, using its
built-in interpreted language.

> Main problem of the documentation is that it assumes knowledge of
> Jam.

If you take the documentation in total, which includes documentation
of stock Perforce Jam, there is no such assumption. Unfortunately it
means you have to look at a few documents before you get the big
picture.

> I don't know Jam thus there are many things I don't understand about
> the Boost.Build documentation. That makes it very difficult to read
> for someone like me, who only wants to have a quick look at how it
> works.

That's probably true; I've learned that no matter how complete your
reference documentation is, nobody will care unless there's an easy
tutorial all in one place.

> Although the web site states it's mature, I'm not sure it is mature
> in the meaning I give to that word. I call something mature when
> several versions have been released

That is true.

> there are few bugs

That depends on your definition of "bug", but that's also basically
true.

> and no incompatible changes. 

We haven't introduced any incompatible changes in a long, long time.

> The remark "complete rewrite" contradicts the mature status.

Not neccessarily ;-). Often that's what happens to mature software.
It gets stable and reliable enough that the designers have the luxury
to go back and reconsider all their initial decisions.

>> Despite its that, A-A-P seems to be trying to do what Boost.Build
>> does, but at a lower level.
>
> I think the goal for A-A-P is similar. I haven't done some of the
> higher level items yet, but it is certainly a goal to reach a higher
> level. The basis must be done first.

...which is why when you started this, I strongly suggested that you
capitalize on the design work we had done. As it stands, the part of
A-A-P that overlaps with the goals for Boost.Build is still lagging.

>> The remark there claims that Boost.Build syntax is "a bit cryptic",
>> but then a simple A-A-P recipe listed is:
>> 
>> all: foo$EXESUF bar$EXESUF
>> ROOT = main
>> version
>> work
>> util
>> COMMON = $BDIR/$*ROOT$OBJSUF
>> 
>> foo$EXESUF : $COMMON $BDIR/foo$OBJSUF
>> :do build $source
>> 
>> bar$EXESUF : $COMMON $BDIR/bar$OBJSUF
>> :do build $source
>> 
>> which, in Boost.Build would be:
>> 
>> project-root ; # top of project hierarchy
>> 
>> ROOT = main.c
>> version.c
>> work.c
>> util.c ;
>> 
>> COMMON = $(BDIR)/$(ROOT) ;
>> 
>> exe foo : $(COMMON) $(BDIR)/foo.c ;
>> exe bar : $(COMMON) $(BDIR)/bar.c ;
>> 
>> this is already simpler than the former, and hides many
>> platform-specific issues like the suffix used for executables and
>> object files.
>
> This comparison is not fair, because the Boost file specifies only the
> source files, not the object files. 

Precisely my point. Boost.Build derives the build path from sources
to targets through intermediate (.obj) files. The user doesn't have
to think about files which are merely a byproduct of the build
process... though your example below seems to imply that A-A-P can do
that too.

> The A-A-P recipe quoted is used to explain how $BDIR works, it is
> not the simplest recipe for the task. You can do the same with
> A-A-P and the resulting recipe is very similar:

Oh, the documentation I took that from doesn't even give a clue what
$BDIR means. If it's a way to re-root the build output directory,
Boost.Build already has that built-in; you wouldn't need to write
anything special in the Jamfile.

> all: foo$EXESUF bar$EXESUF
>
> COMMON = main.c
> version.c
> work.c
> util.c 
> 
> foo$EXESUF : $COMMON foo.c
> :do build $source
> bar$EXESUF : $COMMON bar.c
> :do build $source
>
> The use of $EXESUF is indeed not that nice. It could be left out and
> you end up with foo.exe and bar.exe anyway. But that's confusing.
> The extension is necessary when the executable is used in another
> dependency, such as the "all" target in the example above. If I
> understand it correctly, Boost does this by prepending <exe> to the
> executable name:
>
> all : <exe>foo <exe>bar ;
>
> Is that correct? 

Actually, no; you'd never write that. That requirement is just for
library dependencies, to distinguish static and shared libraries of
the same name in the same subproject. However, the notation is
dropped in Boost.Build v2; you don't need to do anything to
disambiguate unless you want to. The build system does something
sensible automatically.

> It's not much different from using $EXESUF, but it does introduce a
> new mechanism. Although using $EXESUF isn't nice, it at least keeps
> the logic simple.

It's actually very different, but the reasons are deeper than they
may appear on the surface.

> I don't see how you can specify with Boost whether you want to invoke
> the compiler once with all C files or compile each C file separately and
> link them together in a separate step. In this simple example that is
> not important, but for more complex situations it is.

Boost.Build v1 doesn't support compiling more than one C file at a
time, but in Boost.Build v2 its as simple as associating an
appropriate generator with the toolset. The optimal sequence of
transformations to get from sources to targets is chosen
automatically. Why should the user ever concern herself with whether
sources are compiled together or separately?

> Note that it would be possible to make a recipe that produces foo.exe,
> foo.com, foo.bat and foo.py. These are all executable files. But
> perhaps producing the most obvious one, foo.exe, should be simple.

Yes, we have the same kinds of capabilites.

>> Furthermore, the need to evaluate variables with $(...)
>> in Boost.Build Jamfile is actually quite rare. The next example at
>> http://www.a-a-p.org/examples.html#variants exposes other
>> toolset-specific settings, like specific flags enabling optimization
>> and debug symbols, that you would never touch directly in Boost.Build
>> unless you were writing a toolset description.
>
> That is something that I still need to work on. The main problem is
> that obvious things like building for debugging can be done in a simple
> way and hidden from the user. But the user may want to do many
> different things which the build system doesn't know about (esp. for
> less often used languages). Then you need to be able to fall back to
> the basic mechanisms.

Of course Boost.Build has those backdoor capabilities.

>> I'm sure that A-A-P has some advantages over Boost.Build, but the
>> webpage description of Boost.Build is really not a good description.
>
> I'll update it.

-- 
Dave Abrahams
Boost Consulting
www.boost-consulting.com