ref-manual, dev-manual: Clarification of "native" and "sdknative"

Fixes [YOCTO #8620]

I went through and made some judgement calls on the use of
"native" and "sdknative".  I tried to make sure that the reader
understood the real meaning of these terms.

(From yocto-docs rev: d711e8c6dfb32a4ad79e9d11dbf44fbc759d0245)

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

8 files changed, 98 insertions, 71 deletions

diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index e0db037454..ba182acaf4 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -3603,10 +3603,11 @@
                 <title>Additional Implementation Details</title>
 
                 <para>
-                    Different packaging systems have different levels of native Multilib
-                    support.
-                    For the RPM Package Management System, the following implementation details
-                    exist:
+                    Different packaging systems have different levels of
+                    native Multilib support (i.e. support for the host build
+                    machine).
+                    For the RPM Package Management System, the following
+                    implementation details exist:
                     <itemizedlist>
                         <listitem><para>A unique architecture is defined for the Multilib packages,
                             along with creating a unique deploy folder under
@@ -3823,7 +3824,8 @@
                         in the form generated by the build system.
                         </para></listitem>
                     <listitem><para>
-                        You must build several native tools:
+                        You must build several native tools, which are tools
+                        built to run on the build system:
                         <literallayout class='monospaced'>
      $ bitbake parted-native dosfstools-native mtools-native
                         </literallayout>
@@ -6375,8 +6377,9 @@
                     developers when building for multiple machines.
                     When you use the same <filename>TMPDIR</filename> for
                     multiple machine builds, the OpenEmbedded build system can
-                    reuse the existing native and often cross-recipes for
-                    multiple machines.
+                    reuse the existing native (i.e. host system) and often
+                    cross-recipes (i.e. <filename>nativesdk</filename>
+                    for multiple machines.
                     Thus, build time decreases.
                     <note>
                         If
@@ -7583,6 +7586,7 @@
                             run the test suite by using a single command
                             such as <filename>make check</filename>.
                             However, the native <filename>make check</filename>
+                            that runs on the host system
                             builds and runs on the same computer, while
                             cross-compiling requires that the package is built
                             on the host but executed on the target.
@@ -8169,7 +8173,8 @@
                         specific to or dependent on the target
                         architecture:</emphasis>
                         You can work around these attempts by using native
-                        tools to accomplish the same tasks, or
+                        tools, which run on the host system,
+                        to accomplish the same tasks, or
                         by alternatively running the processes under QEMU,
                         which has the <filename>qemu_run_binary</filename>
                         function.
diff --git a/documentation/dev-manual/dev-manual-start.xml b/documentation/dev-manual/dev-manual-start.xml
index db989b7bfa..9f349adcdd 100644
--- a/documentation/dev-manual/dev-manual-start.xml
+++ b/documentation/dev-manual/dev-manual-start.xml
@@ -341,14 +341,17 @@
     </para>
 
     <para>
-        Using a pre-built binary is ideal for developing software applications to run on your
-        target hardware.
-        To do this, you need to be able to access the appropriate cross-toolchain tarball for
-        the architecture on which you are developing.
-        If you are using an SDK type image, the image ships with the complete toolchain native to
-        the architecture.
-        If you are not using an SDK type image, you need to separately download and
-        install the stand-alone Yocto Project cross-toolchain tarball.
+        Using a pre-built binary is ideal for developing software
+        applications to run on your target hardware.
+        To do this, you need to be able to access the appropriate
+        cross-toolchain tarball for the architecture on which you are
+        developing.
+        If you are using an SDK type image, the image ships with the complete
+        toolchain native to the architecture (i.e. a toolchain designed to
+        run on the
+        <ulink url='&YOCTO_DOCS_REF_URL;#var-SDKMACHINE'><filename>SDKMACHINE</filename></ulink>).
+        If you are not using an SDK type image, you need to separately download
+        and install the stand-alone Yocto Project cross-toolchain tarball.
     </para>
 
     <para>
diff --git a/documentation/ref-manual/faq.xml b/documentation/ref-manual/faq.xml
index 08e0fb170b..3137639d9a 100644
--- a/documentation/ref-manual/faq.xml
+++ b/documentation/ref-manual/faq.xml
@@ -791,7 +791,7 @@
     <qandaentry>
         <question>
             <para>
-                The files provided by my <filename>-native</filename> recipe do
+                The files provided by my <filename>*-native</filename> recipe do
                 not appear to be available to other recipes.
                 Files are missing from the native sysroot, my recipe is
                 installing to the wrong place, or I am getting permissions
diff --git a/documentation/ref-manual/introduction.xml b/documentation/ref-manual/introduction.xml
index 57e4a25853..750d9c681c 100644
--- a/documentation/ref-manual/introduction.xml
+++ b/documentation/ref-manual/introduction.xml
@@ -450,7 +450,9 @@
      $ sh poky-glibc-x86_64-buildtools-tarball-x86_64-buildtools-nativesdk-standalone-&DISTRO;.sh
                         </literallayout>
                         During execution, a prompt appears that allows you to
-                        choose the installation directory.
+                        choose the installation directory for these tools
+                        designed to run on the target machine
+                        (<link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>).
                         For example, you could choose the following:
                         <literallayout class='monospaced'>
      /home/<replaceable>your-username</replaceable>/buildtools
@@ -530,7 +532,8 @@
                    <listitem><para>
                        On the machine that does not meet the requirements,
                        run the <filename>.sh</filename> file
-                       to install the tools.
+                       to install the tools built to run on the target machine
+                       (<link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>).
                        Here is an example:
                        <literallayout class='monospaced'>
      $ sh poky-glibc-x86_64-buildtools-tarball-x86_64-buildtools-nativesdk-standalone-&DISTRO;.sh
diff --git a/documentation/ref-manual/migration.xml b/documentation/ref-manual/migration.xml
index 45ac041d92..62f792bf7b 100644
--- a/documentation/ref-manual/migration.xml
+++ b/documentation/ref-manual/migration.xml
@@ -97,13 +97,14 @@
 
             <para>
                 The shared state cache (sstate-cache), as pointed to by
-                <link linkend='var-SSTATE_DIR'><filename>SSTATE_DIR</filename></link>, by default
-                now has two-character subdirectories to prevent issues arising
-                from too many files in the same directory.
-                Also, native sstate-cache packages will go into a subdirectory named using
+                <link linkend='var-SSTATE_DIR'><filename>SSTATE_DIR</filename></link>,
+                by default now has two-character subdirectories to prevent
+                issues arising from too many files in the same directory.
+                Also, native sstate-cache packages, which are built to run
+                on the host system, will go into a subdirectory named using
                 the distro ID string.
-                If you copy the newly structured sstate-cache to a mirror location
-                (either local or remote) and then point to it in
+                If you copy the newly structured sstate-cache to a mirror
+                location (either local or remote) and then point to it in
                 <link linkend='var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></link>,
                 you need to append "PATH" to the end of the mirror URL so that
                 the path used by BitBake before the mirror substitution is
@@ -191,7 +192,9 @@
                 The suffix <filename>nativesdk</filename> is now implemented
                 as a prefix, which simplifies a lot of the packaging code for
                 <filename>nativesdk</filename> recipes.
-                All custom <filename>nativesdk</filename> recipes and any
+                All custom <filename>nativesdk</filename> recipes, which are
+                recipes built on the host system to create packages for the
+                target machine, and any
                 references need to be updated to use
                 <filename>nativesdk-*</filename> instead of
                 <filename>*-nativesdk</filename>.
diff --git a/documentation/ref-manual/ref-classes.xml b/documentation/ref-manual/ref-classes.xml
index 7ba9a9770f..f994a2269d 100644
--- a/documentation/ref-manual/ref-classes.xml
+++ b/documentation/ref-manual/ref-classes.xml
@@ -463,10 +463,11 @@
 
     <para>
         The <filename>chrpath</filename> class
-        is a wrapper around the "chrpath" utility, which is used during the
-        build process for <filename>nativesdk</filename>,
-        <filename>cross</filename>, and
-        <filename>cross-canadian</filename> recipes to change
+        is a wrapper around the "chrpath" utility.
+        This utility is used during the build process for
+        <filename>nativesdk</filename>, <filename>cross</filename>, and
+        <filename>cross-canadian</filename> recipes, which run on the host
+        system to create packages for the target hardware and change
         <filename>RPATH</filename> records within binaries in order to make
         them relocatable.
     </para>
@@ -1146,8 +1147,8 @@
     <title><filename>gzipnative.bbclass</filename></title>
 
     <para>
-        The <filename>gzipnative</filename>
-        class enables the use of native versions of <filename>gzip</filename>
+        The <filename>gzipnative</filename> class enables the use of
+        different native versions of <filename>gzip</filename>
         and <filename>pigz</filename> rather than the versions of these tools
         from the build host.
     </para>
diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml
index 4ca4e51d5d..71f4ca680c 100644
--- a/documentation/ref-manual/ref-variables.xml
+++ b/documentation/ref-manual/ref-variables.xml
@@ -1396,15 +1396,22 @@
                 <para role="glossdeffirst">
 <!--                <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
                     The bare name of the recipe.
-                    This variable is a version of the <link linkend='var-PN'><filename>PN</filename></link> variable
-                    but removes common suffixes such as "-native" and "-cross" as well
-                    as removes common prefixes such as multilib's "lib64-" and "lib32-".
+                    This variable is a version of the
+                    <link linkend='var-PN'><filename>PN</filename></link>
+                    variable but removes common suffixes such as
+                    <filename>-native</filename> and
+                    <filename>-cross</filename> as well
+                    as removes common prefixes such as multilib's
+                    <filename>lib64-</filename> and
+                    <filename>lib32-</filename>.
                     The exact list of suffixes removed is specified by the
-                    <link linkend='var-SPECIAL_PKGSUFFIX'><filename>SPECIAL_PKGSUFFIX</filename></link> variable.
+                    <link linkend='var-SPECIAL_PKGSUFFIX'><filename>SPECIAL_PKGSUFFIX</filename></link>
+                    variable.
                     The exact list of prefixes removed is specified by the
-                    <link linkend='var-MLPREFIX'><filename>MLPREFIX</filename></link> variable.
+                    <link linkend='var-MLPREFIX'><filename>MLPREFIX</filename></link>
+                    variable.
                     Prefixes are removed for <filename>multilib</filename>
-                    and <filename>nativesdk</filename> cases.
+                    and <filename>nativesdk-</filename> cases.
                 </para>
             </glossdef>
         </glossentry>
@@ -1467,7 +1474,7 @@
                     Specifies the flags to pass to the C pre-processor
                     (i.e. to both the C and the C++ compilers) when building
                     for the build host.
-                    When building in the <filename>native</filename> context,
+                    When building in the <filename>-native</filename> context,
                     <link linkend='var-CPPFLAGS'><filename>CPPFLAGS</filename></link>
                     is set to the value of this variable by default.
                 </para>
@@ -1483,7 +1490,7 @@
 <!--                <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
                     Specifies the flags to pass to the C++ compiler when
                     building for the build host.
-                    When building in the <filename>native</filename> context,
+                    When building in the <filename>-native</filename> context,
                     <link linkend='var-CXXFLAGS'><filename>CXXFLAGS</filename></link>
                     is set to the value of this variable by default.
                 </para>
@@ -1558,7 +1565,7 @@
                     The OpenEmbedded build system uses the
                     <filename>BUILD_PREFIX</filename> value to set the
                     <link linkend='var-TARGET_PREFIX'><filename>TARGET_PREFIX</filename></link>
-                    when building for native recipes.
+                    when building for <filename>native</filename> recipes.
                 </para>
             </glossdef>
         </glossentry>
@@ -1839,7 +1846,7 @@
 <!--                <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
                     Specifies the flags to pass to the C compiler when building
                     for the SDK.
-                    When building in the <filename>nativesdk</filename>
+                    When building in the <filename>nativesdk-</filename>
                     context,
                     <link linkend='var-CFLAGS'><filename>CFLAGS</filename></link>
                     is set to the value of this variable by default.
@@ -1857,7 +1864,7 @@
                     Specifies the flags to pass to the C pre-processor
                     (i.e. to both the C and the C++ compilers) when building
                     for the SDK.
-                    When building in the <filename>nativesdk</filename>
+                    When building in the <filename>nativesdk-</filename>
                     context,
                     <link linkend='var-CPPFLAGS'><filename>CPPFLAGS</filename></link>
                     is set to the value of this variable by default.
@@ -1874,7 +1881,7 @@
 <!--                <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
                     Specifies the flags to pass to the C++ compiler when
                     building for the SDK.
-                    When building in the <filename>nativesdk</filename>
+                    When building in the <filename>nativesdk-</filename>
                     context,
                     <link linkend='var-CXXFLAGS'><filename>CXXFLAGS</filename></link>
                     is set to the value of this variable by default.
@@ -2031,7 +2038,7 @@
                     and then can be used as an override.
                     Here is an example where "python-native" is added to
                     <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
-                    only when building for the native case:
+                    only when building for the <filename>-native</filename> case:
                     <literallayout class='monospaced'>
      DEPENDS_append_class-native = " python-native"
                     </literallayout>
@@ -2567,7 +2574,7 @@
                         <listitem><para>
                             <link linkend='var-BUILDSDK_CXXFLAGS'><filename>BUILDSDK_CXXFLAGS</filename></link>
                             when building for an SDK (i.e.
-                            <filename>nativesdk</filename>)
+                            <filename>nativesdk-</filename>)
                             </para></listitem>
                     </itemizedlist>
                 </para>
@@ -4736,12 +4743,12 @@
                         <listitem><para>
                             <filename>BUILD_CC_ARCH</filename>
                             when building for the build host (i.e.
-                            <filename>native</filename>)
+                            <filename>-native</filename>)
                             </para></listitem>
                         <listitem><para>
                             <filename>BUILDSDK_CC_ARCH</filename>
                             when building for an SDK (i.e.
-                            <filename>nativesdk</filename>)
+                            <filename>nativesdk-</filename>)
                             </para></listitem>
                     </itemizedlist>
                 </para>
