bitbake-user-manual: Enhance environment variable discussion.

Fixes [YOCTO #8567]

Updated the variable list describing the variables that affect
how environment variables are handled.  Also updated the section
on how those variables are passed.

Signed-off-by: Scott Rifenbark <srifenbark@gmail.com>

2 files changed, 43 insertions, 20 deletions

diff --git a/doc/bitbake-user-manual/bitbake-user-manual-execution.xml b/doc/bitbake-user-manual/bitbake-user-manual-execution.xml
index fa52e2989..b1b72e0aa 100644
--- a/doc/bitbake-user-manual/bitbake-user-manual-execution.xml
+++ b/doc/bitbake-user-manual/bitbake-user-manual-execution.xml
@@ -42,9 +42,9 @@
                 <literallayout class='monospaced'>
      $ grep processor /proc/cpuinfo
                 </literallayout>
-                This command returns the number of processors, which takes into 
-                account hyper-threading. 
-                Thus, a quad-core build host with hyper-threading most likely 
+                This command returns the number of processors, which takes into
+                account hyper-threading.
+                Thus, a quad-core build host with hyper-threading most likely
                 shows eight processors, which is the value you would then assign to
                 <filename>BB_NUMBER_THREADS</filename>.
             </para>
@@ -116,16 +116,35 @@
             Prior to parsing configuration files, Bitbake looks
             at certain variables, including:
             <itemizedlist>
-                <listitem><para><link linkend='var-BB_ENV_WHITELIST'><filename>BB_ENV_WHITELIST</filename></link></para></listitem>
-                <listitem><para><link linkend='var-BB_PRESERVE_ENV'><filename>BB_PRESERVE_ENV</filename></link></para></listitem>
-                <listitem><para><link linkend='var-BB_ENV_EXTRAWHITE'><filename>BB_ENV_EXTRAWHITE</filename></link></para></listitem>
+                <listitem><para>
+                    <link linkend='var-BB_ENV_WHITELIST'><filename>BB_ENV_WHITELIST</filename></link>
+                    </para></listitem>
+                <listitem><para>
+                    <link linkend='var-BB_ENV_EXTRAWHITE'><filename>BB_ENV_EXTRAWHITE</filename></link>
+                    </para></listitem>
+                <listitem><para>
+                    <link linkend='var-BB_PRESERVE_ENV'><filename>BB_PRESERVE_ENV</filename></link>
+                    </para></listitem>
+                <listitem><para>
+                    <link linkend='var-BB_ORIGENV'><filename>BB_ORIGENV</filename></link>
+                    </para></listitem>
                 <listitem><para>
                     <link linkend='var-BITBAKE_UI'><filename>BITBAKE_UI</filename></link>
                     </para></listitem>
             </itemizedlist>
-            You can find information on how to pass environment variables into the BitBake
-            execution environment in the
-            "<link linkend='passing-information-into-the-build-task-environment'>Passing Information Into the Build Task Environment</link>" section.
+            The first four variables in this list relate to how BitBake treats shell
+            environment variables during task execution.
+            By default, BitBake cleans the environment variables and provides tight
+            control over the shell execution environment.
+            However, through the use of these first four variables, you can
+            apply your control regarding the
+            environment variables allowed to be used by BitBake in the shell
+            during execution of tasks.
+            See the
+            "<link linkend='passing-information-into-the-build-task-environment'>Passing Information Into the Build Task Environment</link>"
+            section and the information about these variables in the
+            variable glossary for more information on how they work and
+            on how to use them.
         </para>
 
         <para>
diff --git a/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml b/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml
index 61daadea9..cfa85b379 100644
--- a/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml
+++ b/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml
@@ -1107,10 +1107,18 @@
             <title>Passing Information Into the Build Task Environment</title>
 
             <para>
-                When running a task, BitBake tightly controls the execution
+                When running a task, BitBake tightly controls the shell execution
                 environment of the build tasks to make
                 sure unwanted contamination from the build machine cannot
                 influence the build.
+                <note>
+                    By default, BitBake cleans the environment to include only those
+                    things exported or listed in its whitelist to ensure that the build
+                    environment is reproducible and consistent.
+                    You can prevent this "cleaning" by setting the
+                    <link linkend='var-BB_PRESERVE_ENV'><filename>BB_PRESERVE_ENV</filename></link>
+                    variable.
+                </note>
                 Consequently, if you do want something to get passed into the
                 build task environment, you must take these two steps:
                 <orderedlist>
@@ -1118,14 +1126,16 @@
                         Tell BitBake to load what you want from the environment
                         into the datastore.
                         You can do so through the
+                        <link linkend='var-BB_ENV_WHITELIST'><filename>BB_ENV_WHITELIST</filename></link>
+                        and
                         <link linkend='var-BB_ENV_EXTRAWHITE'><filename>BB_ENV_EXTRAWHITE</filename></link>
-                        variable.
+                        variables.
                         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 datastore:
+                        The following command "whitelists" the environment variable
+                        <filename>CCACHE_DIR</filename> causing BitBack to allow that
+                        variable into the datastore:
                         <literallayout class='monospaced'>
      export BB_ENV_EXTRAWHITE="$BB_ENV_EXTRAWHITE CCACHE_DIR"
                         </literallayout></para></listitem>
@@ -1174,12 +1184,6 @@
                 The previous example returns <filename>BAR</filename> from the original
                 execution environment.
             </para>
-
-            <para>
-                By default, BitBake cleans the environment to include only those
-                things exported or listed in its whitelist to ensure that the build
-                environment is reproducible and consistent.
-            </para>
         </section>
     </section>