dev-manual: Added new section on "Best Practices"

Fixes [YOCTO #5037]

The information to fix this bug was very similar to some
"best practices" and "recommendations" information that was
currently buried in a section that described how to create a
layer.  So, since the new information for this bug fix increased
the amount of information significantly, I have pulled out the
existing "recommendations" and "best practices" information and
combined it with this new information and placed it in its
own section dedicated to just that.  The information still
resides in the main section that introduces and discusses
layers and their creation.

This is a first draft of the section.  It is under review.

(From yocto-docs rev: 066de04511afb0641278f3fda4e97718b3ed5c47)

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

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>