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>

documentation/ref-manual/ref-structure.xml

@@ -334,47 +334,123 @@
         <title><filename>build/conf/local.conf</filename></title>
 
         <para>
-            This file contains all the local user configuration for your build environment.
+            This configuration file contains all the local user configurations 
-            If there is no <filename>local.conf</filename> present, it is created from
+            for your build environment.
-            <filename>local.conf.sample</filename>.
+            The <filename>local.conf</filename> file contains documentation on 
-            The <filename>local.conf</filename> file contains documentation on the various configuration options.
+            the various configuration options.
-            Any variable set here overrides any variable set elsewhere within the environment unless
+            Any variable set here overrides any variable set elsewhere within 
-            that variable is hard-coded within a file (e.g. by using '=' instead of '?=').
+            the environment unless that variable is hard-coded within a file 
-            Some variables are hard-coded for various reasons but these variables are
+            (e.g. by using '=' instead of '?=').
-            relatively rare.
+            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>
+            The <filename>bblayers.conf</filename> file uses the
-            is not present, it is created from <filename>bblayers.conf.sample</filename> when
+            <link linkend='var-BBLAYERS'><filename>BBLAYERS</filename></link> 
-            you <filename>source</filename> the environment setup script.
+            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>
-            The <filename>bblayers.conf</filename> file uses the
+            If <filename>bblayers.conf</filename> is not present when you 
-            <link linkend='var-BBLAYERS'><filename>BBLAYERS</filename></link> variable to
+            start the build, the OpenEmbedded build system creates it from 
-            list the layers BitBake tries to find.
+            <filename>bblayers.conf.sample</filename> when
-            The file uses the
+            you <filename>source</filename> the top-level build environment 
-            <link linkend='var-BBLAYERS_NON_REMOVABLE'><filename>BBLAYERS_NON_REMOVABLE</filename></link>
+            setup script (i.e.
-            variable to list layers that must not be removed.
+            <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>
 

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.
+                    The central download directory used by the build process to 
-                    You can set this directory by defining the <filename>DL_DIR</filename>
+                    store downloads.
-                    variable in the <filename>/conf/local.conf</filename> file.
+                    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
+                    To specify a different download directory, simply remove 
-                    and provide your directory.
+                    the comment from the line and provide your directory.
                 </para>
 
                 <para>
-                    During a first build, the system downloads many different source code
+                    During a first build, the system downloads many different 
-                    tarballs from various upstream projects.
+                    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
+                    <filename>DL_DIR</filename> and the build system looks there 
-                    to find source tarballs.
+                    first to find source tarballs.
                     <note>
-                        When wiping and rebuilding, you can preserve this directory to speed
+                        When wiping and rebuilding, you can preserve this 
-                        up this part of subsequent builds.
+                        directory to speed up this part of subsequent builds.
                     </note>
                 </para>
 
                 <para>
-                    You can safely share this directory between multiple builds on the
+                    You can safely share this directory between multiple builds 
-                    same development machine.
+                    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>