1 files changed, 188 insertions, 58 deletions

diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index 4bdeedb8d7..a4d837216e 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -228,65 +228,192 @@
                             </note></para></listitem>
                 </orderedlist>
             </para>
+        </section>
 
-            <para>
-                To create layers that are easier to maintain, you should
-                consider the following:
-                <itemizedlist>
-                    <listitem><para>Avoid "overlaying" entire recipes from
-                        other layers in your configuration.
-                        In other words, do not copy an entire recipe into your
-                        layer and then modify it.
-                        Use <filename>.bbappend</filename> files to override the
-                        parts of the recipe you need to modify.
-                        </para></listitem>
-                    <listitem><para>Avoid duplicating include files.
-                        Use <filename>.bbappend</filename> files for each recipe
-                        that uses an include file.
-                        Or, if you are introducing a new recipe that requires
-                        the included file, use the path relative to the original
-                        layer directory to refer to the file.
-                        For example, use
-                        <filename>require recipes-core/somepackage/somefile.inc</filename>
-                        instead of <filename>require somefile.inc</filename>.
-                        If you're finding you have to overlay the include file,
-                        it could indicate a deficiency in the include file in
-                        the layer to which it originally belongs.
-                        If this is the case, you need to address that deficiency
-                        instead of overlaying the include file.
-                        For example, consider how Qt 4 database support plug-ins
-                        are configured.
-                        The Source Directory does not have MySQL or PostgreSQL,
-                        however OpenEmbedded's layer
-                        <filename>meta-oe</filename> does.
-                        Consequently, <filename>meta-oe</filename> uses
-                        <filename>.bbappend</filename> files to modify the
-                        <filename>QT_SQL_DRIVER_FLAGS</filename> variable to
-                        enable the appropriate plugins.
-                        This variable was added to the
-                        <filename>qt4.inc</filename> include file in the Source
-                        Directory specifically to allow the
-                        <filename>meta-oe</filename> layer to be able to control
-                        which plugins are built.</para></listitem>
-                </itemizedlist>
-            </para>
+        <section id='best-practices-to-follow-when-creating-layers'>
+            <title>Best Practices to Follow When Creating Layers</title>
 
             <para>
-                We also recommend the following:
-                <itemizedlist>
-                    <listitem><para>Store custom layers in a Git repository
-                        that uses the
-                        <filename>meta-&lt;layer_name&gt;</filename> format.
-                        </para></listitem>
-                    <listitem><para>Clone the repository alongside other
-                        <filename>meta</filename> directories in the
-                        <link linkend='source-directory'>Source Directory</link>.
-                        </para></listitem>
-                 </itemizedlist>
-                 Following these recommendations keeps your Source Directory and
-                 its configuration entirely inside the Yocto Project's core
-                 base.
+                To create layers that are easier to maintain and that will
+                not impact builds for other machines, you should consider the 
+                information in the following sections.
             </para>
