[Boost-build] boost documentation

From: david x callaway (dxc_at_[hidden])
Date: 2007-01-28 16:17:51

I've sent this twice already, but it never showed up. maybe this time?

dxc

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 boost.build 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.

thx
dxc

--- 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" ;
       }
       else
       {
         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:
 >>
 >> http://www.brainbell.com/tutorials/C++/Building_C++_Applications.htm
 >>
 >> 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
 >