documentation/poky-ref-manual/ref-variables.xml: Added CONFFILES and FILES

Added a new glossary entry fro CONFFILES and I updated the existing
description for FILES.  These two variables are inter-twined.  FILES
was a one-liner and definitely needed expansion.

Reported-by: Paul Eggleton <paul.eggleton@linux.intel.com>
(From yocto-docs rev: 6788128c459ccf04f932c2273aca1e6b88f0def0)

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

1 files changed, 80 insertions, 1 deletions

diff --git a/documentation/poky-ref-manual/ref-variables.xml b/documentation/poky-ref-manual/ref-variables.xml
index b4964b3935..5b23076533 100644
--- a/documentation/poky-ref-manual/ref-variables.xml
+++ b/documentation/poky-ref-manual/ref-variables.xml
@@ -224,6 +224,56 @@
             </glossdef>
         </glossentry>
 
+        <glossentry id='var-CONFFILES'><glossterm>CONFFILES</glossterm>
+            <glossdef>
+                <para>
+                    Identifies editable or configurable files that are part of a package.
+                    If the Package Management System (PMS) is updating packages as part of 
+                    the final image packaging, it is possible that files you want unchanged
+                    get overwritten.
+                    In other words, editable files might exist in the package that you do not 
+                    want reset as part of the package update process.
+                    You can use the <filename>CONFFILES</filename> variable to list the files in the 
+                    package that wish to prevent PMS from overwriting during this update process.
+                    The <filename>CONFFILES</filename> variable essentially tells the PMS about 
+                    files in the package that you do not want updated as part of the package 
+                    update process.
+                </para>
+
+                <para>  
+                    To use the <filename>CONFFILES</filename> variable, provide a package name
+                    override that identifies the package.
+                    Then, provide a list of space-separated files or paths that identify the 
+                    editable files you want the PMS to exclude from the update process.
+                    Here is an example:
+                    <literallayout class='monospaced'>                       
+     CONFFILES_${PN} += "/dir1/" "dir2/" "file1" "file2"
+                    </literallayout>
+                </para>
+
+                <para>
+                    A relationship exists between the <filename>CONFFILES</filename> and 
+                    <filename><link linkend='var-FILES'>FILES</link></filename> variables.
+                    The files listed with <filename>CONFFILES</filename> must be a subset of 
+                    the files listed with <filename>FILES</filename>.
+                    Because the files you provide with <filename>CONFFILES</filename> are simply
+                    being identified so that the PMS will not overwrite them, it makes sense that
+                    the files must already be included as part of the package through the 
+                    <filename>FILES</filename> variable.
+                </para>
+
+                <note>
+                    When specifying paths as part of the <filename>CONFFILES</filename> variable, 
+                    it is good practice to use the base, architecture-dependant, and 
+                    architecture-independant variables in the pathnames 
+                    rather than hard-coding the pathnames. 
+                    You can find a list of these variables at the top of the 
+                    <filename>/meta/conf/bitbake.conf</filename> file in the Yocto Project
+                    files directory.
+                </note>
+            </glossdef>
+        </glossentry>
+
         <glossentry id='var-CONFIG_SITE'><glossterm>CONFIG_SITE</glossterm>
             <glossdef>
                 <para>
@@ -484,7 +534,36 @@
 
         <glossentry id='var-FILES'><glossterm>FILES</glossterm>
             <glossdef>
-                <para>The list of directories or files that are placed in packages.</para>
+                <para>
+                    The list of directories or files that are placed in packages.
+                    If some of these files are editable and you know they should not be 
+                    overwritten during the package update process by the Package Management
+                    System (PMS), you can identify these files so that the PMS will not 
+                    overwrite them. 
+                    See the <filename><link linkend='var-CONFFILES'>CONFFILES</link></filename> 
+                    variable for information on how to identify these files to the PMS.
+                </para>
+
+                <para>  
+                    To use the <filename>FILES</filename> variable, provide a package name
+                    override that identifies the package.
+                    Then, provide a list of space-separated files or paths that identify the 
+                    files you want included as part of the package.
+                    Here is an example:
+                    <literallayout class='monospaced'>                       
+     FILES_${PN} += "/dir1/" "dir2/" "file1" "file2"
+                    </literallayout>
+                </para>
+
+                <note>
+                    When specifying paths as part of the <filename>FILES</filename> variable, 
+                    it is good practice to use the base, architecture-dependant, and 
+                    architecture-independant variables in the pathnames 
+                    rather than hard-coding the pathnames. 
+                    You can find a list of these variables at the top of the 
+                    <filename>/meta/conf/bitbake.conf</filename> file in the Yocto Project
+                    files directory.
+                </note>
             </glossdef>
         </glossentry>