sdk-manual: Applied some "red" text formatting to indicate notes

I am using "red" text to indicate sections of the manual that
are my development notes.

(From yocto-docs rev: 95b432d852ac3248874a2a958d4a80e59187f062)

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

1 files changed, 212 insertions, 18 deletions

diff --git a/documentation/sdk-manual/sdk-using.xml b/documentation/sdk-manual/sdk-using.xml
index e3dc6e22a1..66f2c0ed9d 100644
--- a/documentation/sdk-manual/sdk-using.xml
+++ b/documentation/sdk-manual/sdk-using.xml
@@ -7,9 +7,9 @@
 <title>Using the Standard SDK</title>
 
 <para>
-    This chapter describes how to use a standard SDK.
-    Information covers installing the SDK and task-based procedures common
-    for developing with a standard SDK.
+    This chapter describes the standard SDK and how to use it.
+    Information covers the pieces of the SDK, how to install it, and presents
+    several task-based procedures common for developing with a standard SDK.
     <note>
         The tasks you can perform using a standard SDK are also applicable
         when you are using an extensible SDK.
@@ -20,34 +20,50 @@
     </note>
 </para>
 
-<section id='sdk-setting-up-to-use-the-standard-sdk'>
-    <title>Setting Up to Use the Standard SDK</title>
+<section id='sdk-standard-sdk-intro'>
+    <title>Why use the Standard SDK and What is in It?</title>
 
-    <para>
-        Here is a list of items I think need addressed in this section:
+    <para role='writernotes'>
+        <emphasis>MANUAL DEVELOPMENT NOTES:</emphasis>
+        This paragraph describes why you use the Standard SDK.
+        Probably need to compare that against why you would not be interested
+        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 role='writernotes'>
+        <emphasis>MANUAL DEVELOPMENT NOTES:</emphasis>
+        Here is a list of items I think need addressed in these early
+        sections:
         <itemizedlist>
-            <listitem><para><emphasis>What is your situation?</emphasis></para>
-                <para>In other words, is the developer on a machine that
+            <listitem><para role='writernotes'><emphasis>What is your situation?</emphasis></para>
+                <para role='writernotes'>In other words, is the developer on a machine that
                 has YP on it?
                 Are they on a machine that does not?
                 Is the image they are developing against available as a
                 pre-built, down-loadable image and can they get it?</para>
-                <para>Depending on the scenario, there are different ways
+                <para role='writernotes'>Depending on the scenario, there are different ways
                 to make sure the machine they are using is ready to use a
                 standard SDK.
                 I think we need to cover the various situations in this
                 section.
                 </para></listitem>
-            <listitem><para><emphasis>What are the recommendations?</emphasis></para>
-                <para>What is the most common development scenario?
+            <listitem><para role='writernotes'><emphasis>What are the recommendations?</emphasis></para>
+                <para role='writernotes'>What is the most common development scenario?
                 Is there a recommended development flow we want to present
                 when using a standard SDK?
                 What conditions in a development scenario warrant use of
                 just the standard SDK as compared to the extensible SDK?
                 </para></listitem>
-            <listitem><para><emphasis>What procedures do we want to cover to set up
+            <listitem><para role='writernotes'><emphasis>What procedures do we want to cover to set up
                 the standard SDK?</emphasis></para>
-                <para>There is a ton of setup information in the
+                <para role='writernotes'>There is a ton of setup information in the
                 current ADT manual regarding getting, building, and installing
                 an SDK.
                 We would ignore the stuff about the ADT installer script
@@ -60,12 +76,190 @@
                 </para></listitem>
         </itemizedlist>
     </para>
