Bug 10364

Hello Scott,

BitBake-style Python functions involved some pretty deep magic for me. Here's a
suggested new section to explain how they differ from regular Python functions.
It also demystifies bb.build.exec_func().

  3.5.4. Bitbake-Style Python Functions Versus Python Functions
  
  Listed below are some important differences between BitBake-style Python
  function and regular Python functions defined with 'def':
  
   * Only BitBake-style Python functions can be [tasks](3.6 Tasks).
   
   * Overrides and override-style operators can only be applied to
     BitBake-style Python functions.
  
   * Only regular Python functions can take arguments and return values.
  
   * Variable flags such as 'dirs', 'cleandirs', and 'lockfiles' can only be
     used on BitBake-style Python functions.
  
   * BitBake-style Python functions generate a separate
     ${[T]}/run.<function-name>.<pid> script that is executed to run the
     function, and also generate a log file in ${T}/log.<function-name>.<pid> if
     they are executed as tasks.
  
     Regular Python functions execute "inline" and do not generate any files in
     ${T}.
  
   * Regular Python functions are called with the usual Python syntax.
     BitBake-style Python functions are usually tasks and are called directly by
     BitBake, but can also be called manually from Python code by using the
     bb.build.exec_func() function. Here is an example:
  
       bb.build.exec_func("my_bitbake_style_function", d)
  
     Note {
     bb.build.exec_func() can also be used to run shell functions from Python
     code. If you want to run a shell function before a Python function within
     the same task, you can use a parent Python function that calls both
     functions in turn with bb.build.exec_func().
     }
  
     To detect errors from functions executed with bb.build.exec_func(), you
     can catch the bb.build.FuncFailed exception. 
  
     Note {
     Functions in metadata (recipes and classes) should not themselves raise
     bb.build.FuncFailed. Rather, bb.build.FuncFailed should be viewed as a
     general indicator that the called function failed by raising an exception.
     For example, an exception raised by bb.fatal() will be caught inside
     bb.build.exec_func(), and a bb.build.FuncFailed will be raised in
     response.
     }
  
  Due to their simplicity, regular Python functions should be preferred over
  BitBake-style Python functions unless you need a feature specific to
  BitBake-style Python functions.
  
  Regular Python functions in metadata are a more recent invention than
  BitBake-style Python functions, and older code tends to use
  bb.build.exec_func() more often.


Cheers,
Ulf