10364 2016-10-04 02:27:13 +0000 Suggested documentation to clarify BitBake-style vs. regular Python functions and bb.build.exec_func() 2016-10-04 19:27:09 +0000 1 1 9 Documentation BitBake User Manual bitbake-manual 2.2 x86 Multiple RESOLVED FIXED 04 Oct 2016: RESOLVED Undecided normal 2.2 M4 1 ulfalizer srifenbark bluelightning kergoth ross.burton sgw srifenbark --- --- Done (doc changes complete) oldest_to_newest 66848 0 ulfalizer 2016-10-04 02:27:13 +0000 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 66849 1 ulfalizer 2016-10-04 02:30:50 +0000 As a small nit, there's both "BitBake style" and "BitBake-style" in the manual. Maybe that could be made consistent too. Cheers, Ulf 66850 2 ulfalizer 2016-10-04 02:40:36 +0000 Another small nit... change * Variable flags such as 'dirs', 'cleandirs', and 'lockfiles' can only be used on BitBake-style Python functions. to * Variable flags such as 'dirs', 'cleandirs', and 'lockfiles' can be used on BitBake-style Python functions, but not on regular Python functions. That might make it clearer that they can be used on all BitBake-style Python functions and not just on tasks. Cheers, Ulf 66875 3 srifenbark 2016-10-04 17:02:55 +0000 Ulf, See http://www.yoctoproject.org/docs/2.2/bitbake-user-manual/bitbake-user-manual.html#bitbake-style-python-functions-versus-python-functions for the new section. Regarding the BitBake Style / BitBake-Style controversy.... I made everything BitBake-Style. There were just a few occurrences. Check things out.. thanks, Scott 66881 4 ulfalizer 2016-10-04 17:52:38 +0000 Looks good. just a few nits: * Maybe "variable flags" could be linkified in "variable flags such as [dirs], [cleandirs], ..." Seems a bit weird to start a sentence with a link, but whatever. :) * The "linkification brackets" accidentally got left in in ${[T]}/... in two places. Should be ${T}/..., and the first one could be linkified. * Maybe the first note makes things sound a bit more complicated than they are. Could we do this version instead? 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, then you can use a parent helper Python function that starts by running the shell function with bb.build.exec_func() and then runs the Python code. * Maybe the final two paragraphs could be merged into one. Thanks, Ulf 66884 5 srifenbark 2016-10-04 19:21:26 +0000 Ulf, See http://www.yoctoproject.org/docs/2.2/bitbake-user-manual/bitbake-user-manual.html#bitbake-style-python-functions-versus-python-functions for the changes. Thanks, Scott 66885 6 ulfalizer 2016-10-04 19:24:26 +0000 Looks good to me! Thanks, Ulf 66887 7 srifenbark 2016-10-04 19:27:09 +0000 Thanks, Setting to RESOLVED and putting the doc flag to "done." Scott