Bug 13112

Summary: FILESPATH and FILESOVERRIDES documentation lacks key detail
Product: [Documentation] Reference Reporter: Richard Purdie <richard.purdie>
Component: handbookAssignee: Scott Rifenbark <srifenbark>
Status: RESOLVED FIXED QA Contact:
Severity: normal    
Priority: Medium+ CC: poky.doc.watcher, poky.watcher, srifenbark
Version: 2.7   
Target Milestone: 2.7 M2   
Hardware: x86   
OS: Multiple   
URL: 02 January 2019: ACCECPTED
Whiteboard: 18 February 2019: RESOLVED
OS type for building Yocto: --- Type of Regression: ---
Verified: Documentation change: Done (doc changes complete)

Description Richard Purdie 2019-01-02 21:50:15 UTC 
https://www.yoctoproject.org/docs/latest/ref-manual/ref-manual.html#var-FILESOVERRIDES

https://www.yoctoproject.org/docs/latest/ref-manual/ref-manual.html#var-FILESPATH

These two variables need to reference each other and include an example of how these combine to provide really powerful behavior.

The FILESPATH variable needs to mention that it is extended automatically using the overrides from FILESOVERRIDES.

I'd also suggest an example is added, for example, if you put:

"file://defconfig" into SRC_URI, then have the directory structure:

files/defconfig
files/MACHINEA/defconfig
files/MACHINEB/defconfig

then MACHINE=MACHINEA will use the file from files/MACHINEA, MACHINE=MACHINEB will use the one from files/MACHINEB and any other machine would use the one from files/.
Comment 1 Scott Rifenbark 2019-01-03 23:39:57 UTC 
Richard, 

Look at https://yoctoproject.org/docs/2.7/ref-manual/ref-manual.html#var-FILESPATH for updates to FILESPATH.  I am holding off on FILESOVERRIDES until FILESPATH is good.

Thanks, 
Scott
Comment 2 Richard Purdie 2019-02-14 16:37:03 UTC 
Scott,

I think to make most sense the ordering needs tweaking. Can you move the last two paragraphs ("The default value for the ..." and "The FILESPATH variable is automatically ") before the example?

This is because the example uses FILESOVERRIDES as well. If you do that I think this is good.

Cheers,

Richard
Comment 3 Scott Rifenbark 2019-02-15 18:23:32 UTC 
Richard, 

See https://yoctoproject.org/docs/2.7/ref-manual/ref-manual.html#var-FILESPATH for the re-ordering.  

I also added a bit to the front of the https://yoctoproject.org/docs/2.7/ref-manual/ref-manual.html#var-FILESOVERRIDES variable.

Let me know if all this is good and I will close the bug out.

Thanks, 
Scott
Comment 4 Richard Purdie 2019-02-16 10:37:45 UTC 
Looks good to me, I'd just add a comment to FILESOVERRIDES to see FILESPATH for an example of how it works.
Comment 5 Scott Rifenbark 2019-02-19 01:03:05 UTC 
Richard, 

See https://yoctoproject.org/docs/2.7/ref-manual/ref-manual.html#var-FILESOVERRIDES for the reference to the FILESPATH description.

I am going to set this to RESOLVED and put the doc flag to "done."

Thanks, 
Scott