Boost logo

Boost-Build :

From: david x callaway (dxc_at_[hidden])
Date: 2007-01-19 18:09:04

I'll second or third the request for better docs for the new user. it's
extremely easy to use if you don't want to do anything odd, but that
won't do it for most people (other than hello world or hello library).

what I did to try it out was set up to build something that already
works using Make, a c++ library that links to 3rd party stuff, an exe
that uses the lib and some compiled resources (this is all ICU stuff).
thanks to Vladimir I was able to make it work, but when I went back and
looked at it 3 weeks later I realize I didn't actually understand what
was happening.

below is the code in question. what it does is runs the ICU resource
compiler to turn 3 files named *.txt into *.res. the most confusing
part is the genrb rule returns a list containing "root en de". I sort
of understand that "res $(r:B) : $(r) ;" calls the res rule (which acts
like a function call; the text substitution is no issue, I get that),
but exactly how that causes it to be built beats me. also I assume
"res.resource" links the action "resource" to the .txt/.res
relationship, but I haven't found an explanation for the rules of that
linkage. also the top level rule for .txt/.res is implicitly generated,
but I don't know what it would look like.

I also had a sizeable adventure writing a rule to remove some files that
aren't direct products of a build, e.g. "*~" files that emacs leaves
lying around. with Make this is of course trivial, but with boost I
ended up with the (to be verified) monster that follows the genrb rules.
I realize that variants, installs, and so forth make this not as simple
as the simplest Make clean rule, but regardless it is a daunting outcome
for something I've done trivially forever using Make (see the text of
the rm-on-clean rule below).

I've had my eye on for years because of the possibility of
using a high level description rather than hundreds of lines of details
in Makefiles, especially for cross platform builds (and note one of
these projects involved using a COM emulator on linux, i.e. windowsisms
to the max but using gcc/g++), so don't get the idea I don't want to
succeed here. the problem for me is as soon as I start thinking about
how to sell it to developers who mostly are barely into cut/paste level
Makefiles let alone something new, I know the first question will be
some thorny issue with an oddball build (think running a windows
resource compiler on linux or screwball linker options), or something
like the ICU resources where you need to run a tool for which there is
no builtin rule.

in short better examples would be a big help. I know I didn't learn
Make in a day (if in fact I ever did ;-), so I'm willing to put in time,
but I prefer making progress to bouncing around at random doing cut and
pray hoping to make it work.


--- res.jam in root dir ---
type.register RES : res ;
type.register TXT : txt ;

generators.register-standard res.resource : TXT : RES ;

actions resource
     genrb "-d$(<:D)" "$(>)"
--- end res.jam ---

--- in Jamroot ---
rule genrb ( sources + : requirements * )
   local result ;

   for local r in $(sources)
     res $(r:B) : $(r) ;
     result += $(r:B) ;

   return $(result) ;
--- end Jamroot ---

--- in the Jamfile that builds the resources
rsrcs = root.txt en.txt de.txt ;

reslist = [ genrb $(rsrcs) ] ;
--- end resource Jamfile ---

--- the rule for removing extra stuff ---
--- it works, but if this isn't scary, what is? ---
# use it like this:
# rm-on-clean *~ whatever.txt ;

rule rm-on-clean ( files * )
   if "$(files)"
     local argv = [ modules.peek : ARGV ] ;

     if "clean" in $(argv) || "--clean" in $(argv)
       local cmd ;

       if [ os.on-windows ]
         cmd = "del /f /q" ;
         cmd = "rm -f" ;

       local native_names ;

       # flip the leaning toothpicks before expansion

       for local name in $(files)
         local normalized = [ path.make $(name) ] ;
         native_names += [ path.native $(normalized) ] ;

       local caller = [ utility.caller-file ] ;
       local dirname = [ path.parent $(caller) ] ;

       for local name in $(native_names)
         local del_list = [ path.glob $(dirname) : $(name) ] ;

         for local file in $(del_list)
           if [ path.exists $(file) ]
             SHELL "$(cmd) \"$(file)\"" ;

Dean Michael Berris wrote:
> On 1/16/07, Mateusz Loskot <mateusz_at_[hidden]> wrote:
>> Dean Michael Berris wrote:
>>> I'm primarily thinking about the people just starting out with using
>>> Boost.Build V2 in their own projects looking for information about it.
>>> Collating information like this into one definitive document would be
>>> a worthy effort IMHO.
>> Generally, start with BBv2 is hard :-) and time consuming, but feasible.
> Oh I can attest to that... But fortunately, trial and error, much
> hours of tinkering, and later refactoring (and borrowing from some of
> the Jamfile.v2's in the Boost Distribution) made me think "There's got
> to be a better way if I want to `sell` this to my colleagues..." --
> and now I'm in the beginnings of writing something that's more
> Wiki-friendly.
> Collecting references is the first step, and formulating an outline
> the next. Right now I'm in the first step, and the outline I should be
> able to make public soon (through a Wiki I'll try to host in our
> company site).
>> Here are some simple crash courses I found very helpful:
>> As you can see, these tutorials are very well-written in comparative
>> style, and shows how to achieve the same tasks using different tool
>> chains, Boost.Build included.
> Thanks! I might pattern it like this, but I'm more interested in
> incorporating more anecdotes, personal experiences (from the community
> at large), tips and tricks, and perhaps a "Get Funky With It" blurb
> for really interesting advanced stuff users might be interested in.
>>> Perhaps later, we can start writing propaganda material for people
>>> who've been bitten by autoconf hell and are interested in looking for
>>> a GNU Make replacement.
>> I believe the best propaganda is extremely user-friendly set of docs,
>> for instance, wiki.
> It's certainly a good way of showing that we're reaching out and
> trying to get Newbies started to actually being more productive with
> Boost.Build at least. :)
>>> C++ Users Journal,
>> R.I.P :-(
> Sadness... Oh well, there's always the back issues. :D

Boost-Build list run by bdawes at, david.abrahams at, gregod at, cpdaniel at, john at