diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml
index 6551ff6b90..753279cb5b 100644
--- a/documentation/ref-manual/ref-variables.xml
+++ b/documentation/ref-manual/ref-variables.xml
@@ -12696,9 +12696,13 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
Specifies the path to the sysroot directory for the system
that the component is built to run on (the system that hosts
the component).
- This sysroot is the one that the recipe's
+ For most recipes, this sysroot is the one that the recipe's
do_populate_sysroot
task copies files into.
+ Exceptions include -native recipes,
+ where the do_populate_sysroot task
+ instead uses
+ STAGING_DIR_NATIVE.
Depending on the type of recipe and the build target,
STAGING_DIR_HOST can have the
following values:
@@ -12718,6 +12722,33 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
"${STAGING_DIR}/${MULTIMACH_HOST_SYS}".
+
+ -native recipes are not installed
+ into host paths like such as /usr.
+ Rather, these recipes are installed into
+ STAGING_DIR_NATIVE.
+ When compiling -native recipes,
+ standard build environment variables such as
+ CPPFLAGS
+ and
+ CFLAGS
+ are set up so that both host paths and
+ STAGING_DIR_NATIVE are searched
+ for libraries and headers using, for example,
+ GCC's -isystem option.
+
+ This emphasizes that the
+ STAGING_DIR* variables should be
+ viewed as input variables by tasks such as
+ do_configure,
+ do_compile,
+ and
+ do_install.
+ Having the real system root correspond to
+ STAGING_DIR_HOST makes conceptual
+ sense for -native recipes, as
+ they make use of host headers and libraries.
+