ref-manual: Updates to the FILESPATH variable.

Added some more clarity about how this variable works and the
implications for using the default setting from the base.bbclass
file.  Namely, if you are going to have the build system look
for files in your layer and your layer uses an append file,
then you need to also use the FILESEXTRAPATHS variable to
extend FILESPATHS.

(From yocto-docs rev: 2826fa6f9286efb1d5ca6cf85f65266a35bb8cfc)

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

1 files changed, 22 insertions, 11 deletions

diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml
index 1a751a9758..be15a447e6 100644
--- a/documentation/ref-manual/ref-variables.xml
+++ b/documentation/ref-manual/ref-variables.xml
@@ -1191,26 +1191,37 @@ Core layer for images cannot be removed
         <glossentry id='var-FILESPATH'><glossterm>FILESPATH</glossterm>
             <glossdef>
                 <para>
-                    The default set of directories the OpenEmbedded build system uses
-                    when searching for patches and files.
+                    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 <filename>file://</filename> URI in a recipe.
+                    <filename>FILESPATH</filename> in the specified order when 
+                    looking for files and patches specified by each 
+                    <filename>file://</filename> URI in a recipe.
                 </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
+                    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
                     <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>:
                     <literallayout class='monospaced'>
      FILESPATH = "${@base_set_filespath(["${FILE_DIRNAME}/${BP}", \
         "${FILE_DIRNAME}/${BPN}", "${FILE_DIRNAME}/files"], d)}"
                     </literallayout>
-                    Do not hand-edit the <filename>FILESPATH</filename> variable.
-                    If you want to extend the set of pathnames that BitBake uses when searching for
-                    files and patches, use the
-                    <link linkend='var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></link> variable.
+                    <warning>
+                        Do not hand-edit the <filename>FILESPATH</filename> 
+                        variable.
+                    </warning>
+                    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 
+                    <link linkend='var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></link> 
+                    variable.
                 </para>
             </glossdef>
         </glossentry>