+ 
+            <section id='avoid-overlaying-entire-recipes'>
+                <title>Avoid "Overlaying" Entire Recipes</title>
+
+                <para>
+                    Avoid "overlaying" entire recipes from other layers in your
+                    configuration.
+                    In other words, do not copy an entire recipe into your
+                    layer and then modify it.
+                    Use <filename>.bbappend</filename> files to override the
+                    parts of the recipe you need to modify.
+                </para>
+            </section>
+
+            <section id='avoid-duplicating-include-files'>
+                <title>Avoid Duplicating Include Files</title>
+
+                <para>
+                    Avoid duplicating include files.
+                    Use <filename>.bbappend</filename> files for each recipe
+                    that uses an include file.
+                    Or, if you are introducing a new recipe that requires
+                    the included file, use the path relative to the original
+                    layer directory to refer to the file.
+                    For example, use
+                    <filename>require recipes-core/somepackage/somefile.inc</filename>
+                    instead of <filename>require somefile.inc</filename>.
+                    If you're finding you have to overlay the include file,
+                    it could indicate a deficiency in the include file in
+                    the layer to which it originally belongs.
+                    If this is the case, you need to address that deficiency
+                    instead of overlaying the include file.
+                    For example, consider how support plugins for the Qt 4 
+                    database are configured.
+                    The Source Directory does not have MySQL or PostgreSQL.
+                    However, OpenEmbedded's layer <filename>meta-oe</filename> 
+                    does.
+                    Consequently, <filename>meta-oe</filename> uses
+                    <filename>.bbappend</filename> files to modify the
+                    <filename>QT_SQL_DRIVER_FLAGS</filename> variable to
+                    enable the appropriate plugins.
+                    This variable was added to the <filename>qt4.inc</filename> 
+                    include file in the Source Directory specifically to allow 
+                    the <filename>meta-oe</filename> layer to be able to control
+                    which plugins are built.
+                </para>
+            </section>
+
+            <section id='structure-your-layers'>
+                <title>Structure Your Layers</title>
+
+                <para>
+                    Proper use of overrides within append files and placement 
+                    of machine-specific files within your layer can ensure that 
+                    a build is not using the wrong Metadata and negatively
+                    impacting a build for a different machine.
+                    Following are some examples:
+                    <itemizedlist>
+                        <listitem><para><emphasis>Modifying Variables to support 
+                            a different machine:</emphasis>
+                            Suppose you have a layer named
+                            <filename>meta-one</filename> that adds support 
+                            for building machine "one".
+                            To do so, you use an append file named 
+                            <filename>base-files.bbappend</filename> and 
+                            create a dependency on a file named  
+                            <filename>foo</filename> that contains the 
+                            altered variables:
+                            <literallayout class='monospaced'>
+     <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink> = "foo"
+                            </literallayout>
+                            The dependency is created during any build that 
+                            includes the layer 
+                            <filename>meta-one</filename>.
+                            However, you might not want this dependency 
+                            for all machines.
+                            For example, suppose you are building for 
+                            machine "two" but your 
+                            <filename>bblayers.conf</filename> file has the 
+                            <filename>meta-one</filename> layer included.
+                            During the build, the 
+                            <filename>base-files</filename> for machine 
+                            "two" will also have the dependency on 
+                            <filename>foo</filename>.</para>
+                            <para>To make sure your changes apply only when 
+                            building machine "one", use a machine override 
+                            with the <filename>DEPENDS</filename> statement:
+                            <literallayout class='monospaced'>
+     DEPENDS_one = "foo"
+                            </literallayout>
+                            You should follow the same strategy when using 
+                            <filename>_append</filename> and 
+                            <filename>_prepend</filename> overrides:
+                            <literallayout class='monospaced'>
+     DEPENDS_append_one = " foo"
+     DEPENDS_prepend_one = "foo "
+                            </literallayout>
+                            <note>
+                                Avoiding "+=" and "=+" and using 
+                                machine-specific 
+                                <filename>_append</filename>
+                                and <filename>_prepend</filename> overrides 
+                                is recommended as well.
+                            </note></para></listitem>
+                        <listitem><para><emphasis>Place Machine-Specific Files 
+                            in Machine-Specific Locations:</emphasis>
+                            When you have a base recipe, such as 
+                            <filename>base-files.bb</filename>, that 
+                            contains a 
+                            <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
+                            statement to a file, you can use an append file
+                            to cause the build to use your own version of 
+                            the file.
+                            For example, an append file in your layer at 
+                            <filename>/meta-one/recipes-core/base-files/base-files.bbappend</filename>
+                            could extend  
+                            <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink>
+                            using 
+                            <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
+                            as follows:
+                            <literallayout class='monospaced'>
+     FILESEXTRAPATHS_prepend := "${THISDIR}/${BPN}:"
+                            </literallayout>
+                            The build for machine "one" will pick up your 
+                            machine-specific file as long as you have the 
+                            file in
+                            <filename>/meta-one/recipes-core/base-files/base-files/</filename>.
+                            However, if you are building for a different 
+                            machine and the 
+                            <filename>bblayers.conf</filename> file includes
+                            the <filename>meta-one</filename> layer and 
+                            the location of your machine-specific file is 
+                            the first location where that file is found
+                            according to <filename>FILESPATH</filename>, 
+                            builds for all machines will also use that 
+                            machine-specific file.</para>
+                            <para>You can make sure that a machine-specific
+                            file is used for a particular machine by putting
+                            the file in a subdirectory specific to the 
+                            machine.
+                            For example, rather than placing the file in 
+                            <filename>/meta-one/recipes-core/base-files/base-files/</filename>
+                            as shown above, put it in 
+                            <filename>/meta-one/recipes-core/base-files/base-files/one/</filename>.
+                            Not only does this make sure the file is used  
+                            only when building for machine "one" but the 
+                            build process locates the file more quickly.</para>
+                            <para>In summary, you need to place all files
+                            referenced from <filename>SRC_URI</filename>
+                            in a machine-specific subdirectory within the 
+                            layer in order to restrict those files to 
+                            machine-specific builds.</para></listitem>
+                    </itemizedlist>
+                </para>
+            </section>
+
+            <section id='other-recommendations'>
+                <title>Other Recommendations</title>
+
+                <para>
+                    We also recommend the following:
+                    <itemizedlist>
+                        <listitem><para>Store custom layers in a Git repository
+                            that uses the
+                            <filename>meta-&lt;layer_name&gt;</filename> format.
+                            </para></listitem>
+                        <listitem><para>Clone the repository alongside other
+                            <filename>meta</filename> directories in the
+                            <link linkend='source-directory'>Source Directory</link>.
+                            </para></listitem>
+                     </itemizedlist>
+                     Following these recommendations keeps your Source Directory and
+                     its configuration entirely inside the Yocto Project's core
+                     base.
+                </para>
+            </section>
         </section>
 
         <section id='enabling-your-layer'>
@@ -2469,9 +2596,12 @@
                             If you have distro-specific configuration files
                             that are included by an existing recipe, you should
                             add a <filename>.bbappend</filename> for those.
-                            For general information on how to add recipes to
-                            your layer, see the "<link linkend='creating-your-own-layer'>Creating Your Own Layer</link>"
-                            section.</para></listitem>
+                            For general information and recommendations 
+                            on how to add recipes to your layer, see the 
+                            "<link linkend='creating-your-own-layer'>Creating Your Own Layer</link>"
+                            and
+                            "<link linkend='best-practices-to-follow-when-creating-layers'>Best Practices to Follow When Creating Layers</link>"
+                            sections.</para></listitem>
                         <listitem><para>Add any image recipes that are specific
                             to your distribution.</para></listitem>
                         <listitem><para>Add a <filename>psplash</filename>