ref-manual, dev-manual: Updates for custom template configuration directory.

Fixes [YOCTO #5895]

I created a new section in the dev-manual titles
"Creating a Custom Template Configuration Directory" that describes
how the build system uses the template local.conf and bblayers.conf
and conf-notes.txt files as a basis when creating the real
deals in the build directory's conf folder.  The context of this
is so that the user can create their own directory with their own
template files for repeated configurations and to create a custom
conf-notes.txt file should they want the setup scripts to display
some custom list of targets.

I also modified the two script references in the ref-manual for
oe-init-build-env and oe-init-build-env-memres.  I needed to
link to the "how-to" section and added a bit in there about how
the scripts go about forming the conf files in the build directory.

(From yocto-docs rev: c07fb7082fe08387bbc546b2a23620dedc7127b8)

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

2 files changed, 137 insertions, 4 deletions

diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index 3af40c2392..4a58a6f490 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -888,6 +888,119 @@
         </section>
     </section>
 
+    <section id='creating-a-custom-template-configuration-directory'>
+        <title>Creating a Custom Template Configuration Directory</title>
+
+        <para>
+            You might find yourself repeating the same configurations for
+            a particular build or group of builds.
+            If so, rather than repeatedly editing your
+            <filename>local.conf</filename> and possibly your
+            <filename>bblayers.conf</filename>, you can set up a
+            custom directory that has your configurations, and then
+            point the OpenEmbedded build system to that directory to find
+            the configurations.
+        </para>
+
+        <para>
+            The OpenEmbedded build system uses the environment variable
+            <filename>TEMPLATECONF</filename> to point to the directory
+            from which it gathers configuration information that ultimately
+            ends up in the
+            <link linkend='build-directory'>Build Directory's</link>
+            <filename>conf</filename> directory.
+            By default, <filename>TEMPLATECONF</filename> points here:
+            <literallayout class='monospaced'>
+     TEMPLATECONF=${TEMPLATECONF:-meta-yocto/conf}
+            </literallayout>
+            This is the directory that the build system finds templates
+            with which to build some key configuration files.
+            If you look at this directory, you will see the
+            <filename>bblayers.conf.sample</filename>,
+            <filename>local.conf.sample</filename>, and
+            <filename>site.conf.sample</filename> configuration files.
+            The build system uses these files to form the respective
+            <filename>bblayers.conf</filename>,
+            <filename>local.conf</filename>, and the
+            <filename>site.conf</filename> configuration files it places in
+            the <filename>conf</filename> directory with the
+            Build Directory.
+        </para>
+
+        <para>
+            To override these default configuration files with
+            configurations you want used with every build, simply point the
+            <filename>TEMPLATECONF</filename> to your directory.
+            The <filename>TEMPLATECONF</filename> variable is set in the
+            <filename>.templateconf</filename> file, which is in the
+            top-level
+            <link linkend='source-directory'>Source Directory</link>
+            folder (e.g. <filename>poky</filename>).
+            Edit the <filename>.templateconf</filename> so that it points
+            to your directory.
+            Best practices dictate that you should keep your
+            template configuration directory in your custom distribution layer.
+            For example, suppose you have a layer named
+            <filename>meta-mylayer</filename> located in your home directory
+            and you want your template configuration directory named
+            <filename>myconf</filename>.
+            Changing the <filename>.templateconf</filename> as follows
+            causes the OpenEmbedded build system to look in your directory
+            and base its configuration files on the
+            <filename>*.sample</filename> configuration files it finds.
+            The final configuration files (i.e.
+            <filename>local.conf</filename> and
+            <filename>bblayers.conf</filename> ultimately still end up in
+            your Build Directory, but they are based on your
+            <filename>*.sample</filename> files.
+            <literallayout class='monospaced'>
+     TEMPLATECONF=${TEMPLATECONF:-meta-mylayer/myconf}
+            </literallayout>
+        </para>
+
+        <para>
+            Aside from the <filename>*.sample</filename> configuration files,
+            the <filename>conf-notes.txt</filename> also resides in the
+            default <filename>meta-yocto/conf</filename> directory.
+            The scripts that set up the build environment
+            (i.e.
+            <ulink url="&YOCTO_DOCS_REF_URL;#structure-core-script"><filename>&OE_INIT_FILE;</filename></ulink>
+            and
+            <ulink url="&YOCTO_DOCS_REF_URL;#structure-memres-core-script"><filename>oe-init-build-env-memres</filename></ulink>)
+            use this file to display BitBake targets as part of the script
+            output.
+            Customizing this <filename>conf-notes.txt</filename> file is a
+            good way to make sure your list of custom targets appears
+            as part of the script's output.
+        </para>
+
+        <para>
+            Here is output from either of the setup scripts by default:
+            <literallayout class='monospaced'>
+     $ source oe-init-build-env-memres
+     No port specified, using dynamically selected port
+
+     ### Shell environment set up for builds. ###
+
+     You can now run 'bitbake &lt;target&gt;'
+
+     Common targets are:
+         core-image-minimal
+         core-image-sato
+         meta-toolchain
+         adt-installer
+         meta-ide-support
+            </literallayout>
+        </para>
+
+        <para>
+            Changing the listed common targets is as easy as editing your
+            version of <filename>conf-notes.txt</filename> in your
+            custom template configuration directory and making sure you
+            have <filename>TEMPLATECONF</filename> pointing to it.
+        </para>
+    </section>
+
     <section id='usingpoky-extend-customimage'>
         <title>Customizing Images</title>
 
diff --git a/documentation/ref-manual/ref-structure.xml b/documentation/ref-manual/ref-structure.xml
index 1549d90357..c849dbda33 100644
--- a/documentation/ref-manual/ref-structure.xml
+++ b/documentation/ref-manual/ref-structure.xml
@@ -240,8 +240,10 @@
             Should you have custom distributions, it is very easy to modify
             this configuration file to include your targets for your
             distribution.
-            Simply edit the list within the file and when you run the
-            environment setup script you see your customized list of targets.
+            See the
+            "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-custom-template-configuration-directory'>Creating a Custom Template Configuration Directory</ulink>"
+            section in the Yocto Project Development Manual for more
+            information.
         </para>
 
         <para>
@@ -258,6 +260,14 @@
             <literallayout class='monospaced'>
      $ source &OE_INIT_FILE; ~/mybuilds
             </literallayout>
+            The OpenEmbedded build system uses the template configuration
+            files, which are found by default in the
+            <filename>meta-yocto/conf</filename> directory in the
+            <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
+            See the
+            "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-custom-template-configuration-directory'>Creating a Custom Template Configuration Directory</ulink>"
+            section in the Yocto Project Development Manual for more
+            information.
             <note>
                 The OpenEmbedded build system does not support file or directory names that
                 contain spaces.
@@ -349,8 +359,10 @@
             Should you have custom distributions, it is very easy to modify
             this configuration file to include your targets for your
             distribution.
-            Simply edit the list within the file and when you run the
-            environment setup script you see your customized list of targets.
+            See the
+            "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-custom-template-configuration-directory'>Creating a Custom Template Configuration Directory</ulink>"
+            section in the Yocto Project Development Manual for more
+            information.
         </para>
 
         <para>
@@ -368,6 +380,14 @@
             <literallayout class='monospaced'>
      $ source oe-init-build-env-memres ~/mybuilds
             </literallayout>
+            The OpenEmbedded build system uses the template configuration
+            files, which are found by default in the
+            <filename>meta-yocto/conf</filename> directory in the
+            <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
+            See the
+            "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-custom-template-configuration-directory'>Creating a Custom Template Configuration Directory</ulink>"
+            section in the Yocto Project Development Manual for more
+            information.
             <note>
                 The OpenEmbedded build system does not support file or
                 directory names that contain spaces.