1 files changed, 43 insertions, 1 deletions

diff --git a/documentation/poky-ref-manual/ref-bitbake.xml b/documentation/poky-ref-manual/ref-bitbake.xml
index 6851fbf603..930b0a23f7 100644
--- a/documentation/poky-ref-manual/ref-bitbake.xml
+++ b/documentation/poky-ref-manual/ref-bitbake.xml
@@ -260,8 +260,50 @@
         <para>
             Once all the tasks have been completed BitBake exits.
         </para> 
-    </section>
 
+        <para>
+            When running a task, BitBake tightly controls the execution environment 
+            of the build tasks to make sure unwanted contamination from the build machine
+            cannot influence the build. 
+            Consequently, if you do want something to get passed into the build 
+            task's environment, you must take a few steps:
+            <orderedlist>
+                <listitem><para>Tell BitBake to load what you want from the environment
+                    into the data store. 
+                    You can do so through the <filename>BB_ENV_WHITELIST</filename>
+                    variable.
+                    For example, assume you want to prevent the build system from 
+                    accessing your <filename>$HOME/.ccache</filename> directory.
+                    The following command tells BitBake to load 
+                    <filename>CCACHE_DIR</filename> from the environment into the data
+                    store:
+                    <literallayout class='monospaced'>
+     export BB_ENV_EXTRAWHITE="$BB_ENV_EXTRAWHITE CCACHE_DIR" 
+                    </literallayout></para></listitem>
+                <listitem><para>Tell BitBake to export what you have loaded into the 
+                    environment store to the task environment of every running task.
+                    Loading something from the environment into the data store
+                    (previous step) only makes it available in the datastore. 
+                    To export it to the task environment of every running task,
+                    use a command similar to the following in your 
+                    <filename>local.conf</filename> or distro configuration file:
+                    <literallayout class='monospaced'>
+     export CCACHE_DIR
+                    </literallayout></para></listitem>
+            </orderedlist>
+        </para>
+
+        <note>
+            A side effect of the previous steps is that BitBake records the variable
+            as a dependency of the build process in things like the shared state
+            checksums. 
+            If doing so results in unnecessary rebuilds of tasks, you can whitelist the 
+            variable so that the shared state code ignores the dependency when it creates
+            checksums.
+            For information on this process, see the <filename>BB_HASHBASE_WHITELIST</filename>
+            example in <xref linkend='checksums'>Checksums (Signatures)</xref>.
+        </note>
+    </section>
 
     <section id='ref-bitbake-commandline'>
         <title>BitBake Command Line</title>