summaryrefslogtreecommitdiffstats
path: root/documentation/ref-manual/usingpoky.xml
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2016-07-16 12:51:53 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2016-07-19 15:04:52 +0100
commitaae4c2a629d5314a1ccf17e87827adb080cbbe53 (patch)
tree6ef0f0cc6ab8e3775e16606ac8fddbbaef7b48b9 /documentation/ref-manual/usingpoky.xml
parent451334a841971ee21bce705a4bae4506b5444fde (diff)
downloadpoky-aae4c2a629d5314a1ccf17e87827adb080cbbe53.tar.gz
ref-manual: Updated the "Recipe Logging Mechanisms" section
Fixes [YOCTO #9950] Added more detail on the functions for logging. (From yocto-docs rev: b7ed4d84ae5221765201fe661af3741fb01da738) Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/ref-manual/usingpoky.xml')
-rw-r--r--documentation/ref-manual/usingpoky.xml66
1 files changed, 53 insertions, 13 deletions
diff --git a/documentation/ref-manual/usingpoky.xml b/documentation/ref-manual/usingpoky.xml
index 3a6b5a1a85..f94e3a79ff 100644
--- a/documentation/ref-manual/usingpoky.xml
+++ b/documentation/ref-manual/usingpoky.xml
@@ -356,24 +356,64 @@
356 <section id='recipe-logging-mechanisms'> 356 <section id='recipe-logging-mechanisms'>
357 <title>Recipe Logging Mechanisms</title> 357 <title>Recipe Logging Mechanisms</title>
358 <para> 358 <para>
359 Best practices exist while writing recipes that both log build progress and 359 Best practices exist while writing recipes that both log build
360 act on build conditions such as warnings and errors. 360 progress and act on build conditions such as warnings and errors.
361 Both Python and Bash language bindings exist for the logging mechanism: 361 For Python functions, the following logging functions exist.
362 All of these functions log to
363 <filename>${T}/log.do_</filename><replaceable>task</replaceable>,
364 and can also log to standard output (stdout) with the right
365 settings:
362 <itemizedlist> 366 <itemizedlist>
363 <listitem><para><emphasis>Python:</emphasis> For Python functions, BitBake 367 <listitem><para>
364 supports several loglevels: <filename>bb.fatal</filename>, 368 <filename>bb.plain(</filename><replaceable>msg</replaceable><filename>)</filename>:
365 <filename>bb.error</filename>, <filename>bb.warn</filename>, 369 Writes <replaceable>msg</replaceable> as is to the log while
366 <filename>bb.note</filename>, <filename>bb.plain</filename>, 370 also logging to stdout.
367 and <filename>bb.debug</filename>.</para></listitem> 371 </para></listitem>
368 <listitem><para><emphasis>Bash:</emphasis> For Bash functions, the same set 372 <listitem><para>
369 of loglevels exist and are accessed with a similar syntax: 373 <filename>bb.note(</filename><replaceable>msg</replaceable><filename>)</filename>:
370 <filename>bbfatal</filename>, <filename>bberror</filename>, 374 Writes "NOTE: <replaceable>msg</replaceable>" to the log.
371 <filename>bbwarn</filename>, <filename>bbnote</filename>, 375 Also logs to stdout if BitBake is called with "-v".
372 <filename>bbplain</filename>, and <filename>bbdebug</filename>.</para></listitem> 376 </para></listitem>
377 <listitem><para>
378 <filename>bb.debug(</filename><replaceable>level</replaceable><filename>,&nbsp;</filename><replaceable>msg</replaceable><filename>)</filename>:
379 Writes "DEBUG: <replaceable>msg</replaceable>" to the log.
380 Also logs to stdout if the log level is greater than or
381 equal to <replaceable>level</replaceable>.
382 See the
383 "<ulink url='&YOCTO_DOCS_BB_URL;#usage-and-syntax'>-D</ulink>"
384 option in the BitBake User Manual for more information.
385 </para></listitem>
386 <listitem><para>
387 <filename>bb.warn(</filename><replaceable>msg</replaceable><filename>)</filename>:
388 Writes "WARNING: <replaceable>msg</replaceable>" to the log
389 while also logging to stdout.
390 </para></listitem>
391 <listitem><para>
392 <filename>bb.error(</filename><replaceable>msg</replaceable><filename>)</filename>:
393 Writes "ERROR: <replaceable>msg</replaceable>" to the log
394 while also logging to stdout.
395 <note>
396 Calling this function does not cause the task to fail.
397 </note>
398 </para></listitem>
399 <listitem><para>
400 <filename>bb.fatal(</filename><replaceable>msg</replaceable><filename>)</filename>:
401 This logging function is similar to
402 <filename>bb.error(</filename><replaceable>msg</replaceable><filename>)</filename>
403 but also causes the calling task to fail.
404 </para></listitem>
373 </itemizedlist> 405 </itemizedlist>
374 </para> 406 </para>
375 407
376 <para> 408 <para>
409 The same logging functions are also available in shell functions,
410 under the names
411 <filename>bbplain</filename>, <filename>bbnote</filename>,
412 <filename>bbdebug</filename>, <filename>bbwarn</filename>,
413 <filename>bberror</filename>, and <filename>bbfatal</filename>.
414 </para>
415
416 <para>
377 For guidance on how logging is handled in both Python and Bash recipes, see the 417 For guidance on how logging is handled in both Python and Bash recipes, see the
378 <filename>logging.bbclass</filename> file in the 418 <filename>logging.bbclass</filename> file in the
379 <filename>meta/classes</filename> folder of the 419 <filename>meta/classes</filename> folder of the