sdk-manual: Applied review edits to the manual.

(From yocto-docs rev: be853fb74b28bcf1b27b3b7a8e83012928d4e53a)

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

documentation/sdk-manual/sdk-appendix-customizing.xml

@@ -17,11 +17,11 @@
 
     <para>
         The extensible SDK primarily consists of a pre-configured copy of
-        the build system from which it was produced.
+        the OpenEmbedded build system from which it was produced.
         Thus, the SDK's configuration is derived using that build system.
-        However, filters exist that are applied such as the following that
+        However, filters such as the following exist that the OpenEmbedded
-        are applied to <filename>local.conf</filename> and
+        build system applies to <filename>local.conf</filename> and
-        <filename>auto.conf</filename> when present:
+        <filename>auto.conf</filename> when these files are present:
         <itemizedlist>
             <listitem><para>
                 Variables whose values start with "/" are excluded since the
@@ -44,8 +44,9 @@
                 Variables listed in
                 <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_LOCAL_CONF_WHITELIST'><filename>SDK_LOCAL_CONF_WHITELIST</filename></ulink>
                 are included.
-                Including these variables overrides either of the above two
+                Including a variable in the value of
-                conditions.
+                <filename>SDK_LOCAL_CONF_WHITELIST</filename> overrides either
+                of the above two conditions.
                 The default value is blank.
                 </para></listitem>
             <listitem><para>
@@ -68,9 +69,9 @@
         when present, are appended to the end of
         <filename>conf/local.conf</filename> within the produced SDK, without
         any filtering.
-        Not filtering these contents is particularly useful if you want to
+        The <filename>sdk-extra.conf</filename> file is particularly useful
-        set a variable value just for the SDK and not the build system used to
+        if you want to set a variable value just for the SDK and not the
-        create the SDK.
+        OpenEmbedded build system used to create the SDK.
     </para>
 </section>
 
@@ -141,14 +142,14 @@
                 appear in
                 <ulink url='&YOCTO_DOCS_REF_URL;#var-COREBASE'><filename>COREBASE</filename></ulink>
                 (other than layers that are enabled through
-                <filename>bblayers.conf</filename>), then must list these
+                <filename>bblayers.conf</filename>), then you must list these
                 files in
                 <ulink url='&YOCTO_DOCS_REF_URL;#var-COREBASE_FILES'><filename>COREBASE_FILES</filename></ulink>
                 so that the files are copied into the SDK.
                 </para></listitem>
             <listitem><para>
-                If your build system setup uses a different environment setup
+                If your OpenEmbedded build system setup uses a different
-                script other than
+                environment setup script other than
                 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
                 or
                 <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>,
@@ -270,15 +271,16 @@
                 <itemizedlist>
                     <listitem><para>
                         If the mirror value you are setting is appropriate to
-                        be set for both the build system that is actually
+                        be set for both the OpenEmbedded build system that is
-                        building the SDK and the SDK itself (i.e. the mirror
+                        actually building the SDK and the SDK itself (i.e. the
-                        is accessible in both places or it will fail quickly
+                        mirror is accessible in both places or it will fail
-                        on the build system side, and its contents will not
+                        quickly on the OpenEmbedded build system side, and its
-                        interfere with the build), then you can set the
+                        contents will not interfere with the build), then you
-                        variable in your <filename>local.conf</filename>
+                        can set the variable in your
-                        or custom distro configuration file.
+                        <filename>local.conf</filename> or custom distro
-                        You can "whitelist" the variable through the SDK by
+                        configuration file.
-                        adding the following:
+                        You can then "whitelist" the variable through
+                        to the SDK by adding the following:
                         <literallayout class='monospaced'>
      SDK_LOCAL_CONF_WHITELIST = "SSTATE_MIRRORS"
                         </literallayout>
@@ -324,8 +326,8 @@
         <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_EXT_TYPE'><filename>SDK_EXT_TYPE</filename></ulink>
         to "minimal" produces an SDK installer that is around 35 Mbytes in
         size, which downloads and installs quickly.
