profile-manual: Raw text for introduction chapter.

this text is straight from Tom's wiki.  no formatting
no nuthin'

(From yocto-docs rev: 95f5341169c3e8d3bd7a97740320d0d27cbee020)

Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

1 files changed, 71 insertions, 159 deletions

diff --git a/documentation/profile-manual/profile-manual-intro.xml b/documentation/profile-manual/profile-manual-intro.xml
index dca2460..9ed807f 100644
--- a/documentation/profile-manual/profile-manual-intro.xml
+++ b/documentation/profile-manual/profile-manual-intro.xml
@@ -2,186 +2,98 @@
 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
 [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
 
-<chapter id='dev-manual-intro'>
+<chapter id='profile-manual-intro'>
 
-<title>The Yocto Project Development Manual</title>
+<title>Yocto Project Tracing and Profiling Manual</title>
     <section id='intro'>
         <title>Introduction</title>
 
         <para>
-            Welcome to the Yocto Project Development Manual!
-            This manual gives you an idea of how to use the Yocto Project to develop embedded Linux
-            images and user-space applications to run on targeted devices.
-            Reading this manual gives you an overview of image, kernel, and user-space application development
-            using the Yocto Project.
-            Because much of the information in this manual is general, it contains many references to other
-            sources where you can find more detail.
-            For example, detailed information on Git, repositories and open source in general
-            can be found in many places.
-            Another example is how to get set up to use the Yocto Project, which our Yocto Project
-            Quick Start covers.
+            Yocto bundles a number of tracing and profiling tools - this 'HOWTO'
+            describes their basic usage and shows by example how to make use
+            of them to examine application and system behavior.
         </para>
 
         <para>
-            The Yocto Project Development Manual, however, does provide detailed examples
-            on how to change the kernel source code, reconfigure the kernel, and develop
-            an application using the popular <trademark class='trade'>Eclipse</trademark> IDE.
+            The tools presented are for the most part completely open-ended and
+            have quite good and/or extensive documentation of their own which
+            can be used to solve just about any problem you might come across
+            in Linux.
+            Each section that describes a particular tool has links to that
+            tool's documentation and website.
         </para>
-    </section>
 
-    <section id='what-this-manual-provides'>
-        <title>What this Manual Provides</title>
+        <para>
+            The purpose of this 'HOWTO' is to present a set of common and
+            generally useful tracing and profiling idioms along with their
+            application (as appropriate) to each tool, in the context of a
+            general-purpose 'drill-down' methodology that can be applied
+            to solving a large number (90%?) of problems.
+            For help with more advanced usages and problems, please see
+            the documentation and/or websites listed for each tool.
+        </para>
 
         <para>
-            The following list describes what you can get from this guide:
-            <itemizedlist>
-                <listitem><para>Information that lets you get set
-                    up to develop using the Yocto Project.</para></listitem>
-                <listitem><para>Information to help developers who are new to the open source environment
-                    and to the distributed revision control system Git, which the Yocto Project
-                    uses.</para></listitem>
-                <listitem><para>An understanding of common end-to-end development models and tasks.</para></listitem>
-                <listitem><para>Development case overviews for both system development and user-space
-                    applications.</para></listitem>
-                <listitem><para>An overview and understanding of the emulation environment used with
-                    the Yocto Project - the Quick EMUlator (QEMU).</para></listitem>
-                <listitem><para>An understanding of basic kernel architecture and concepts.</para></listitem>
-                <listitem><para>Many references to other sources of related information.</para></listitem>
-            </itemizedlist>
+            The final section of this 'HOWTO' is a collection of real-world
+            examples which we'll be continually adding to as we solve more
+            problems using the tools - feel free to add your own examples
+            to the list!
         </para>
     </section>
 
-    <section id='what-this-manual-does-not-provide'>
-        <title>What this Manual Does Not Provide</title>
+    <section id='profile-manual-general-setup'>
+        <title>General Setup</title>
 
         <para>
-            This manual will not give you the following:
-            <itemizedlist>
-                <listitem><para>Step-by-step instructions if those instructions exist in other Yocto
-                    Project documentation.
-                    For example, the Yocto Project Application Developer's Guide contains detailed
-                    instruction on how to run the
-                    <ulink url='&YOCTO_DOCS_ADT_URL;#installing-the-adt'>Installing the ADT and Toolchains</ulink>,
-                    which is used to set up a cross-development environment.</para></listitem>
-                <listitem><para>Reference material.
-                    This type of material resides in an appropriate reference manual.
-                    For example, system variables are documented in the
-                    <ulink url='&YOCTO_DOCS_REF_URL;'>Yocto Project Reference Manual</ulink>.</para></listitem>
-                <listitem><para>Detailed public information that is not specific to the Yocto Project.
-                    For example, exhaustive information on how to use Git is covered better through the
-                    Internet than in this manual.</para></listitem>
-            </itemizedlist>
+            Most of the tools are available only in 'sdk' images or in images
+            built after adding 'tools-profile' to your local.conf.
+            So, in order to be able to access all of the tools described here,
+            please first build and boot an 'sdk' image e.g.
+            <literallayout class='monospaced'>
+     $ bitbake core-image-sato-sdk
+            </literallayout>
+            or alternatively by adding 'tools-profile' to the
+            EXTRA_IMAGE_FEATURES line in your local.conf:
+            <literallayout class='monospaced'>
+      EXTRA_IMAGE_FEATURES = "debug-tweaks tools-profile"
+            </literallayout>
+            If you use the 'tools-profile' method, you don't need to build an
+            sdk image - the tracing and profiling tools will be included in
+            non-sdk images as well e.g.:
+            <literallayout class='monospaced'>
+     $ bitbake core-image-sato
+            </literallayout>
+            <note><para>
+                By default, the Yocto build system strips symbols from the
+                binaries it packages, which makes it difficult to use some
+                of the tools.
+                </para><para>You can prevent that by putting the following
+                in your local.conf when you build the image:
+                </para>
+            </note>
+            <literallayout class='monospaced'>
+     INHIBIT_PACKAGE_STRIP = "1"
+            </literallayout>
+            The above setting will noticeably increase the size of your image.
         </para>
-    </section>
 
-    <section id='other-information'>
-        <title>Other Information</title>
+        <para>
+            If you've already build a stripped image, you can generate
+            debug packages (xxx-dbg) which you can manually install as
+            needed.
+        </para>
 
         <para>
-            Because this manual presents overview information for many different topics, you will
-            need to supplement it with other information.
-            The following list presents other sources of information you might find helpful:
-            <itemizedlist>
-                <listitem><para><emphasis>The <ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink>:
-                    </emphasis> The home page for the Yocto Project provides lots of information on the project
-                    as well as links to software and documentation.</para></listitem>
-                <listitem><para><emphasis>
-                    <ulink url='&YOCTO_DOCS_QS_URL;'>Yocto Project Quick Start</ulink>:</emphasis> This short document lets you get started
-                    with the Yocto Project quickly and start building an image.</para></listitem>
-                <listitem><para><emphasis>
-                    <ulink url='&YOCTO_DOCS_REF_URL;'>Yocto Project Reference Manual</ulink>:</emphasis> This manual is a reference
-                    guide to the OpenEmbedded build system known as "Poky."
-                    The manual also contains a reference chapter on Board Support Package (BSP)
-                    layout.</para></listitem>
-                <listitem><para><emphasis>
-                    <ulink url='&YOCTO_DOCS_ADT_URL;'>Yocto Project Application Developer's Guide</ulink>:</emphasis>
-                    This guide provides information that lets you get going with the Application
-                    Development Toolkit (ADT) and stand-alone cross-development toolchains to
-                    develop projects using the Yocto Project.</para></listitem>
-                <listitem><para><emphasis>
-                    <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>:</emphasis>
-                    This guide defines the structure for BSP components.
-                    Having a commonly understood structure encourages standardization.</para></listitem>
-                <listitem><para><emphasis>
-                    <ulink url='&YOCTO_DOCS_KERNEL_URL;'>Yocto Project Kernel Architecture and Use Manual</ulink>:</emphasis>
-                    This manual describes the architecture of the Yocto Project kernel and provides
-                    some work flow examples.</para></listitem>
-                <listitem><para><emphasis>
-                    <ulink url='http://www.youtube.com/watch?v=3ZlOu-gLsh0'>
-                    Eclipse IDE Yocto Plug-in</ulink>:</emphasis> A step-by-step instructional video that
-                    demonstrates how an application developer uses Yocto Plug-in features within
-                    the Eclipse IDE.</para></listitem>
-                <listitem><para><emphasis>
-                    <ulink url='&YOCTO_WIKI_URL;/wiki/FAQ'>FAQ</ulink>:</emphasis>
-                    A list of commonly asked questions and their answers.</para></listitem>
-                <listitem><para><emphasis>
-                    <ulink url='&YOCTO_HOME_URL;/download/yocto/yocto-project-&DISTRO;-release-notes-poky-&POKYVERSION;'>
-                    Release Notes</ulink>:</emphasis> Features, updates and known issues for the current
-                    release of the Yocto Project.</para></listitem>
-                <listitem><para><emphasis>
-                    <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/hob'>
-                    Hob</ulink>:</emphasis> A graphical user interface for BitBake.
-                    Hob's primary goal is to enable a user to perform common tasks more easily.</para></listitem>
-                <listitem><para><emphasis>
-                    <ulink url='&YOCTO_HOME_URL;/download/build-appliance-0'>
-                    Build Appliance</ulink>:</emphasis> A bootable custom embedded Linux image you can
-                    either build using a non-Linux development system (VMware applications) or download
-                    from the Yocto Project website.
-                    See the <ulink url='&YOCTO_HOME_URL;/documentation/build-appliance-manual'>Build Appliance</ulink>
-                    page for more information.</para></listitem>
-                <listitem><para><emphasis>
-                    <ulink url='&YOCTO_BUGZILLA_URL;'>Bugzilla</ulink>:</emphasis>
-                    The bug tracking application the Yocto Project uses.
-                    If you find problems with the Yocto Project, you should report them using this
-                    application.</para></listitem>
-                <listitem><para><emphasis>
-                    Yocto Project Mailing Lists:</emphasis> To subscribe to the Yocto Project mailing
-                    lists, click on the following URLs and follow the instructions:
-                    <itemizedlist>
-                        <listitem><para><ulink url='&YOCTO_LISTS_URL;/listinfo/yocto'></ulink> for a
-                            Yocto Project Discussions mailing list.</para></listitem>
-                        <listitem><para><ulink url='&YOCTO_LISTS_URL;/listinfo/poky'></ulink> for a
-                            Yocto Project Discussions mailing list about the Poky build system.</para></listitem>
-                        <listitem><para><ulink url='&YOCTO_LISTS_URL;/listinfo/yocto-announce'></ulink>
-                            for a mailing list to receive official Yocto Project announcements for developments and
-                            as well as Yocto Project milestones.</para></listitem>
-                        <listitem><para><ulink url='&YOCTO_LISTS_URL;/listinfo'></ulink> for a
-                            listing of all public mailing lists on <filename>lists.yoctoproject.org</filename>.
-                            </para></listitem>
-                    </itemizedlist></para></listitem>
-                <listitem><para><emphasis>Internet Relay Chat (IRC):</emphasis>
-                    Two IRC channels on freenode are available
-                    for Yocto Project and Poky discussions: <filename>#yocto</filename> and
-                    <filename>#poky</filename>, respectively.</para></listitem>
-                <listitem><para><emphasis>
-                    <ulink url='&OH_HOME_URL;'>OpenedHand</ulink>:</emphasis>
-                    The company that initially developed the Poky project, which is the basis
-                    for the OpenEmbedded build system used by the Yocto Project.
-                    OpenedHand was acquired by Intel Corporation in 2008.</para></listitem>
-                <listitem><para><emphasis>
-                    <ulink url='http://www.intel.com/'>Intel Corporation</ulink>:</emphasis>
-                    A multinational semiconductor chip manufacturer company whose Software and
-                    Services Group created and supports the Yocto Project.
-                    Intel acquired OpenedHand in 2008.</para></listitem>
-                <listitem><para><emphasis>
-                    <ulink url='&OE_HOME_URL;'>OpenEmbedded</ulink>:</emphasis>
-                    The build system used by the Yocto Project.
-                    This project is the upstream, generic, embedded distribution from which the Yocto
-                    Project derives its build system (Poky) from and to which it contributes.</para></listitem>
-                <listitem><para><emphasis>
-                    <ulink url='http://developer.berlios.de/projects/bitbake/'>
-                    BitBake</ulink>:</emphasis> The tool used by the OpenEmbedded build system
-                    to process project metadata.</para></listitem>
-                <listitem><para><emphasis>
-                    BitBake User Manual:</emphasis>
-                    A comprehensive guide to the BitBake tool.
-                    If you want information on BitBake, see the user manual inculded in the
-                    <filename>bitbake/doc/manual</filename> directory of the
-                    <link linkend='source-directory'>Source Directory</link>.</para></listitem>
-                <listitem><para><emphasis>
-                    <ulink url='http://wiki.qemu.org/Index.html'>Quick EMUlator (QEMU)</ulink>:
-                    </emphasis> An open-source machine emulator and virtualizer.</para></listitem>
-            </itemizedlist>
+            To generate debug info for packages, you can add dbg-pkgs to
+            EXTRA_IMAGE_FEATURES in local.conf. For example:
+            <literallayout class='monospaced'>
+     EXTRA_IMAGE_FEATURES = "debug-tweaks tools-profile dbg-pkgs"
+            </literallayout>
+            Additionally, in order to generate the right type of
+            debuginfo, we also need to add the following to local.conf:
+            <literallayout class='monospaced'>
+     PACKAGE_DEBUG_SPLIT_STYLE = 'debug-file-directory'
+            </literallayout>
         </para>
     </section>
 </chapter>