@@ -11898,14 +11905,14 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
                         <listitem><para>For recipes building for the target
                            machine, the value is "${STAGING_DIR}/${MACHINE}".
                            </para></listitem>
-                        <listitem><para>For <filename>native</filename>
-                           recipes building
+                        <listitem><para>For native recipes building
                            for the build host, the value is empty given the
                            assumption that when building for the build host,
                            the build host's own directories should be used.
                            </para></listitem>
-                        <listitem><para>For <filename>nativesdk</filename>
-                           recipes that build for the SDK, the value is
+                        <listitem><para>For native SDK
+                           recipes that build for the SDK
+                           (<filename>nativesdk</filename>), the value is
                            "${STAGING_DIR}/${MULTIMACH_HOST_SYS}".
                            </para></listitem>
                     </itemizedlist>
@@ -12713,12 +12720,13 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
                             "${<link linkend='var-TARGET_SYS'>TARGET_SYS</link>}-".
                             </para></listitem>
                         <listitem><para>
-                            For <filename>native</filename> recipes, the build
-                            system sets the variable to the value of
+                            For native recipes, the build system sets the
+                            variable to the value of
                             <filename>BUILD_PREFIX</filename>.
                             </para></listitem>
                         <listitem><para>
-                            For <filename>nativesdk</filename> recipes, the
+                            For native SDK recipes
+                            (<filename>nativesdk</filename>), the
                             build system sets the variable to the value of
                             <filename>SDK_PREFIX</filename>.
                             </para></listitem>