-        You need to realize, though, that the installer does not install any
+        You need to realize, though, that the minimal installer does not
-        libraries or tools out of the box.
+        install any libraries or tools out of the box.
         These must be installed either "on the fly" or through actions you
         perform using <filename>devtool</filename> or explicitly with the
         <filename>devtool sdk-install</filename> command.

documentation/sdk-manual/sdk-appendix-obtain.xml

@@ -222,15 +222,15 @@
         different than the installed structure for the standard SDK.
         The extensible SDK does not separate host and target parts in the
         same manner as does the standard SDK.
-        The extensible SDK uses an embedded copy of the build system, which
+        The extensible SDK uses an embedded copy of the OpenEmbedded
-        has its own sysroots.
+        build system, which has its own sysroots.
     </para>
 
     <para>
         Of note in the directory structure are an environment setup script
         for the SDK, a configuration file for the target, a version file for
-        the target, and a log file for the build system preparation script run
+        the target, and a log file for the OpenEmbedded build system
-        by the installer.
+        preparation script run by the installer.
     </para>
 
     <para>

documentation/sdk-manual/sdk-extensible.xml

@@ -10,8 +10,8 @@
     This chapter describes the extensible SDK and how to use it.
     The extensible SDK makes it easy to add new applications and libraries
     to an image, modify the source for an existing component, test
-    changes on the target hardware, and ease integration into the rest
+    changes on the target hardware, and ease integration into the rest of the
-    of the build system.
+    <ulink url='&YOCTO_DOCS_DEV_URL;#build-system-term'>OpenEmbedded build system</ulink>.
 </para>
 
 <para>
@@ -45,12 +45,17 @@
                 <filename>poky_sdk</filename> folder of your home directory.
                 As with the standard SDK, you can choose to install the
                 extensible SDK in any location when you run the installer.
+                However, unlike the standard SDK, the location you choose needs
+                to be writable for whichever users need to use the SDK,
+                since files will need to be written under that directory during
+                the normal course of operation.
                 </para></listitem>
             <listitem><para><emphasis>Build Tools and Build System:</emphasis>
                 The extensible SDK installer performs additional tasks as
                 compared to the standard SDK installer.
                 The extensible SDK installer extracts build tools specific
-                to the SDK and the installer also prepares the build system.
+                to the SDK and the installer also prepares the OpenEmbedded
+                build system.
                 Here is example output for running the extensible SDK
                 installer:
                 <literallayout class='monospaced'>
@@ -86,7 +91,31 @@
     </para>
 </section>
 
-<section id='sdk-use-devtool-to-add-an-application'>
+<section id='using-devtool-in-your-sdk-workflow'>
+    <title>Using <filename>devtool</filename> in Your SDK Workflow</title>
+
+    <para>
+        <filename>devtool</filename> helps you easily develop projects whose
+        build output must be part of an image built using the OpenEmbedded
+        build system.
+    </para>
+
+    <para>
+        These entry points exist that allow you to develop using
+        <filename>devtool</filename>:
+        <itemizedlist>
+            <listitem><para><emphasis><filename>devtool add</filename></emphasis>
+                </para></listitem>
+            <listitem><para><emphasis><filename>devtool modify</filename></emphasis>
+                </para></listitem>
+        </itemizedlist>
+    </para>
+
+    <para>
+        The remainder of this section presents these workflows.
+    </para>
+
+    <section id='sdk-use-devtool-to-add-an-application'>
         <title>Use <filename>devtool add</filename> to Add an Application</title>
 
         <para>
@@ -308,9 +337,9 @@
                     </para></listitem>
             </orderedlist>
         </para>
-</section>
+    </section>
 
-<section id='sdk-devtool-use-devtool-modify-to-modify-the-source-of-an-existing-component'>
+    <section id='sdk-devtool-use-devtool-modify-to-modify-the-source-of-an-existing-component'>
         <title>Use <filename>devtool modify</filename> to Modify the Source of an Existing Component</title>
 
         <para>
