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.