@@ -12757,9 +12765,8 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
                     Consider these two examples:
                     <itemizedlist>
                         <listitem><para>
-                            Given a <filename>native</filename> recipe on a
-                            32-bit, x86 machine running Linux, the value is
-                            "i686-linux".
+                            Given a native recipe on a 32-bit, x86 machine
+                            running Linux, the value is "i686-linux".
                             </para></listitem>
                         <listitem><para>
                             Given a recipe being built for a little-endian,
@@ -13365,11 +13372,14 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
                     toolchain set that runs on the
                     <link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>,
                     and each package should usually have the prefix
-                    "nativesdk-".
-                    When building an SDK using
-                    <filename>bitbake -c populate_sdk &lt;imagename&gt;</filename>,
-                    a default list of packages is set in this variable, but
-                    you can add additional packages to the list.
+                    <filename>nativesdk-</filename>.
+                    For example, consider the following command when
+                    building an SDK:
+                    <literallayout class='monospaced'>
+     $ bitbake -c populate_sdk <replaceable>imagename</replaceable>
+                    </literallayout>
+                    In this case, a default list of packages is set in this
+                    variable, but you can add additional packages to the list.
                 </para>
 
                 <para>
diff --git a/documentation/ref-manual/technical-details.xml b/documentation/ref-manual/technical-details.xml
index 6b4deb3177..b4f6a832ed 100644
--- a/documentation/ref-manual/technical-details.xml
+++ b/documentation/ref-manual/technical-details.xml
@@ -470,17 +470,19 @@
         </para>
 
         <para>
-            To complicate the problem, there are things that should not be included in
-            the checksum.
+            To complicate the problem, there are things that should not be
+            included in the checksum.
             First, there is the actual specific build path of a given task -
             the <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>.
-            It does not matter if the work directory changes because it should not
-            affect the output for target packages.
-            Also, the build process has the objective of making native or cross packages relocatable.
-            The checksum therefore needs to exclude <filename>WORKDIR</filename>.
+            It does not matter if the work directory changes because it should
+            not affect the output for target packages.
+            Also, the build process has the objective of making native
+            (build host) or cross packages (target hardware) relocatable.
+            The checksum therefore needs to exclude
+            <filename>WORKDIR</filename>.
             The simplistic approach for excluding the work directory is to set
-            <filename>WORKDIR</filename> to some fixed value and create the checksum
-            for the "run" script.
+            <filename>WORKDIR</filename> to some fixed value and create the
+            checksum for the "run" script.
         </para>
 
         <para>