On Mon, Apr 20, 2009 at 10:23 PM, Steven Watanabe
<watanabesj@gmail.com> 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?