[gnome-continuous-yocto/gnomeostree-3.28-rocko: 3431/8267] ref-manual, dev-manual: Added references to SYSROOT_DIRS

[Emmanuele Bassi <ebassi src gnome org>]

commit 479fbee8408d1b4d3829377b040f4f1e6457b418
Author: Scott Rifenbark <srifenbark gmail com>
Date:   Fri Nov 18 14:34:46 2016 -0800

    ref-manual, dev-manual: Added references to SYSROOT_DIRS
    
    Fixes [YOCTO #10692]
    
    I updated the STAGING_DIR variable description to have a reference
    to the SYSROOT_DIRS variable as well as the "Sharing Files
    Between Recipes" section of the dev-manual.
    
    I also updated the "Sharing Files Between Recipes" section so
    that the role of SYSROOT_DIRS is explained and actually used
    in an example to add another directory.
    
    (From yocto-docs rev: 6539fcf632cfa3f076f874535ee9fc7ac291fbce)
    
    Signed-off-by: Scott Rifenbark <srifenbark gmail com>
    Signed-off-by: Richard Purdie <richard purdie linuxfoundation org>

 .../dev-manual/dev-manual-common-tasks.xml         |   24 ++++++++++++++++---
 documentation/ref-manual/ref-variables.xml         |   15 +++++++++++-
 2 files changed, 34 insertions(+), 5 deletions(-)
---
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml 
b/documentation/dev-manual/dev-manual-common-tasks.xml
index 55a2995..39ce2a2 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -2891,9 +2891,9 @@
                 machine, and a sysroot exists for the build host.
                 <note>
                     You could find the term "staging" used within the Yocto
-                    project regarding files populating sysroot.
-                    The term "staging" was used for previous releases of
-                    the Yocto Project.
+                    project regarding files populating sysroot (e.g. the
+                    <ulink 
url='&YOCTO_DOCS_REF_URL;#var-STAGING_DIR'><filename>STAGING_DIR</filename></ulink>
+                    variable).
                 </note>
             </para>
 
@@ -2906,7 +2906,12 @@
                 task within the
                 <filename>${</filename><ulink 
url='&YOCTO_DOCS_REF_URL;#var-D'><filename>D</filename></ulink><filename>}</filename>
                 directory.
-                A subset of these files automatically populates the sysroot.
+            </para>
+
+            <para>
+                A subset of these files, as defined by the
+                the <ulink 
url='&YOCTO_DOCS_REF_URL;#var-SYSROOT_DIRS'><filename>SYSROOT_DIRS</filename></ulink>
+                variable, automatically populates the sysroot.
                 The reason for this limitation is that almost all files that
                 populate the sysroot are cataloged in manifests in order to
                 ensure the files can be removed later when a recipe is either
@@ -2915,6 +2920,17 @@
             </para>
 
             <para>
+                It is possible to modify the list of directories that populate
+                the sysroot.
+                The following example shows how you could add the
+                <filename>/opt</filename> directory to the list of
+                directories:
+                <literallayout class='monospaced'>
+     SYSROOT_DIRS += "/opt"
+                </literallayout>
+            </para>
+
+            <para>
                 For information on variables you can use to help control how
                 files sysroot is populated, see the
                 <ulink url='&YOCTO_DOCS_REF_URL;#var-SYSROOT_DIRS'><filename>SYSROOT_DIRS</filename></ulink>,
diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml
index 9d6fab0..af1ed84 100644
--- a/documentation/ref-manual/ref-variables.xml
+++ b/documentation/ref-manual/ref-variables.xml
@@ -12692,9 +12692,22 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
                     Specifies the path to the top-level sysroots directory
                     (i.e.
                     <filename>${</filename><link 
linkend='var-TMPDIR'><filename>TMPDIR</filename></link><filename>}/sysroots</filename>).
+                </para>
+
+                <para>
+                    <filename>STAGING_DIR</filename> contains the directories
+                    that are staged into the sysroot by the
+                    <link 
linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link>
+                    task.
+                    See the
+                    <link linkend='var-SYSROOT_DIRS'><filename>SYSROOT_DIRS</filename></link>
+                    variable and the
+                    "<ulink url='&YOCTO_DOCS_DEV_URL;#new-sharing-files-between-recipes'>Sharing Files 
Between Recipes</ulink>"
+                    section for more information.
                     <note>
                         Recipes should never write files directly under
-                        this directory because the OpenEmbedded build system
+                        the <filename>STAGING_DIR</filename> directory because
+                        the OpenEmbedded build system
                         manages the directory automatically.
                         Instead, files should be installed to
                         <filename>${</filename><link 
linkend='var-D'><filename>D</filename></link><filename>}</filename>