summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2011-08-17 16:35:05 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2011-08-23 18:47:01 -0700
commit00d483d65a54b210b581b17196ea37b021eb2623 (patch)
tree2b6d3d86347e48e1124e22cad2b3b9b85d38590b
parent8165eefb1f6946abdaaebbbaf138b9e319e66ae9 (diff)
downloadpoky-00d483d65a54b210b581b17196ea37b021eb2623.tar.gz
documentation/poky-ref-manual/usingpoky.xml: YOCTO #1001 - new section added
YOCTO #1001 - created a new section to address this issue. This is the first draft. Darren to provide review comments. (From yocto-docs rev: fc2aee572cc3e620684533a12a2d8436dc0abe32) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
-rw-r--r--documentation/poky-ref-manual/usingpoky.xml98
1 files changed, 95 insertions, 3 deletions
diff --git a/documentation/poky-ref-manual/usingpoky.xml b/documentation/poky-ref-manual/usingpoky.xml
index c8407bb002..b07ec70fac 100644
--- a/documentation/poky-ref-manual/usingpoky.xml
+++ b/documentation/poky-ref-manual/usingpoky.xml
@@ -200,14 +200,14 @@
200 <title>Debugging Build Failures</title> 200 <title>Debugging Build Failures</title>
201 201
202 <para> 202 <para>
203 The exact method for debugging Poky depends on the nature of the 203 The exact method for debugging Yocto Project build failures depends on the nature of the
204 problem and on the system's area from which the bug originates. 204 problem and on the system's area from which the bug originates.
205 Standard debugging practices such as comparison against the last 205 Standard debugging practices such as comparison against the last
206 known working version with examination of the changes and the re-application of steps 206 known working version with examination of the changes and the re-application of steps
207 to identify the one causing the problem are 207 to identify the one causing the problem are
208 valid for Poky just as they are for any other system. 208 valid for Yocto Project just as they are for any other system.
209 Even though it is impossible to detail every possible potential failure, 209 Even though it is impossible to detail every possible potential failure,
210 here are some general tips to aid in debugging: 210 this section provides some general tips to aid in debugging.
211 </para> 211 </para>
212 212
213 <section id='usingpoky-debugging-taskfailures'> 213 <section id='usingpoky-debugging-taskfailures'>
@@ -328,6 +328,98 @@
328 </para> 328 </para>
329 </section> 329 </section>
330 330
331 <section id='recipe-logging-mechanisms'>
332 <title>Recipe Logging Mechanisms</title>
333 <para>
334 Best practices exist while writing recipes that both log build progress and
335 act on build conditions such as warnings and errors.
336 Depending whether you are creating recipes using Bash or Python, the mechanism
337 differs:
338 <itemizedlist>
339 <listitem><para><emphasis>Python:</emphasis> For Python functions BitBake
340 supports several loglevels: <filename>bb.fatal</filename>,
341 <filename>bb.error</filename>, <filename>bb.warn</filename>,
342 <filename>bb.note</filename>, <filename>bb.plain</filename>,
343 and <filename>bb.debug</filename>.</para></listitem>
344 <listitem><para><emphasis>Bash:</emphasis> For Bash functions you use the
345 <filename>echo</filename> command and prepend a diagnostic string that includes
346 the loglevel followed by a colon character</para></listitem>
347 </itemizedlist>
348 </para>
349
350 <section id='logging-with-python'>
351 <title>Logging With Python</title>
352 <para>
353 When creating recipes using Python and inserting code that handles build logs
354 keep in mind the goal is to have informative logs while keeping the console as
355 "silent" as possible.
356 Also, if you want status messages in the log use the "debug" loglevel.
357 </para>
358
359 <para>
360 Following is sample code from a recipe written in Python.
361 The code handles logging for a function that determines the number of tasks
362 needed to be run:
363 <literallayout class='monospaced'>
364 python do_listtasks() {
365 bb.debug(2, "Starting to figure out the task list")
366 if noteworthy_condition:
367 bb.note("There are 47 tasks to run")
368 bb.debug(2, "Got to point xyz")
369 if warning_trigger:
370 bb.warn("Detected warning_trigger, this might be a problem later.")
371 if recoverable_error:
372 bb.error("Hit recoverable_error, you really need to fix this!")
373 if fatal_error:
374 bb.fatal("fatal_error detected, unable to print the task list")
375 bb.plain("The tasks present are abc")
376 bb.debug(2, "Finished figureing out the tasklist")
377 }
378 </literallayout>
379 </para>
380 </section>
381
382 <section id='logging-with-bash'>
383 <title>Logging With Bash</title>
384 <para>
385 When creating recipes using Bash and inserting code that handles build
386 logs you have the same goals - informative with minimal console output.
387 Use the <filename>echo</filename> command and prepend the diagnostic string
388 with the appropriate loglevel floowed by the colon character.
389 </para>
390
391 <para>
392 For guidance on <filename>echo</filename> usage in Bash recipes, see the
393 <filename>logging.bbclass</filename> file in the
394 <filename>meta/classes</filename> directory of the Yocto Project files.
395 </para>
396
397 <para>
398 Following is sample code from a recipe written in Bash.
399 The code logs the progress of the <filename>do_my_function</filename> function.
400 <literallayout class='monospaced'>
401 do_my_function() {
402 echo "Running do_my_function()"
403 if [ exceptional_condition ]; then
404 echo "NOTE: hit exceptional_condition"
405 fi
406 echo "DEBUG: got to point xyz"
407 if [ warning_trigger ]; then
408 echo "WARNING: detected warning_trigger, this might cause a plroblem later."
409 fi
410 if [ recoverable_error ]; then
411 echo "ERROR: hit recoverable_error, correcting"
412 fi
413 if [ fatal_error ]; then
414 echo "FATAL: fatal_error detected"
415 fi
416 echo "Completed do_my_function"
417 }
418 </literallayout>
419 </para>
420 </section>
421 </section>
422
331 <section id='usingpoky-debugging-others'> 423 <section id='usingpoky-debugging-others'>
332 <title>Other Tips</title> 424 <title>Other Tips</title>
333 <tip> 425 <tip>