[Boost-build] language.html#jam.language.rules confusing about rules and actions

From: Larry Evans (cppljevans_at_[hidden])
Date: 2007-09-26 11:16:33

The description of "updating" rules and actions in:

http://www.boost.org/doc/html/jam/language.html#jam.language.rules

seems inconsistent with my experience (detailed further down) because
it contains:

   The procedure is a body of jam statements to be run when the rule is
   invoked; the actions are the OS shell commands to execute when
   updating the built targets of the rule.

The phrase "built targets of the rule" suggest that a rule can be used
to build a target.  This conclusion is reinforced by the use of
"updating rules" in:

   Rules fall into two categories: updating rules (with actions), and
   pure procedure rules (without actions). Updating rules treat
   arguments $(1)  and $(2) as built targets and sources, respectively,
   while pure procedure rules can take arbitrary arguments.

from further down the same page.  And of course there's the
"invocation" description on the same page:

    rulename field1 : field2 : ... : fieldN ;

All these lead, IMO, quite naturally to the conclusion that the
following portion of a Jamfile:

<--- cut here ---
rule my-update
{
     ECHO "in rule my-update" $(1) ":" $(2) ;
}

actions my-update
{
     echo "in actions my-update" $(1) ":" $(2) ;
}

my-update x : y ;

 >--- cut here ---

together with the following command line:

   bjam x

could lead to the following output to the screen:

   in rule my-update x : y
   ...
   in actions my-update x : y

However, only the following relevant output appears:

   in rule my-update x : y
   ...
   don't know how to make <e>x

This leads one to search further in the docs for something describing
how to "make" or "build" a "target".  Such a search leads on to:

   http://www.boost.org/boost-build2/doc/html/bbv2/advanced/targets.html

which says the only way to create such a target is, ultimately, to
declare a "type", but there's also the following contained in
targets.html:

   import generators ;
   generators.register-standard obfuscate.file : CPP : OBFUSCATED_CPP ;

followed by:

   you'll be able to use the rule "obfuscated-cpp" in Jamfiles, which
   will convert source to the OBFUSCATED_CPP type.

However, there's no hint about what obfuscate.file is, until the
bottom:

   Note that because you can associate a custom generator with a target
   type, the logic of building can be rather compiler.

(NOTE: the last word looks like it should be "complex" intead of
"compiler".)

Somewhere there should at least be a mention of what obfuscate.file is
and link to:

   http://www.boost.org/boost-build2/doc/html/bbv2/extending/tools.html

for further explanation.

SOLUTION:

   To avoid this confusion, any mention of "updating", "build", and
   "targets" in:

http://www.boost.org/doc/html/jam/language.html#jam.language.rules

   AFAICT, the association of actions with rules mentioned there is
   false, as demonstrated by the my-update exmple above.  This
   conclusion is supported by:

cd ~/prog_dev/boost-svn/ro/trunk/libs/
find . -name Jamfile\* -exec grep -e 'actions ' {} \; -print
actions wave
./function_types/build/Jamfile
actions wave
./function_types/build/.svn/text-base/Jamfile.svn-base

Compilation finished at Wed Sep 26 10:06:10

   and the fact that, in ./function_types/build/Jamfile, the only
   occurrence of wave is in invocations of the make rule, such as:

make $(BOOST_ROOT)/libs/function_types/build/timestamps/arity_loops
   : preprocess_arity_loops.cpp : wave ;

   So, I guess, when rules and like-named actions are only connected,
   automatically, the make rule; otherwise, they have to be explicitly
   connected with the generators.register-standard rule.  Is that
   right?