path: root/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml
diff options
authorScott Rifenbark <srifenbark@gmail.com>2016-10-04 09:58:44 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2016-10-06 11:39:32 +0100
commite6f12157a210084d1a870832107c910df792f1d9 (patch)
treef0140e83752259e47dce90f4b1de72602f77b8c3 /doc/bitbake-user-manual/bitbake-user-manual-metadata.xml
parent67d5501d5fd6b7ac3ee9ad97962fcf8a41d00cff (diff)
bitbake-user-manual: Added new section on BB-style functions
Fixes [YOCTO #10364] Added a new section titled "Bitbake-Style Python Functions Versus Python Functions". This section describes differences for the user between the two types of functions. Also, cleaned up a consistency problem with the terms "BitBake style" and "BitBake-style". I used the latter throughout the manual. Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'doc/bitbake-user-manual/bitbake-user-manual-metadata.xml')
1 files changed, 96 insertions, 3 deletions
diff --git a/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml b/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml
index 5636a356..53e182ba 100644
--- a/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml
+++ b/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml
@@ -283,7 +283,7 @@
functions and BitBake-style Python functions.
See the
"<link linkend='shell-functions'>Shell Functions</link>" and
- "<link linkend='bitbake-style-python-functions'>BitBake Style Python Functions</link>
+ "<link linkend='bitbake-style-python-functions'>BitBake-Style Python Functions</link>
sections for examples.
@@ -1060,7 +1060,7 @@
directly as functions, tasks, or both.
They can also be called by other shell functions.
- <listitem><para><emphasis>BitBake Style Python Functions:</emphasis>
+ <listitem><para><emphasis>BitBake-Style Python Functions:</emphasis>
Functions written in Python and executed by BitBake or other
Python functions using <filename>bb.build.exec_func()</filename>.
@@ -1152,7 +1152,7 @@
<section id='bitbake-style-python-functions'>
- <title>BitBake Style Python Functions</title>
+ <title>BitBake-Style Python Functions</title>
These functions are written in Python and executed by
@@ -1261,6 +1261,99 @@
+ <section id='bitbake-style-python-functions-versus-python-functions'>
+ <title>Bitbake-Style Python Functions Versus Python Functions</title>
+ <para>
+ Following are some important differences between
+ BitBake-style Python functions and regular Python
+ functions defined with "def":
+ <itemizedlist>
+ <listitem><para>
+ Only BitBake-style Python functions can be
+ <link linkend='tasks'>tasks</link>.
+ </para></listitem>
+ <listitem><para>
+ Overrides and override-style operators can only
+ be applied to BitBake-style Python functions.
+ </para></listitem>
+ <listitem><para>
+ Only regular Python functions can take arguments
+ and return values.
+ </para></listitem>
+ <listitem><para>
+ <link linkend='variable-flags'>Variable flags</link>
+ such as <filename>[dirs]</filename>,
+ <filename>[cleandirs]</filename>, and
+ <filename>[lockfiles]</filename> can be used
+ on BitBake-style Python functions, but not on
+ regular Python functions.
+ </para></listitem>
+ <listitem><para>
+ BitBake-style Python functions generate a separate
+ <filename>${</filename><link linkend='var-T'><filename>T</filename></link><filename>}/run.</filename><replaceable>function-name</replaceable><filename>.</filename><replaceable>pid</replaceable>
+ script that is executed to run the function, and also
+ generate a log file in
+ <filename>${T}/log.</filename><replaceable>function-name</replaceable><filename>.</filename><replaceable>pid</replaceable>
+ if they are executed as tasks.</para>
+ <para>
+ Regular Python functions execute "inline" and do not
+ generate any files in <filename>${T}</filename>.
+ </para></listitem>
+ <listitem><para>
+ 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
+ <filename>bb.build.exec_func()</filename> function.
+ Here is an example:
+ <literallayout class='monospaced'>
+ bb.build.exec_func("my_bitbake_style_function", d)
+ </literallayout>
+ <note>
+ <filename>bb.build.exec_func()</filename> 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
+ <filename>bb.build.exec_func()</filename> and then
+ runs the Python code.
+ </note></para>
+ <para>To detect errors from functions executed with
+ <filename>bb.build.exec_func()</filename>, you
+ can catch the <filename>bb.build.FuncFailed</filename>
+ exception.
+ <note>
+ Functions in metadata (recipes and classes) should
+ not themselves raise
+ <filename>bb.build.FuncFailed</filename>.
+ Rather, <filename>bb.build.FuncFailed</filename>
+ should be viewed as a general indicator that the
+ called function failed by raising an exception.
+ For example, an exception raised by
+ <filename>bb.fatal()</filename> will be caught inside
+ <filename>bb.build.exec_func()</filename>, and a
+ <filename>bb.build.FuncFailed</filename> will be raised
+ in response.
+ </note>
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Due to their simplicity, you should prefer regular Python functions
+ 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
+ <filename>bb.build.exec_func()</filename> more often.
+ </para>
+ </section>
<section id='anonymous-python-functions'>
<title>Anonymous Python Functions</title>