summaryrefslogtreecommitdiffstats
path: root/bitbake/doc
diff options
context:
space:
mode:
authorRichard Purdie <richard.purdie@linuxfoundation.org>2014-01-18 14:27:30 +0000
committerRichard Purdie <richard.purdie@linuxfoundation.org>2014-01-27 21:03:21 +0000
commitab18cca2dc65a2d40b92a4c27e114f4ce0b7e074 (patch)
tree1f25203f57ee699fb0fef5c9ccbd59da9386261f /bitbake/doc
parent8705fe23834ec9a164ca21e8c141fded97af28de (diff)
downloadpoky-ab18cca2dc65a2d40b92a4c27e114f4ce0b7e074.tar.gz
bitbake: user-manual-metadata: Add section about running tasks and the environment
(Bitbake rev: b32524643c125c78848630a5ce18d1df36313bc7) Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'bitbake/doc')
-rw-r--r--bitbake/doc/user-manual/user-manual-metadata.xml74
1 files changed, 74 insertions, 0 deletions
diff --git a/bitbake/doc/user-manual/user-manual-metadata.xml b/bitbake/doc/user-manual/user-manual-metadata.xml
index 55b59ebcc1..c38c542a10 100644
--- a/bitbake/doc/user-manual/user-manual-metadata.xml
+++ b/bitbake/doc/user-manual/user-manual-metadata.xml
@@ -480,6 +480,80 @@
480 </para> 480 </para>
481 </section> 481 </section>
482 482
483 <section id='running-a-task'>
484 <title>Running a Task</title>
485
486 <para>
487 Tasks can either be a shell task or a Python task.
488 For shell tasks, BitBake writes a shell script to
489 <filename>${WORKDIR}/temp/run.do_taskname.pid</filename>
490 and then executes the script.
491 The generated shell script contains all the exported variables,
492 and the shell functions with all variables expanded.
493 Output from the shell script goes to the file
494 <filename>${WORKDIR}/temp/log.do_taskname.pid</filename>.
495 Looking at the expanded shell functions in the run file and
496 the output in the log files is a useful debugging technique.
497 </para>
498
499 <para>
500 For Python tasks, BitBake executes the task internally and logs
501 information to the controlling terminal.
502 Future versions of BitBake will write the functions to files
503 similar to the way shell tasks are handled.
504 Logging will be handled in a way similar to shell tasks as well.
505 </para>
506
507 <para>
508 Once all the tasks have been completed BitBake exits.
509 </para>
510
511 <para>
512 When running a task, BitBake tightly controls the execution
513 environment of the build tasks to make
514 sure unwanted contamination from the build machine cannot
515 influence the build.
516 Consequently, if you do want something to get passed into the
517 build task's environment, you must take a few steps:
518 <orderedlist>
519 <listitem><para>
520 Tell BitBake to load what you want from the environment
521 into the data store.
522 You can do so through the
523 <filename>BB_ENV_EXTRAWHITE</filename> variable.
524 For example, assume you want to prevent the build system from
525 accessing your <filename>$HOME/.ccache</filename>
526 directory.
527 The following command tells BitBake to load
528 <filename>CCACHE_DIR</filename> from the environment into
529 the data store:
530 <literallayout class='monospaced'>
531 export BB_ENV_EXTRAWHITE="$BB_ENV_EXTRAWHITE CCACHE_DIR"
532 </literallayout></para></listitem>
533 <listitem><para>
534 Tell BitBake to export what you have loaded into the
535 environment store to the task environment of
536 every running task.
537 Loading something from the environment into the data
538 store (previous step) only makes it available in the datastore.
539 To export it to the task environment of every running task,
540 use a command similar to the following in your
541 <filename>local.conf</filename> or distribution configuration file:
542 <literallayout class='monospaced'>
543 export CCACHE_DIR
544 </literallayout>
545 <note>
546 A side effect of the previous steps is that BitBake
547 records the variable as a dependency of the build process
548 in things like the shared state checksums.
549 If doing so results in unnecessary rebuilds of tasks, you can
550 whitelist the variable so that the shared state code
551 ignores the dependency when it creates checksums.
552 </note></para></listitem>
553 </orderedlist>
554 </para>
555 </section>
556
483 <section id='task-flags'> 557 <section id='task-flags'>
484 <title>Task Flags</title> 558 <title>Task Flags</title>
485 559