ref-manual: Updated the FILESEXTRAPATHS variable

Added an example to show machine overrides.

(From yocto-docs rev: d0c54caf2a2a6ccb9a6fb38b77c9827b66b9ff10)

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

1 files changed, 28 insertions, 2 deletions

diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml
index c85efc65ff..2b561584eb 100644
--- a/documentation/ref-manual/ref-variables.xml
+++ b/documentation/ref-manual/ref-variables.xml
@@ -4742,7 +4742,8 @@
                     in a directory that has the same name as the corresponding
                     append file.
                     <note>
-                        <para>When extending <filename>FILESEXTRAPATHS</filename>,
+                        <para>When extending
+                        <filename>FILESEXTRAPATHS</filename>,
                         be sure to use the immediate expansion
                         (<filename>:=</filename>) operator.
                         Immediate expansion makes sure that BitBake evaluates
@@ -4751,6 +4752,7 @@
                         some later time when expansion might result in a
                         directory that does not contain the files you need.
                         </para>
+
                         <para>Also, include the trailing separating colon
                         character if you are prepending.
                         The trailing colon character is necessary because you
@@ -4768,13 +4770,37 @@
                 </para>
 
                 <para>
-                    Here is a final example that specifically adds three paths:
+                    This next example specifically adds three paths:
                     <literallayout class='monospaced'>
      FILESEXTRAPATHS_prepend := "path_1:path_2:path_3:"
                     </literallayout>
                 </para>
 
                 <para>
+                    A final example shows how you can extend the search path
+                    and include a
+                    <link linkend='var-MACHINE'><filename>MACHINE</filename></link>-specific
+                    override, which is useful in a BSP layer:
+                    <literallayout class='monospaced'>
+     FILESEXTRAPATHS_prepend_intel-x86-common := "${THISDIR}/${PN}:"
+                    </literallayout>
+                    The previous statement appears in the
+                    <filename>linux-yocto-dev.bbappend</filename> file, which
+                    is found in the Yocto Project
+                    <link linkend='source-repositories'>Source Repositories</link>
+                    in
+                    <filename>meta-intel/common/recipes-kernel/linux</filename>.
+                    Here, the machine override is a special
+                    <link linkend='var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></link>
+                    definition for multiple <filename>meta-intel</filename>
+                    machines.
+                    <note>
+                        For a layer that supports a single BSP, the override
+                        could just be the value of <filename>MACHINE</filename>.
+                    </note>
+                </para>
+
+                <para>
                     By prepending paths in <filename>.bbappend</filename>
                     files, you allow multiple append files that reside in
                     different layers but are used for the same recipe to