+
+    <para>
+        The installed Standard SDK consists of several files and directories.
+        Basically, it contains an SDK environment setup script, some
+        configuration files, and host and target root filesystems to support
+        usage.
+        You can see the directory structure in the
+        "<link linkend='sdk-installed-standard-sdk-directory-structure'>Installed Standard SDK Directory Structure</link>"
+        section.
+        <note>
+            You can also find information on how the Yocto Project
+            OpenEmbedded build system creates an SDK image by looking at the
+            "<ulink url='&YOCTO_DOCS_REF_URL;#sdk-generation-dev-environment'>SDK Generation</ulink>"
+            section in the Yocto Project Reference Manual.
+        </note>
+    </para>
+</section>
+
+<section id='sdk-installing-the-sdk'>
+    <title>Installing the SDK</title>
+
+    <para>
+        The first thing you need to do is install the SDK on your host
+        development machine by running the <filename>.sh</filename>
+        installation script.
+    </para>
+
+    <para>
+        You can download a tarball installer, which includes the
+        pre-built toolchain, the <filename>runqemu</filename>
+        script, and support files from the appropriate directory under
+        <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'></ulink>.
+        Toolchains are available for 32-bit and 64-bit x86 development
+        systems from the <filename>i686</filename> and
+        <filename>x86_64</filename> directories, respectively.
+        The toolchains the Yocto Project provides are based off the
+        <filename>core-image-sato</filename> image and contain
+        libraries appropriate for developing against that image.
+        Each type of development system supports five or more target
+        architectures.
+    </para>
+
+    <para>
+        The names of the tarball installer scripts are such that a
+        string representing the host system appears first in the
+        filename and then is immediately followed by a string
+        representing the target architecture.
+        <literallayout class='monospaced'>
+     poky-glibc-<replaceable>host_system</replaceable>-<replaceable>image_type</replaceable>-<replaceable>arch</replaceable>-toolchain-<replaceable>release_version</replaceable>.sh
+
+     Where:
+         <replaceable>host_system</replaceable> is a string representing your development system:
+
+                    i686 or x86_64.
+
+         <replaceable>image_type</replaceable> is a string representing the image you wish to
+                develop a SDK for use against. The Yocto Project builds
+                installers for standard SDKs using the following BitBake
+                command:
+
+                    bitbake core-image-sato -c populate_sdk
+
+         <replaceable>arch</replaceable> is a string representing the tuned target architecture:
+
+                    i586, x86_64, powerpc, mips, armv7a or armv5te
+
+         <replaceable>release_version</replaceable> is a string representing the release number of the
+                Yocto Project:
+
+                    &DISTRO;, &DISTRO;+snapshot
+        </literallayout>
+        For example, the following toolchain installer is for a 64-bit
+        development host system and a i586-tuned target architecture
+        based off the SDK for <filename>core-image-sato</filename> and
+        using the current &DISTRO; snapshot:
+        <literallayout class='monospaced'>
+     poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh
+        </literallayout>
+    </para>
+
+    <para>
+        The SDK and toolchains are self-contained and by default are installed
+        into <filename>/opt/poky</filename>.
+        However, when you run the SDK installer, you can choose an
+        installation directory.
+    </para>
+
+    <para>
+        The following command shows how to run the installer given a
+        toolchain tarball for a 64-bit x86 development host system and
+        a 32-bit x86 target architecture.
+        When you run the installer, the script prompts you for a
+        system password so that you permissions can change enabling
+        you to run the installer script.
+        The example assumes the toolchain installer is located in
+        <filename>~/Downloads/</filename>.
+        <note>
+            If you do not have write permissions for the directory
+            into which you are installing the SDK, the installer
+            notifies you and exits.
+            Be sure you have write permissions in the directory and
+            run the installer again.
+        </note>
+        <literallayout class='monospaced'>
+     $ ~/Downloads/poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh
+     Poky (Yocto Project Reference Distro) SDK installer version 2.1+snapshot
+     ========================================================================
+     Enter target directory for SDK (default: /opt/poky/2.1+snapshot):
+     You are about to install the SDK to "/opt/poky/2.1+snapshot". Proceed[Y/n]? Y
+     [sudo] password for scottrif:
+     Extracting SDK.......................done
+     Setting it up...done
+     SDK has been successfully set up and is ready to be used.
+     Each time you wish to use the SDK in a new shell session, you need to source the environment setup script e.g.
+      $ . /opt/poky/2.1+snapshot/environment-setup-i586-poky-linux
+        </literallayout>
+    </para>
+
+    <para>
+        Again, reference the
+        "<link linkend='sdk-installed-standard-sdk-directory-structure'>Installed Standard SDK Directory Structure</link>"
+        section for more details on the resulting directory structure of
+        the installed SDK.
+    </para>
+</section>
+
+<section id='sdk-running-the-sdk-environment-setup-script'>
+    <title>Running the SDK Environment Setup Script</title>
+
+    <para>
+        Once you have the SDK installed, you must run the SDK environment
+        setup script before you can actually use it.
+        This setup script resides in the directory you chose when you installed
+        the SDK.
+        For information on where this setup script can reside, see the
+        "<link linkend='sdk-appendix-obtain'>Obtaining the SDK</link>"
+        Appendix.
+    </para>
+
+    <para>
+        Before running the script, be sure it is the one that matches the
+        architecture for which you are developing.
+        Environment setup scripts begin with the string
+        "<filename>environment-setup</filename>" and include as part of their
+        name the tuned target architecture.
+        For example, the setup script for an IA-based target machine using
+        i586 tuning and located in the default SDK installation
+        directory is as follows:
+        <literallayout class='monospaced'>
+     $ source /opt/poky/&DISTRO;+snapshot/environment-setup-i586-poky-linux
+        </literallayout>
+        When you run the setup script, many environment variables are
+        defined:
+        <literallayout class='monospaced'>
+     <ulink url='&YOCTO_DOCS_REF_URL;#var-SDKTARGETSYSROOT'><filename>SDKTARGETSYSROOT</filename></ulink> - The path to the sysroot used for cross-compilation
+     <ulink url='&YOCTO_DOCS_REF_URL;#var-PKG_CONFIG_PATH'><filename>PKG_CONFIG_PATH</filename></ulink> - The path to the target pkg-config files
+     <ulink url='&YOCTO_DOCS_REF_URL;#var-CONFIG_SITE'><filename>CONFIG_SITE</filename></ulink> - A GNU autoconf site file preconfigured for the target
+     <ulink url='&YOCTO_DOCS_REF_URL;#var-CC'><filename>CC</filename></ulink> - The minimal command and arguments to run the C compiler
+     <ulink url='&YOCTO_DOCS_REF_URL;#var-CXX'><filename>CXX</filename></ulink> - The minimal command and arguments to run the C++ compiler
+     <ulink url='&YOCTO_DOCS_REF_URL;#var-CPP'><filename>CPP</filename></ulink> - The minimal command and arguments to run the C preprocessor
+     <ulink url='&YOCTO_DOCS_REF_URL;#var-AS'><filename>AS</filename></ulink> - The minimal command and arguments to run the assembler
+     <ulink url='&YOCTO_DOCS_REF_URL;#var-LD'><filename>LD</filename></ulink> - The minimal command and arguments to run the linker
+     <ulink url='&YOCTO_DOCS_REF_URL;#var-GDB'><filename>GDB</filename></ulink> - The minimal command and arguments to run the GNU Debugger
+     <ulink url='&YOCTO_DOCS_REF_URL;#var-STRIP'><filename>STRIP</filename></ulink> - The minimal command and arguments to run 'strip', which strips symbols
+     <ulink url='&YOCTO_DOCS_REF_URL;#var-RANLIB'><filename>RANLIB</filename></ulink> - The minimal command and arguments to run 'ranlib'
+     <ulink url='&YOCTO_DOCS_REF_URL;#var-OBJCOPY'><filename>OBJCOPY</filename></ulink> - The minimal command and arguments to run 'objcopy'
+     <ulink url='&YOCTO_DOCS_REF_URL;#var-OBJDUMP'><filename>OBJDUMP</filename></ulink> - The minimal command and arguments to run 'objdump'
+     <ulink url='&YOCTO_DOCS_REF_URL;#var-AR'><filename>AR</filename></ulink> - The minimal command and arguments to run 'ar'
+     <ulink url='&YOCTO_DOCS_REF_URL;#var-NM'><filename>NM</filename></ulink> - The minimal command and arguments to run 'nm'
+     <ulink url='&YOCTO_DOCS_REF_URL;#var-TARGET_PREFIX'><filename>TARGET_PREFIX</filename></ulink> - The toolchain binary prefix for the target tools
+     <ulink url='&YOCTO_DOCS_REF_URL;#var-CROSS_COMPILE'><filename>CROSS_COMPILE</filename></ulink> - The toolchain binary prefix for the target tools
+     <ulink url='&YOCTO_DOCS_REF_URL;#var-CONFIGURE_FLAGS'><filename>CONFIGURE_FLAGS</filename></ulink> - The minimal arguments for GNU configure
+     <ulink url='&YOCTO_DOCS_REF_URL;#var-CFLAGS'><filename>CFLAGS</filename></ulink> - Suggested C flags
+     <ulink url='&YOCTO_DOCS_REF_URL;#var-CXXFLAGS'><filename>CXXFLAGS</filename></ulink> - Suggested C++ flags
+     <ulink url='&YOCTO_DOCS_REF_URL;#var-LDFLAGS'><filename>LDFLAGS</filename></ulink> - Suggested linker flags when you use CC to link
+     <ulink url='&YOCTO_DOCS_REF_URL;#var-CPPFLAGS'><filename>CPPFLAGS</filename></ulink> - Suggested preprocessor flags
+        </literallayout>
+    </para>
 </section>
 
 <section id='sdk-using-the-sdk-to-task-1'>
     <title>Using the SDK to <replaceable>item 1</replaceable></title>
 
