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>

4 files changed, 229 insertions, 35 deletions

diff --git a/documentation/sdk-manual/sdk-appendix-customizing.xml b/documentation/sdk-manual/sdk-appendix-customizing.xml
index c2cb4aa005..2068143df3 100644
--- a/documentation/sdk-manual/sdk-appendix-customizing.xml
+++ b/documentation/sdk-manual/sdk-appendix-customizing.xml
@@ -6,14 +6,14 @@
 
 <title>Customizing the SDK</title>
 
-<para>
+<para role='writernotes'>
     This chapter is going to cover the details on extending the SDK through
     user customizations.
     I am not sure if this is possible for both the standard and extensible
     SDK or what.
 </para>
 
-<para>
+<para role='writernotes'>
     I do not have a feel for what sub-topics need to be covered here.
     I need to get this information from Paul.
 </para>
diff --git a/documentation/sdk-manual/sdk-appendix-obtain.xml b/documentation/sdk-manual/sdk-appendix-obtain.xml
index baf5dfd42f..eada4cc8ed 100644
--- a/documentation/sdk-manual/sdk-appendix-obtain.xml
+++ b/documentation/sdk-manual/sdk-appendix-obtain.xml
@@ -9,18 +9,18 @@
 <section id='sdk-appendix-obtain-manual-development-notes'>
     <title>Manual Development Notes for Scott and Paul</title>
 
-    <para>
+    <para role='writernotes'>
         This chapter is going to cover details about the installed SDK and perhaps
         stuff on locating it (e.g. the naming scheme used to identify the
         <filename>.sh</filename> installation script.
     </para>
 
-    <para>
+    <para role='writernotes'>
         The idea here is to gather all the current information in the regular
         YP doc set that describes how to locate, download, or build out the SDK.
     </para>
 
-    <para>
+    <para role='writernotes'>
         One thing that needs discussed is any differences between getting the
         standard SDK as compared to the extended SDK.
         Do we have pre-build extensible SDKs laying around?
diff --git a/documentation/sdk-manual/sdk-extensible.xml b/documentation/sdk-manual/sdk-extensible.xml
index a04164a413..c238dee382 100644
--- a/documentation/sdk-manual/sdk-extensible.xml
+++ b/documentation/sdk-manual/sdk-extensible.xml
@@ -6,7 +6,7 @@
 
 <title>Using the Extensible SDK</title>
 
-<para>
+<para role='writernotes'>
     This chapter describes what you need on your machine in order to use
     an extensible SDK.
     The chapter does not repeat information that also applies to using the
@@ -26,30 +26,30 @@
 <section id='sdk-setting-up-to-use-the-extensible-sdk'>
     <title>Setting Up to Use the Extensible SDK</title>
 
-    <para>
+    <para role='writernotes'>
         Here is a list of items I think need addressed in this section:
         <itemizedlist>
-            <listitem><para><emphasis>Cover differences in the development
+            <listitem><para role='writernotes'><emphasis>Cover differences in the development
                 that might be impacted because they are using an extensible
                 SDK</emphasis></para>
-                <para>Presumably, the various development scenarios are
+                <para role='writernotes'>Presumably, the various development scenarios are
                 covered regarding setup in the previous chapter.
                 Are these impacted because the developer is going to now be
                 using an extensible SDK?
                 If so, what are the implications?
                 </para></listitem>
-            <listitem><para><emphasis>What new recommendations exist now that
+            <listitem><para role='writernotes'><emphasis>What new recommendations exist now that
                 the developer is going to be using an extensible SDK?</emphasis></para>
-                <para>We should cover the most common development scenarios
+                <para role='writernotes'>We should cover the most common development scenarios
                 that apply when using an extensible SDK.
                 Is there a recommended development flow we want to present
                 when using an extensible SDK?
                 What conditions in a development scenario warrant use of
                 the extensible SDK as compared to the standard SDK?
                 </para></listitem>
-            <listitem><para><emphasis>What procedures do we want to cover to set
+            <listitem><para role='writernotes'><emphasis>What procedures do we want to cover to set
                 up the extensible SDK?</emphasis></para>
-                <para>Is it just a matter of building out the SDK using
+                <para role='writernotes'>Is it just a matter of building out the SDK using
                 <filename>bitbake -c populate_sdk_ext</filename>?
                 Is there a pre-built extensible SDK laying around they can
                 find and download if they are using a machine that does not
@@ -63,7 +63,7 @@
 <section id='sdk-using-the-extensible-sdk-to-task-1'>
     <title>Using the Extensible SDK to <replaceable>item 1</replaceable></title>
 
-    <para>
+    <para role='writernotes'>
         Describe the specific task you are going to accomplish with the
         extensible SDK.
         Provide a diagram showing the rough flow of the task.
@@ -75,7 +75,7 @@
 <section id='sdk-using-the-extensible-sdk-to-task-2'>
     <title>Using the Extensible SDK to <replaceable>item-2</replaceable></title>
 
-    <para>
+    <para role='writernotes'>
         Describe the specific task you are going to accomplish with the
         extensible SDK.
         Provide a diagram showing the rough flow of the task.
@@ -87,7 +87,7 @@
 <section id='sdk-using-the-extensible-sdk-to-task-3'>
     <title>Using the Extensible SDK to <replaceable>item-3</replaceable></title>
 
-    <para>
+    <para role='writernotes'>
         Describe the specific task you are going to accomplish with the
         extensible SDK.
         Provide a diagram showing the rough flow of the task.
@@ -99,7 +99,7 @@
 <section id='sdk-using-the-extensible-sdk-to-task-x'>
     <title>Using the Extensible SDK to <replaceable>item-x</replaceable></title>
 
-    <para>
+    <para role='writernotes'>
         Describe the specific task you are going to accomplish with the
         extensible SDK.
         Provide a diagram showing the rough flow of the task.
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