Re: [Boost-build] [Build] Extender Manual, Generators, Actions

Subject: Re: [Boost-build] [Build] Extender Manual, Generators, Actions
From: Brian Davis (bitminer_at_[hidden])
Date: 2009-04-22 11:34:21

See below

On Mon, Apr 20, 2009 at 10:23 PM, Steven Watanabe <watanabesj_at_[hidden]>wrote:

> AMDG
>
> Lee Winter wrote:
>
>> The Build Extender Manual gives examples and describes creating new
>> file types.  It gives examples and describes derived generators for
>> new file types.  And it gives examples of actions for new file types,
>> but does not decribe them.  Is there a written description for such
>> actions?
>>
>> If there is no written description, can anyone provide information on
>> the example in the manual?  It is as follows:
>>
>>      import type ;
>>      import generators ;
>>      type.register VERBATIM : verbatim ;
>>      generators.register-standard verbatim.inline-file : VERBATIM : CPP ;
>>      actions inline-file
>>      {
>>          "./inline-file.py" $(<) $(>)
>>      }
>>
>> The areas I'm seeking clarification of are as follow:
>>
>> 1.  The manual states that "...the name of the action block should be
>> specifed when creating targets."
>>
>> What targets are created in the above example?
>>
>>
>
> The code that you've pasted in does not create any targets.
> The verbatim.inline-file generator will be invoked when
> Boost.Build needs to convert a verbatim file to a cpp file
> as is shown at the bottom of
> http://www.boost.org/boost-build2/doc/html/bbv2/extender.html
>

>From my understanding the code does set up the generator to create CPP
(.cpp) files from VERBATIM (.verbatim) files using the python script
inline-file.py.  Thus generating .cpp files as a target.  I think the term
"generator" can be used to include the .jam file that defines the
configuration for the generator and the exe or script file that actualy
generates the target.  Here .cpp is a target and .verbatium is a target.
Source targets can be output targets for other targets.

.verbatim -> .cpp -> .obj -> .exe

Here .verbatim is a target that creates the target .cpp, .cpp target is used
to create target .obj which is then used to create target .exe.

>
>  2.  The manual states that "By convention, generators use the same
>> name of the action block as their own id."
>>
>> In the example above, is the name of the generator
>> "verbatim.inline-file" or "inline-file"?  If the former what magic
>> connects the generator name to the action named with a substring of
>> the generator's name?  Is the file type ("verbatim") automatically
>> suppressed?
>>
>>
>
> The name of the generator is verbatim.inline-file.
> verbatim is the name of the module.  (i.e. this code
> goes in a file called verbatim.jam)
>

This was not clear to me either when reading through the documentation or
after going through the soap.jam and verbatim.jam files I finally realized
that "own id" = name of file.. in this case "verbatim" because of the file
name verbatim.jam.  IMHO the documentation could use some refinement in this
area.  It can be figured out from looking at the examples, but clarification
in documentation will definitely speed up the learning curve.

>
>
>  3.  The construct "./inline-file.py" is not described in the manual.
>> It appears to be the invocation of a python script named
>> "inline-file".  Is it?  If so, what is the role of the leading "./"?
>>
>>
>
> The contents of the action block are passed to the shell
> after variable substitution.
>

./ is current working directory of where the .jam file is located

from cygwin prompt:

ls boost_1_38_0/tools/build/v2/example/customization/
class.verbatim  inline_file.py  jamroot.jam  t1.verbatim  usage.verbatim
codegen.cpp     jamfile.jam     readme.txt   t2.verbatim  verbatim.jam

You will find verbatim.jam and inline_file.py in this directory.  I
recommend looking at the generators supplied and the examples in this
directory.  This is how I had to *realy* learn boost build.  Does'nt hurt to
look at source to bjam as well.

>
>  4.  If the shell command needs to invoke a filter program handling
>> stdin and stdout pipes rather than a typical command-line program that
>> takes file names as arguments, how should such a filter action be
>> defined?
>>
>>
>
I have never done this, but you may find what you are looking for in:

boost_1_38_0/tools/build/v2/tools/testing.jam

see rule:

# Runs executable 'sources' and stores stdout in file 'target'. Unless
# --preserve-test-targets command line option has been specified, removes
the
# executable. The 'target-to-remove' parameter controls what should be
removed:
#   - if 'none', does not remove anything, ever
#   - if empty, removes 'source'
#   - if non-empty and not 'none', contains a list of sources to remove.
#
rule capture-output ( target : source : properties * : targets-to-remove * )
...
...

It looks as though you would need to create a rule not an action (though
this may be possible) to capture stdio or stdin.  I would hope others that
know more than I would weigh in on this.  I am unsure if this can be done in
a action, but I have *limited* knowledge.

** I also recommend if you are using eclipse to point its search path to the
boost lib and ctrl-H search limiting search to Jamroot, *.v2, *.jam.  This
is how I find the "good stuff" :-) **

Hope it helps

-- 
Brian J. Davis