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>

2 files changed, 135 insertions, 34 deletions

diff --git a/documentation/ref-manual/ref-structure.xml b/documentation/ref-manual/ref-structure.xml
index 3133e8dc6d..13803f5a41 100644
--- a/documentation/ref-manual/ref-structure.xml
+++ b/documentation/ref-manual/ref-structure.xml
@@ -334,48 +334,124 @@
         <title><filename>build/conf/local.conf</filename></title>
 
         <para>
-            This file contains all the local user configuration for your build environment.
-            If there is no <filename>local.conf</filename> present, it is created from
-            <filename>local.conf.sample</filename>.
-            The <filename>local.conf</filename> file contains documentation on the various configuration options.
-            Any variable set here overrides any variable set elsewhere within the environment unless
-            that variable is hard-coded within a file (e.g. by using '=' instead of '?=').
-            Some variables are hard-coded for various reasons but these variables are
-            relatively rare.
+            This configuration file contains all the local user configurations 
+            for your build environment.
+            The <filename>local.conf</filename> file contains documentation on 
+            the various configuration options.
+            Any variable set here overrides any variable set elsewhere within 
+            the environment unless that variable is hard-coded within a file 
+            (e.g. by using '=' instead of '?=').
+            Some variables are hard-coded for various reasons but these 
+            variables are relatively rare.
         </para>
 
         <para>
-            Edit this file to set the <filename><link linkend='var-MACHINE'>MACHINE</link></filename>
+            Edit this file to set the 
+            <filename><link linkend='var-MACHINE'>MACHINE</link></filename>
             for which you want to build, which package types you wish to use
             (<link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>),
             the location from which you want to downloaded files
             (<filename><link linkend='var-DL_DIR'>DL_DIR</link></filename>),
             and how you want your host machine to use resources
-            (<link linkend='var-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename></link> and
+            (<link linkend='var-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename></link> 
+            and
             <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>).
         </para>
+
+        <para>
+            If <filename>local.conf</filename> is not present when you 
+            start the build, the OpenEmbedded build system creates it from 
+            <filename>local.conf.sample</filename> when
+            you <filename>source</filename> the top-level build environment 
+            setup script (i.e.
+            <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>
+            or 
+            <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>).
+        </para>
+
+        <para>
+            The source <filename>local.conf.sample</filename> file used 
+            depends on the <filename>$TEMPLATECONF</filename> script variable,
+            which defaults to <filename>/meta-yocto/conf</filename>
+            when you are building from the Yocto Project development 
+            environment and defaults to <filename>/meta/conf</filename> when 
+            you are building from the OpenEmbedded Core environment.
+            Because the script variable points to the source of the 
+            <filename>local.conf.sample</filename> file, this implies that 
+            you can configure your build environment from any layer by setting     
+            the variable in the top-level build environment setup script as 
+            follows:
+            <literallayout class='monospaced'>
+     TEMPLATECONF=&lt;your_layer&gt;/conf
+            </literallayout>
+            Once the build process gets the sample file, it uses 
+            <filename>sed</filename> to substitute final 
+            <filename>${</filename><link linkend='var-OEROOT'><filename>OEROOT</filename></link><filename>}</filename> 
+            values for all <filename>##OEROOT##</filename> values.
+            <note>
+                You can see how the <filename>TEMPLATECONF</filename> variable
+                is used by looking at the       
+                <filename>/scripts/oe-setup-builddir</filename> script in the 
+                <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
+                You can find the Yocto Project version of the 
+                <filename>local.conf.sample</filename> file in the 
+                <filename>/meta-yocto/conf</filename> directory.                
+            </note>
+        </para>
     </section>
 
     <section id='structure-build-conf-bblayers.conf'>
         <title><filename>build/conf/bblayers.conf</filename></title>
 
         <para>
-            This file defines
+            This configuration file defines
             <ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>layers</ulink>,
             which are directory trees, traversed (or walked) by BitBake.
-            If <filename>bblayers.conf</filename>
-            is not present, it is created from <filename>bblayers.conf.sample</filename> when
-            you <filename>source</filename> the environment setup script.
-        </para>
-
-        <para>
             The <filename>bblayers.conf</filename> file uses the
-            <link linkend='var-BBLAYERS'><filename>BBLAYERS</filename></link> variable to
-            list the layers BitBake tries to find.
-            The file uses the
+            <link linkend='var-BBLAYERS'><filename>BBLAYERS</filename></link> 
+            variable to list the layers BitBake tries to find, and uses the
             <link linkend='var-BBLAYERS_NON_REMOVABLE'><filename>BBLAYERS_NON_REMOVABLE</filename></link>
             variable to list layers that must not be removed.
         </para>
+
+        <para>
+            If <filename>bblayers.conf</filename> is not present when you 
+            start the build, the OpenEmbedded build system creates it from 
+            <filename>bblayers.conf.sample</filename> when
+            you <filename>source</filename> the top-level build environment 
+            setup script (i.e.
+            <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>
+            or 
+            <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>).
+        </para>
+
+        <para>
+            The source <filename>bblayers.conf.sample</filename> file used 
+            depends on the <filename>$TEMPLATECONF</filename> script variable,
+            which defaults to <filename>/meta-yocto/conf</filename>
+            when you are building from the Yocto Project development 
+            environment and defaults to <filename>/meta/conf</filename> when 
+            you are building from the OpenEmbedded Core environment.
+            Because the script variable points to the source of the 
+            <filename>bblayers.conf.sample</filename> file, this implies that 
+            you can base your build from any layer by setting the variable in
+            the top-level build environment setup script as follows:
+            <literallayout class='monospaced'>
+     TEMPLATECONF=&lt;your_layer&gt;/conf
+            </literallayout>
+            Once the build process gets the sample file, it uses 
+            <filename>sed</filename> to substitute final 
+            <filename>${</filename><link linkend='var-OEROOT'><filename>OEROOT</filename></link><filename>}</filename> 
+            values for all <filename>##OEROOT##</filename> values.
+            <note>
+                You can see how the <filename>TEMPLATECONF</filename> variable
+                <filename>/scripts/oe-setup-builddir</filename> script in the 
+                <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
+                You can find the Yocto Project version of the 
+                <filename>bblayers.conf.sample</filename> file in the 
+                <filename>/meta-yocto/conf</filename> directory.                
+            </note>
+        </para>
     </section>
 
     <section id='structure-build-conf-sanity_info'>
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>