ref-manual: Updates to FILESPATH and IMAGE_FSTYPES variables.

Fixes [YOCTO #13112]
Fixes [YOCTO #13115]

* FILESPATH: Added a detailed example of how to use the variable
  to set machine-specific configurations.  Also, noted the default
  behavior of using FILESOVERRIDES to automatically extend
  FILESPATH. Did some rewriting as well.

* IMAGE_FSTYPES: Updated the note to not be exclusive to "live"
  images.  The behavior applies to many images.

(From yocto-docs rev: 46e3f2545c45ba5391603f9ffa1c87896d472df6)

Signed-off-by: Scott Rifenbark <srifenbark@gmail.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

1 files changed, 69 insertions, 26 deletions

diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml
index 9e51b7591c..ed65727fc7 100644
--- a/documentation/ref-manual/ref-variables.xml
+++ b/documentation/ref-manual/ref-variables.xml
@@ -5041,17 +5041,45 @@
             <glossdef>
                 <para role="glossdeffirst">
 <!--                <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
-                    The default set of directories the OpenEmbedded build system
-                    uses when searching for patches and files.
-                    During the build process, BitBake searches each directory in
-                    <filename>FILESPATH</filename> in the specified order when
-                    looking for files and patches specified by each
+                    The default set of directories the OpenEmbedded build
+                    system uses when searching for patches and files.
+                </para>
+
+                <para>
+                    During the build process, BitBake searches each directory
+                    in <filename>FILESPATH</filename> in the specified order
+                    when looking for files and patches specified by each
                     <filename>file://</filename> URI in a recipe's
                     <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
                     statements.
                 </para>
 
                 <para>
+                    You can take advantage of this searching behavior in
+                    useful ways.
+                    For example, consider a case where the following
+                    directory structure exists for general and machine-specific
+                    configurations:
+                    <literallayout class='monospaced'>
+     files/defconfig
+     files/MACHINEA/defconfig
+     files/MACHINEB/defconfig
+                    </literallayout>
+                    Also in the example, the <filename>SRC_URI</filename>
+                    statement contains "file://defconfig".
+                    Given this scenario, you can set
+                    <link linkend='var-MACHINE'><filename>MACHINE</filename></link>
+                    to "MACHINEA" and cause the build system to use files
+                    from <filename>files/MACHINEA</filename>.
+                    Set <filename>MACHINE</filename> to "MACHINEB" and the
+                    build system uses files from
+                    <filename>files/MACHINEB</filename>.
+                    Finally, for any machine other than "MACHINEA" and
+                    "MACHINEB", the build system uses files from
+                    <filename>files/defconfig</filename>.
+                </para>
+
+                <para>
                     The default value for the <filename>FILESPATH</filename>
                     variable is defined in the <filename>base.bbclass</filename>
                     class found in <filename>meta/classes</filename> in the
@@ -5060,23 +5088,37 @@
      FILESPATH = "${@base_set_filespath(["${FILE_DIRNAME}/${BP}", \
         "${FILE_DIRNAME}/${BPN}", "${FILE_DIRNAME}/files"], d)}"
                     </literallayout>
-                    <note>
-                        Do not hand-edit the <filename>FILESPATH</filename>
-                        variable.
-                        If you want the build system to look in directories
-                        other than the defaults, extend the
-                        <filename>FILESPATH</filename> variable by using the
-                        <link linkend='var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></link>
-                        variable.
+                    The <filename>FILESPATH</filename> variable is automatically
+                    extended using the overrides from the
+                    <link linkend='var-FILESOVERRIDES'><filename>FILESOVERRIDES</filename></link>
+                    variable.
+                    <note><title>Notes</title>
+                        <itemizedlist>
+                            <listitem><para>
+                                Do not hand-edit the
+                                <filename>FILESPATH</filename> variable.
+                                If you want the build system to look in
+                                directories other than the defaults, extend the
+                                <filename>FILESPATH</filename> variable by
+                                using the
+                                <link linkend='var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></link>
+                                variable.
+                                </para></listitem>
+                            <listitem><para>
+                                Be aware that the default
+                                <filename>FILESPATH</filename> directories do
+                                not map to directories in custom layers
+                                where append files
+                                (<filename>.bbappend</filename>) are used.
+                                If you want the build system to find patches
+                                or files that reside with your append files,
+                                you need to extend the
+                                <filename>FILESPATH</filename> variable by
+                                using the <filename>FILESEXTRAPATHS</filename>
+                                variable.
+                                </para></listitem>
+                        </itemizedlist>
                     </note>
-                    Be aware that the default <filename>FILESPATH</filename>
-                    directories do not map to directories in custom layers
-                    where append files (<filename>.bbappend</filename>)
-                    are used.
-                    If you want the build system to find patches or files
-                    that reside with your append files, you need to extend
-                    the <filename>FILESPATH</filename> variable by using
-                    the <filename>FILESEXTRAPATHS</filename> variable.
                 </para>
 
                 <para>
@@ -6076,11 +6118,12 @@
                 <note><title>Notes</title>
                     <itemizedlist>
                         <listitem><para>
-                            If you add "live" to
-                            <filename>IMAGE_FSTYPES</filename> inside an image
-                            recipe, be sure that you do so prior to the
-                            "inherit image" line of the recipe or the live
-                            image will not build.
+                            If an image recipe uses the "inherit image" line
+                            and you are setting
+                            <filename>IMAGE_FSTYPES</filename> inside the
+                            recipe, you must set
+                            <filename>IMAGE_FSTYPES</filename> prior to
+                            using the "inherit image" line.
                             </para></listitem>
                         <listitem><para>
                             Due to the way the OpenEmbedded build system