@@ -466,11 +495,6 @@
                 <listitem><para><emphasis>Build the Recipe</emphasis>:
                     Once you have updated the source files, you can build
                     the recipe.
-                You can either use <filename>devtool build</filename> or
-                <filename>bitbake</filename>.
-                Either method produces build output that is stored
-                in
-                <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>.
                     </para></listitem>
                 <listitem><para><emphasis>Deploy the Build Output</emphasis>:
                     When you use the <filename>devtool build</filename>
@@ -538,6 +562,7 @@
                     </para></listitem>
             </orderedlist>
         </para>
+    </section>
 </section>
 
 <section id='sdk-installing-additional-items-into-the-extensible-sdk'>
@@ -574,7 +599,7 @@
         It is important to remember that building the item from source takes
         significantly longer than installing the pre-built artifact.
         Also, if no recipe exists for the item you want to add to the SDK, you
-        must add it using the <filename>devtool add</filename> command.
+        must instead add it using the <filename>devtool add</filename> command.
     </para>
 </section>
 
@@ -635,8 +660,8 @@
         constructs a new SDK installer containing those recipes and the
         resulting binary artifacts.
         The recipes go into their own separate layer in the constructed
-        derivative SDK, leaving the workspace clean and ready for you
+        derivative SDK, leaving the workspace clean and ready for users
-        to add your own recipes.
+        to add their own recipes.
     </para>
 </section>
 

documentation/sdk-manual/sdk-intro.xml

@@ -42,7 +42,7 @@
         tools that allow you to easily add new applications and libraries to
         an image, modify the source of an existing component, test changes on
         the target hardware, and easily integrate an application into the
-        the Yocto Project build system.
+        <ulink url='&YOCTO_DOCS_DEV_URL;#build-system-term'>OpenEmbedded build system</ulink>.
     </para>
 
     <para>
@@ -79,7 +79,7 @@
         <itemizedlist>
             <listitem><para>An architecture-specific cross-toolchain and
                 matching sysroots (target and native) all built by the
-                <ulink url='&YOCTO_DOCS_DEV_URL;#build-system-term'>OpenEmbedded build system</ulink>.
+                OpenEmbedded build system.
                 The toolchain and sysroots are based on a
                 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>
                 configuration and extensions,

documentation/sdk-manual/sdk-using.xml

@@ -24,18 +24,10 @@
     <title>Why use the Standard SDK and What is in It?</title>
 
     <para>
-        Fundamentally, the standard SDK exists so that you can access
+        The Standard SDK provides a cross-development toolchain and libraries
-        cross-development tools.
+        tailored to the contents of a specific image.
-        This paragraph describes why you use the Standard SDK.
+        You would use the Standard SDK if you want a more traditional toolchain
-        Probably need to compare that against why you would not be interested
+        experience.
-        in the extensible SDK here as well.
-        According to Paul, the most interest lies in the extensible SDK.
-        So providing this comparison would be helpful.
-        Currently, my understanding boils down to this: The only reason to use
-        the Standard SDK is if you want to build and debug source code that
-        you have.
-        That pretty much sums it up.
-        If there is more detail, I need to know about it.
     </para>
 
     <para>
@@ -125,6 +117,10 @@
         <note>
             You must change the permissions on the toolchain
             installer script so that it is executable.
+            Here is an example:
+            <literallayout class='monospaced'>
+     $ chmod +x  poky-glibc-x86_64-core-image-sato-i586-toolchain-2.1.sh
+            </literallayout>
         </note>
     </para>
 
@@ -440,7 +436,7 @@
 </section>
 
 <section id='sdk-developing-applications-using-eclipse'>
-    <title>Devloping Applications Using <trademark class='trade'>Eclipse</trademark></title>
+    <title>Developing Applications Using <trademark class='trade'>Eclipse</trademark></title>
 
     <para>
         If you are familiar with the popular Eclipse IDE, you can use an