summaryrefslogtreecommitdiffstats
path: root/bitbake/doc/bitbake-user-manual
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2016-10-04 09:58:44 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2016-10-06 11:39:37 +0100
commit510157e5793339df80b89f756ed8f675d0f7c420 (patch)
treee71f1f0665933d189720394b7dbccbc17eee7bc5 /bitbake/doc/bitbake-user-manual
parent04128a657ad92b60fba27e4a0748d2af45d0da75 (diff)
downloadpoky-510157e5793339df80b89f756ed8f675d0f7c420.tar.gz
bitbake: 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. (Bitbake rev: e6f12157a210084d1a870832107c910df792f1d9) Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'bitbake/doc/bitbake-user-manual')
-rw-r--r--bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml99
1 files changed, 96 insertions, 3 deletions
diff --git a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml
index 5636a35620..53e182ba61 100644
--- a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml
+++ b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml
@@ -283,7 +283,7 @@
283 functions and BitBake-style Python functions. 283 functions and BitBake-style Python functions.
284 See the 284 See the
285 "<link linkend='shell-functions'>Shell Functions</link>" and 285 "<link linkend='shell-functions'>Shell Functions</link>" and
286 "<link linkend='bitbake-style-python-functions'>BitBake Style Python Functions</link> 286 "<link linkend='bitbake-style-python-functions'>BitBake-Style Python Functions</link>
287 sections for examples. 287 sections for examples.
288 </para> 288 </para>
289 </section> 289 </section>
@@ -1060,7 +1060,7 @@
1060 directly as functions, tasks, or both. 1060 directly as functions, tasks, or both.
1061 They can also be called by other shell functions. 1061 They can also be called by other shell functions.
1062 </para></listitem> 1062 </para></listitem>
1063 <listitem><para><emphasis>BitBake Style Python Functions:</emphasis> 1063 <listitem><para><emphasis>BitBake-Style Python Functions:</emphasis>
1064 Functions written in Python and executed by BitBake or other 1064 Functions written in Python and executed by BitBake or other
1065 Python functions using <filename>bb.build.exec_func()</filename>. 1065 Python functions using <filename>bb.build.exec_func()</filename>.
1066 </para></listitem> 1066 </para></listitem>
@@ -1152,7 +1152,7 @@
1152 </section> 1152 </section>
1153 1153
1154 <section id='bitbake-style-python-functions'> 1154 <section id='bitbake-style-python-functions'>
1155 <title>BitBake Style Python Functions</title> 1155 <title>BitBake-Style Python Functions</title>
1156 1156
1157 <para> 1157 <para>
1158 These functions are written in Python and executed by 1158 These functions are written in Python and executed by
@@ -1261,6 +1261,99 @@
1261 </para> 1261 </para>
1262 </section> 1262 </section>
1263 1263
1264 <section id='bitbake-style-python-functions-versus-python-functions'>
1265 <title>Bitbake-Style Python Functions Versus Python Functions</title>
1266
1267 <para>
1268 Following are some important differences between
1269 BitBake-style Python functions and regular Python
1270 functions defined with "def":
1271 <itemizedlist>
1272 <listitem><para>
1273 Only BitBake-style Python functions can be
1274 <link linkend='tasks'>tasks</link>.
1275 </para></listitem>
1276 <listitem><para>
1277 Overrides and override-style operators can only
1278 be applied to BitBake-style Python functions.
1279 </para></listitem>
1280 <listitem><para>
1281 Only regular Python functions can take arguments
1282 and return values.
1283 </para></listitem>
1284 <listitem><para>
1285 <link linkend='variable-flags'>Variable flags</link>
1286 such as <filename>[dirs]</filename>,
1287 <filename>[cleandirs]</filename>, and
1288 <filename>[lockfiles]</filename> can be used
1289 on BitBake-style Python functions, but not on
1290 regular Python functions.
1291 </para></listitem>
1292 <listitem><para>
1293 BitBake-style Python functions generate a separate
1294 <filename>${</filename><link linkend='var-T'><filename>T</filename></link><filename>}/run.</filename><replaceable>function-name</replaceable><filename>.</filename><replaceable>pid</replaceable>
1295 script that is executed to run the function, and also
1296 generate a log file in
1297 <filename>${T}/log.</filename><replaceable>function-name</replaceable><filename>.</filename><replaceable>pid</replaceable>
1298 if they are executed as tasks.</para>
1299
1300 <para>
1301 Regular Python functions execute "inline" and do not
1302 generate any files in <filename>${T}</filename>.
1303 </para></listitem>
1304 <listitem><para>
1305 Regular Python functions are called with the usual
1306 Python syntax.
1307 BitBake-style Python functions are usually tasks and
1308 are called directly by BitBake, but can also be called
1309 manually from Python code by using the
1310 <filename>bb.build.exec_func()</filename> function.
1311 Here is an example:
1312 <literallayout class='monospaced'>
1313 bb.build.exec_func("my_bitbake_style_function", d)
1314 </literallayout>
1315 <note>
1316 <filename>bb.build.exec_func()</filename> can also
1317 be used to run shell functions from Python code.
1318 If you want to run a shell function before a Python
1319 function within the same task, then you can use a
1320 parent helper Python function that starts by running
1321 the shell function with
1322 <filename>bb.build.exec_func()</filename> and then
1323 runs the Python code.
1324 </note></para>
1325
1326 <para>To detect errors from functions executed with
1327 <filename>bb.build.exec_func()</filename>, you
1328 can catch the <filename>bb.build.FuncFailed</filename>
1329 exception.
1330 <note>
1331 Functions in metadata (recipes and classes) should
1332 not themselves raise
1333 <filename>bb.build.FuncFailed</filename>.
1334 Rather, <filename>bb.build.FuncFailed</filename>
1335 should be viewed as a general indicator that the
1336 called function failed by raising an exception.
1337 For example, an exception raised by
1338 <filename>bb.fatal()</filename> will be caught inside
1339 <filename>bb.build.exec_func()</filename>, and a
1340 <filename>bb.build.FuncFailed</filename> will be raised
1341 in response.
1342 </note>
1343 </para></listitem>
1344 </itemizedlist>
1345 </para>
1346
1347 <para>
1348 Due to their simplicity, you should prefer regular Python functions
1349 over BitBake-style Python functions unless you need a feature specific
1350 to BitBake-style Python functions.
1351 Regular Python functions in metadata are a more recent invention than
1352 BitBake-style Python functions, and older code tends to use
1353 <filename>bb.build.exec_func()</filename> more often.
1354 </para>
1355 </section>
1356
1264 <section id='anonymous-python-functions'> 1357 <section id='anonymous-python-functions'>
1265 <title>Anonymous Python Functions</title> 1358 <title>Anonymous Python Functions</title>
1266 1359