-    <para>
+    <para role='writernotes'>
         Describe the specific task you are going to accomplish with the SDK.
         Provide a diagram showing the rough flow of the task.
         Provide specific steps using a real example that works through the
@@ -76,7 +270,7 @@
 <section id='sdk-using-the-sdk-to-task-2'>
     <title>Using the SDK to <replaceable>item-2</replaceable></title>
 
-    <para>
+    <para role='writernotes'>
         Describe the specific task you are going to accomplish with the SDK.
         Provide a diagram showing the rough flow of the task.
         Provide specific steps using a real example that works through the
@@ -87,7 +281,7 @@
 <section id='sdk-using-the-sdk-to-task-3'>
     <title>Using the SDK to <replaceable>item-3</replaceable></title>
 
-    <para>
+    <para role='writernotes'>
         Describe the specific task you are going to accomplish with the SDK.
         Provide a diagram showing the rough flow of the task.
         Provide specific steps using a real example that works through the
@@ -98,7 +292,7 @@
 <section id='sdk-using-the-sdk-to-task-x'>
     <title>Using the SDK to <replaceable>item-x</replaceable></title>
 
-    <para>
+    <para role='writernotes'>
         Describe the specific task you are going to accomplish with the SDK.
         Provide a diagram showing the rough flow of the task.
         Provide specific steps using a real example that works through the