ref-manual: Added information for OEROOT and build environment

Fixes [YOCTO #4980]

Added a new glossary entry for OEROOT.

Added significant information to the local.conf and bblayers.conf
reference sections to describe how the root build directory is
derived.

Also, some unrelated formatting to the DL_DIR variable description
was mixed in here because I forgot to commit that separatey and it
lives in the same variables.xml file.

(From yocto-docs rev: c397a31f5b0d3f6257657119a4e81b4fbdc3800c)

Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

1 files changed, 39 insertions, 14 deletions

diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml
index b3562db578..764c8072da 100644
--- a/documentation/ref-manual/ref-variables.xml
+++ b/documentation/ref-manual/ref-variables.xml
@@ -1230,37 +1230,40 @@ Core layer for images cannot be removed
         <glossentry id='var-DL_DIR'><glossterm>DL_DIR</glossterm>
             <glossdef>
                 <para>
-                    The central download directory used by the build process to store downloads.
-                    You can set this directory by defining the <filename>DL_DIR</filename>
-                    variable in the <filename>/conf/local.conf</filename> file.
+                    The central download directory used by the build process to 
+                    store downloads.
+                    You can set this directory by defining the 
+                    <filename>DL_DIR</filename> variable in the 
+                    <filename>/conf/local.conf</filename> file.
                     This directory is self-maintaining and you should not have
                     to touch it.
-                    By default, the directory is <filename>downloads</filename> in the
+                    By default, the directory is <filename>downloads</filename> 
+                    in the
                     <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
                     <literallayout class='monospaced'>
      #DL_DIR ?= "${TOPDIR}/downloads"
                     </literallayout>
-                    To specify a different download directory, simply uncomment the line
-                    and provide your directory.
+                    To specify a different download directory, simply remove 
+                    the comment from the line and provide your directory.
                 </para>
 
                 <para>
-                    During a first build, the system downloads many different source code
-                    tarballs from various upstream projects.
+                    During a first build, the system downloads many different 
+                    source code tarballs from various upstream projects.
                     Downloading can take a while, particularly if your network
                     connection is slow.
                     Tarballs are all stored in the directory defined by
-                    <filename>DL_DIR</filename> and the build system looks there first
-                    to find source tarballs.
+                    <filename>DL_DIR</filename> and the build system looks there 
+                    first to find source tarballs.
                     <note>
-                        When wiping and rebuilding, you can preserve this directory to speed
-                        up this part of subsequent builds.
+                        When wiping and rebuilding, you can preserve this 
+                        directory to speed up this part of subsequent builds.
                     </note>
                 </para>
 
                 <para>
-                    You can safely share this directory between multiple builds on the
-                    same development machine.
+                    You can safely share this directory between multiple builds 
+                    on the same development machine.
                     For additional information on how the build process gets
                     source files when working behind a firewall or proxy server,
                     see this specific question in the
@@ -3353,6 +3356,28 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
             </glossdef>
         </glossentry>
 
+        <glossentry id='var-OEROOT'><glossterm>OEROOT</glossterm>
+            <glossdef>
+                <para>
+                    The directory from which the top-level build environment
+                    setup script is sourced.
+                    The Yocto Project makes two top-level build environment
+                    setup scripts available: 
+                    <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>
+                    and 
+                    <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>.
+                    When you run one of these scripts, the 
+                    <filename>OEROOT</filename> variable resolves to the 
+                    directory that holds the script.
+                </para>
+
+                <para>
+                    For additional information on how this variable is used, 
+                    see the initialization scripts.
+                </para>
+            </glossdef>
+        </glossentry>
+
         <glossentry id='var-OLDEST_KERNEL'><glossterm>OLDEST_KERNEL</glossterm>
             <glossdef>
                 <para>