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 @@
+
+ Sharing Files Between Recipes
+
+
+ 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.
+
+ 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.
+
+
+
+
+ Recipes should never populate the sysroot directly (i.e. write
+ files into sysroot).
+ Instead, files should be installed into standard locations
+ during the
+ do_install
+ task within the
+ ${D}
+ 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.
+
+
+
+ For information on variables you can use to help control how
+ files sysroot is populated, see the
+ SYSROOT_DIRS,
+ SYSROOT_DIRS_NATIVE,
+ and
+ SYSROOT_DIRS_BLACKLIST
+ variables.
+
+
+
Properly Versioning Pre-Release Recipes
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"
+ SYSROOT_DIRS
+
+ SYSROOT_DIRS[doc] = "Directories that are staged in the sysroot."
+
+
+
+
+ Directories that are staged in the sysroot.
+ By default, the following directories are staged:
+
+ SYSROOT_DIRS = " \
+ ${includedir} \
+ ${libdir} \
+ ${base_libdir} \
+ ${nonarch_base_libdir} \
+ ${datadir} \
+ "
+
+
+
+
+
+ SYSROOT_DIRS_BLACKLIST
+
+ SYSROOT_DIRS_BLACKLIST[doc] = "Directories that should not be staged into sysroot."
+
+
+
+
+ Directories that should not be staged into sysroot.
+ By default, the following directories are not staged:
+
+ SYSROOT_DIRS_BLACKLIST = " \
+ ${mandir} \
+ ${docdir} \
+ ${infodir} \
+ ${datadir}/locale \
+ ${datadir}/applications \
+ ${datadir}/fonts \
+ ${datadir}/pixmaps \
+ "
+
+
+
+
+
+ SYSROOT_DIRS_NATIVE
+
+ SYSROOT_DIRS_NATIVE[doc] = "Extra directories staged for native into sysroot."
+
+
+
+
+ Extra directories staged for native into sysroot.
+ By default, the following directories are staged:
+
+ SYSROOT_DIRS_NATIVE = " \
+ ${bindir} \
+ ${sbindir} \
+ ${base_bindir} \
+ ${base_sbindir} \
+ ${libexecdir} \
+ ${sysconfdir} \
+ ${localstatedir} \
+ "
+
+
+
+
+
SYSROOT_PREPROCESS_FUNCS
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."