ref-manual, dev-manual: Updates for "staging" discussion and variables.

Fixes [YOCTO #8631]

These fixes cover the following:

 * New glossary entry for SYSROOT_DIRS
 * New glossary entry for SYSROOT_DIRS_NATIVE
 * New glossary entry for SYSROOT_DIRS_BLACKLIST
 * New section titled "Sharing Files Between Recipes" in the
   dev-manual's "Writing a New Recipe" section.

(From yocto-docs rev: e541a3c8967f51b903d9dd7978009f4fa7c2f014)

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

2 files changed, 120 insertions, 0 deletions

diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index 3c2012cf19..5e77516144 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -2875,6 +2875,56 @@
             </para>
         </section>
 
+        <section id='new-sharing-files-between-recipes'>
+            <title>Sharing Files Between Recipes</title>
+
+            <para>
+                Recipes often need to use files provided by other recipes on
+                the build host.
+                For example, an application linking to a common library needs
+                access to the library itself and its associated headers.
+                The way this access is accomplished is by populating sysroot
+                with files.
+                One sysroot exists per "machine" for which the image is
+                being built.
+                In practical terms, this means a sysroot exists for the target
+                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.
+                </note>
+            </para>
+
+            <para>
+                Recipes should never populate the sysroot directly (i.e. write
+                files into sysroot).
+                Instead, files should be installed into standard locations
+                during the
+                <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink>
+                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.
+                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
+                modified or removed.
+                Thus, the sysroot is able to remain free from stale files.
+            </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>,
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-SYSROOT_DIRS_NATIVE'><filename>SYSROOT_DIRS_NATIVE</filename></ulink>,
+                and
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-SYSROOT_DIRS_BLACKLIST'><filename>SYSROOT_DIRS_BLACKLIST</filename></ulink>
+                variables.
+            </para>
+        </section>
+
         <section id='properly-versioning-pre-release-recipes'>
             <title>Properly Versioning Pre-Release Recipes</title>
 
diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml
index 99f3e03446..1ec804d100 100644
--- a/documentation/ref-manual/ref-variables.xml
+++ b/documentation/ref-manual/ref-variables.xml
@@ -13095,6 +13095,76 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
             </glossdef>
         </glossentry>
 
+        <glossentry id='var-SYSROOT_DIRS'><glossterm>SYSROOT_DIRS</glossterm>
+            <info>
+                SYSROOT_DIRS[doc] = "Directories that are staged in the sysroot."
+            </info>
+            <glossdef>
+                <para role="glossdeffirst">
+<!--                <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
+                    Directories that are staged in the sysroot.
+                    By default, the following directories are staged:
+                    <literallayout class='monospaced'>
+     SYSROOT_DIRS = " \
+         ${includedir} \
+         ${libdir} \
+         ${base_libdir} \
+         ${nonarch_base_libdir} \
+         ${datadir} \
+     "
+                    </literallayout>
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-SYSROOT_DIRS_BLACKLIST'><glossterm>SYSROOT_DIRS_BLACKLIST</glossterm>
+            <info>
+                SYSROOT_DIRS_BLACKLIST[doc] = "Directories that should not be staged into sysroot."
+            </info>
+            <glossdef>
+                <para role="glossdeffirst">
+<!--                <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
+                    Directories that should not be staged into sysroot.
+                    By default, the following directories are not staged:
+                    <literallayout class='monospaced'>
+     SYSROOT_DIRS_BLACKLIST = " \
+         ${mandir} \
+         ${docdir} \
+         ${infodir} \
+         ${datadir}/locale \
+         ${datadir}/applications \
+         ${datadir}/fonts \
+         ${datadir}/pixmaps \
+     "
+                     </literallayout>
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-SYSROOT_DIRS_NATIVE'><glossterm>SYSROOT_DIRS_NATIVE</glossterm>
+            <info>
+                SYSROOT_DIRS_NATIVE[doc] = "Extra directories staged for native into sysroot."
+            </info>
+            <glossdef>
+                <para role="glossdeffirst">
+<!--                <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
+                    Extra directories staged for native into sysroot.
+                    By default, the following directories are staged:
+                    <literallayout class='monospaced'>
+     SYSROOT_DIRS_NATIVE = " \
+         ${bindir} \
+         ${sbindir} \
+         ${base_bindir} \
+         ${base_sbindir} \
+         ${libexecdir} \
+         ${sysconfdir} \
+         ${localstatedir} \
+     "
+                    </literallayout>
+                </para>
+            </glossdef>
+        </glossentry>
+
         <glossentry id='var-SYSROOT_PREPROCESS_FUNCS'><glossterm>SYSROOT_PREPROCESS_FUNCS</glossterm>
             <info>
                 SYSROOT_PREPROCESS_FUNCS[doc] = "A list of functions to execute after files are staged into the sysroot. These functions are usually used to apply additional processing on the staged files, or to stage additional files."